Api.Airforce
API REFERENCE

Conclusões de bate-papo

Gere respostas de chat em mais de 100 modelos a partir de uma API. Drop-in compatível com conclusões de bate-papo OpenAI, mensagens antrópicas e respostas antrópicas.

Autenticação

Cada solicitação precisa de um token de portador (sua chave de API do Airforce). O Antrópico x-api-key cabeçalho também é aceito em /v1/messages para compatibilidade com SDK.

Authorization: Bearer sk-air-YOUR_API_KEY
# alt for /v1/messages:
x-api-key: sk-air-YOUR_API_KEY

POST /v1/chat/completions

Conclusões de bate-papo compatíveis com OpenAI. Trabalha com o oficial openai SDK por substituição base_url para https://api.airforce/v1.

POSThttps://api.airforce/v1/chat/completions

Solicitar corpo

ParameterTypeRequiredDescription
modelstringRequiredID do modelo. Use GET /v1/models para descobrir os IDs disponíveis.
messagesarrayRequiredHistórico de conversas. Cada entrada tem { role: "system" | "usuário" | "assistente" | "ferramenta", conteúdo }. O conteúdo é uma string ou uma matriz de blocos de conteúdo (visão, veja abaixo).
max_tokensintegerOptionalNúmero máximo de tokens a serem gerados. Limitado aos max_output_tokens do modelo.
temperaturefloatOptionalTemperatura de amostragem, 0–2. Menor é mais determinístico. O padrão depende do provedor upstream.
top_pfloatOptionalAmostragem de núcleo. Use temperatura ou top_p, não ambos.
streambooleanOptionalQuando verdadeiro, a resposta é um fluxo de eventos enviados pelo servidor. Consulte "Streaming" abaixo.
stream_optionsobjectOptional{ include_usage: booleano }. Quando include_usage for verdadeiro, o bloco SSE final carrega o bloco de uso.
stopstring | arrayOptionalAté 4 sequências de parada. A geração é interrompida assim que uma é produzida.
toolsarrayOptionalDefinições de função que o modelo pode chamar. Consulte "Chamada de ferramenta" abaixo.
tool_choicestring | objectOptional"auto" (padrão), "none" ou { type: "function", function: { name } } para forçar uma chamada específica.
response_formatobjectOptional{ type: "json_object" } força o modelo a emitir JSON válido. Ignorado para modelos que não o suportam.
reasoning_effortstringOptionalProfundidade de raciocínio estilo OpenAI o1/o3: "baixa" | "médio" | "alto". Consulte "Raciocínio e pensamento".
thinkingstring | objectOptionalMudança de pensamento entre provedores. "ligado" | "desligado" | "auto" ou formato antrópico { type: "enabled", budget_tokens: N }. Consulte "Raciocínio e pensamento".
thinking_budgetintegerOptionalLimite de token para o rastreamento de raciocínio do modelo (quando o provedor expõe um).
ignore_defaultsbooleanOptionalIgnore os parâmetros padrão por modelo salvos do usuário (configurados no painel) para esta solicitação.

Exemplo básico

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is the capital of France?"}
    ],
    "max_tokens": 200,
    "temperature": 0.7
  }'

Forma de resposta

ParameterTypeRequiredDescription
idstringOptionalID de conclusão estável, por ex. "chatcmpl-abc123".
objectstringOptional"chat.completion" para não transmitido, "chat.completion.chunk" para transmitido.
createdintegerOptionalCarimbo de data/hora Unix (segundos).
modelstringOptionalEco do ID do modelo solicitado.
choicesarrayOptionalMatriz de candidatos à conclusão: [{ index, message: { role, content, tool_calls? }, razão_de_acabamento }].
choices[].finish_reasonstringOptional"parar" | "comprimento" | "chamadas_ferramentas" | "filtro_conteúdo".
usageobjectOptional{ prompt_tokens, completion_tokens, total_tokens, completion_tokens_details?, prompt_tokens_details?, cache_creation_input_tokens?, cache_creation? }. completion_tokens_details.reasoning_tokens é definido quando o modelo produziu um rastro de raciocínio. Os campos de cache aparecem quando o upstream retornou informações de cache de prompt: prompt_tokens_details.cached_tokens reporta leituras de cache (padrão OpenAI), cache_creation_input_tokens agrega as escritas, e cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens dão a divisão por TTL.
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-5.1-chat",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "The capital of France is Paris."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 8,
    "total_tokens": 28
  }
}

Raciocínio e pensamento

Os modelos que suportam o raciocínio estendido expõem um traço de pensamento juntamente com a saída regular. A Força Aérea normaliza três convenções upstream diferentes em um conjunto de parâmetros canônicos que funcionam em qualquer lugar.

Verificar supports_reasoning: true em um modelo em GET /v1/models para saber quais IDs aceitam esses parâmetros.

Modelos com suporte de raciocínio

· live

Parâmetros canônicos

ParameterTypeRequiredDescription
reasoning_effortstringOptional"baixo" | "médio" | "alto". OpenAI o1/o3, modelos de raciocínio GPT-5 e qualquer roteador que mapeie para eles.
thinkingstring | objectOptional"ligado" | "desligado" | "auto" para uma alternância rápida ou { type: "enabled", budget_tokens: N } para a forma antrópica nativa. Mapas para o pensamento estendido de Claude, o pensamento de Gêmeos e o raciocínio DeepSeek.
thinking_budgetintegerOptionalMáximo de tokens que o modelo pode gastar no raciocínio antes de emitir uma saída visível. Espelha budget_tokens.

Esforço de raciocínio (estilo OpenAI)

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o3-mini",
    "messages": [{"role": "user", "content": "Prove the Pythagorean theorem."}],
    "reasoning_effort": "high"
  }'

Pensamento estendido (estilo antrópico)

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "messages": [{"role": "user", "content": "Plan a 7-day Italy trip."}],
    "thinking": {"type": "enabled", "budget_tokens": 4000}
  }'

O próprio traço de raciocínio aparece em choices[0].message.reasoning_content (formato OpenAI) ou como thinking blocos em content (Forma antrópica). Os tokens de raciocínio são cobrados e relatados em usage.completion_tokens_details.reasoning_tokens.


Entrada de visão e imagem

Modelos com supports_vision: true aceite imagens incorporadas como blocos de conteúdo. Uma URL pública ou uma URL de dados base64 funcionam; os limites de tamanho dependem do modelo upstream.

Modelos com suporte de visão

· live
curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What is in this image?"},
        {"type": "image_url", "image_url": {"url": "https://example.com/cat.jpg"}}
      ]
    }]
  }'

Chamada de ferramenta

Modelos com supports_tools: true pode chamar funções que você definir. O modelo retorna um tool_calls variedade; você executa a chamada e envia o resultado de volta em um tool mensagem.

Modelos com suporte para chamada de ferramenta

· live

Solicitar

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "What is the weather in Paris?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "City name"}
          },
          "required": ["location"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Resposta com chamada de ferramenta

{
  "id": "chatcmpl-abc123",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"location\":\"Paris\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Acompanhamento com resultado da ferramenta

{
  "model": "gpt-5.1-chat",
  "messages": [
    {"role": "user", "content": "What is the weather in Paris?"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_1",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"location\":\"Paris\"}"}
      }]
    },
    {"role": "tool", "tool_call_id": "call_1", "content": "{\"temp_c\": 14, \"sky\": \"cloudy\"}"}
  ]
}

Transmissão

Definir stream: true para receber conclusões parciais como eventos enviados pelo servidor. Cada evento é um pedaço JSON com o mesmo formato da resposta não transmitida, exceto message é substituído por delta. O fluxo termina com data: [DONE].

curl https://api.airforce/v1/chat/completions \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.1-chat",
    "messages": [{"role": "user", "content": "Write a haiku about Berlin."}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Formato de fio

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"content":"Cold "},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{"content":"stone "},"finish_reason":null}]}


data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1710000000,"model":"gpt-5.1-chat","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":17,"total_tokens":29}}

data: [DONE]

POST /v1/messages

API de mensagens compatível com Antrópico. Trabalha com o oficial @anthropic-ai/sdk configurando baseURL para https://api.airforce. Encaminha para OpenAI/Google/etc. transparentemente para modelos não-Claude.

POSThttps://api.airforce/v1/messages

Solicitar corpo

ParameterTypeRequiredDescription
modelstringRequiredID do modelo (formato antrópico ou alias roteado).
messagesarrayRequiredCada entrada: { role: "user" | "assistente", conteúdo: string | variedade }.
max_tokensintegerRequiredExigido pela Antrópico. Limite de token para a resposta.
systemstring | arrayOptionalAlerta do sistema. Passe um array de { type: "text", text, cache_control? } blocos para marcar segmentos de prefixo em cache. Consulte "Cache de prompts".
temperaturefloatOptional0–1.
top_pfloatOptionalAmostragem de núcleo.
top_kintegerOptionalLimite o pool de amostragem aos principais tokens.
stop_sequencesarrayOptionalAté 4 sequências de parada.
streambooleanOptionalQuando verdadeiro, emite fluxo de eventos SSE no estilo antrópico (consulte "Streaming").
toolsarrayOptionalDefinições de ferramentas antrópicas: { nome, descrição, esquema_de_entrada }. A resposta pode conter blocos de conteúdo tool_use.
tool_choiceobjectOptional{tipo: "automático" | "qualquer" | "ferramenta", nome? }.
thinkingobjectOptionalPensamento antrópico estendido: { type: "enabled", budget_tokens: N }.

Exemplo

curl https://api.airforce/v1/messages \
  -H "x-api-key: sk-air-YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4.6",
    "max_tokens": 256,
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Forma de resposta

ParameterTypeRequiredDescription
idstringOptionalID da mensagem, por ex. "msg_01ABCxyz".
typestringOptionalSempre "mensagem".
rolestringOptionalSempre "assistente".
contentarrayOptionalMatriz de blocos de conteúdo: { type: "text" | "uso_ferramenta" | "pensamento", … }.
modelstringOptionalEco do modelo solicitado.
stop_reasonstringOptional"fim_turno" | "max_tokens" | "stop_sequence" | "uso_ferramenta".
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. Os campos de cache aparecem quando o cache de prompt foi usado. cache_creation.ephemeral_5m_input_tokens e ephemeral_1h_input_tokens dão a divisão de escrita por TTL.

Transmissão de eventos

O Antrópico SSE usa eventos nomeados em vez de blocos JSON únicos. Cada evento tem um event: nome e um data: Carga útil JSON.

event: message_start
data: {"type":"message_start","message":{"id":"msg_01","role":"assistant","content":[],"model":"claude-sonnet-4.6","stop_reason":null,"usage":{"input_tokens":12,"output_tokens":1}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":17}}

event: message_stop
data: {"type":"message_stop"}

Cache de prompt

Sobre /v1/messages com modelos Claude, marque um prefixo como armazenado em cache passando system como uma matriz de blocos onde o segmento em cache carrega cache_control: { type: "ephemeral" }. As solicitações subsequentes que começam com o mesmo prefixo cobram a taxa de leitura de cache mais barata. Modelos com supports_caching: true em /v1/models apoie isso.

Modelos com cache imediato

· live
{
  "model": "claude-sonnet-4.6",
  "max_tokens": 1024,
  "system": [
    {"type": "text", "text": "You are a senior staff engineer at Airforce."},
    {
      "type": "text",
      "text": "<repository-snapshot>...</repository-snapshot>",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [
    {"role": "user", "content": "Where is rate limiting enforced?"}
  ]
}

Como as contagens de cache são reportadas na resposta

Os conteúdos de tokens de cache são passados na forma nativa de cada formato, então SDKs (openai, @anthropic-ai/sdk, @google/genai) os leem sem código personalizado. Os campos são omitidos quando o valor é zero, mantendo respostas não-cacheadas enxutas.

/v1/chat/completions (forma OpenAI)

"usage": {
  "prompt_tokens": 2104,
  "completion_tokens": 147,
  "total_tokens": 2251,
  "prompt_tokens_details": { "cached_tokens": 1980 },
  "cache_creation_input_tokens": 124,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 124,
    "ephemeral_1h_input_tokens": 0
  }
}

/v1/messages (forma Anthropic)

"usage": {
  "input_tokens": 2104,
  "output_tokens": 147,
  "cache_read_input_tokens": 1980,
  "cache_creation_input_tokens": 124,
  "cache_creation": {
    "ephemeral_5m_input_tokens": 124,
    "ephemeral_1h_input_tokens": 0
  }
}

/v1beta/.../generateContent (forma Gemini)

"usageMetadata": {
  "promptTokenCount": 2104,
  "candidatesTokenCount": 147,
  "totalTokenCount": 2251,
  "cachedContentTokenCount": 1980
}

Onde o cache se aplica

Marcadores cache_control explícitos são respeitados em /v1/messages e /v1/chat/completions para modelos Claude — coloque-os em blocos de conteúdo system ou message. Muitos outros provedores (família OpenAI, DeepSeek, Gemini) fazem cache automaticamente: você não envia marcadores e simplesmente vê cached_tokens na resposta quando um prefixo longo o suficiente é reutilizado.

Duração do cache: 5 minutos ou 1 hora

Um prefixo em cache vive 5 minutos por padrão e o timer é renovado a cada acerto. Para um prefixo mais duradouro, adicione ttl: "1h" ao marcador. A resposta informa cada TTL separadamente em cache_creation.

"cache_control": { "type": "ephemeral", "ttl": "1h" }

Exemplo: primeiro write, depois read

Envie exatamente a mesma requisição duas vezes (o exemplo de cache acima). A primeira chamada que vê o prefixo paga um write de cache único; chamadas idênticas dentro da TTL pagam o read de cache muito mais barato.

Primeira chamada — write de cache (trecho de usage):

"usage": {
  "input_tokens": 2104,
  "output_tokens": 12,
  "cache_creation_input_tokens": 1980,
  "cache_read_input_tokens": 0
}

Segunda chamada idêntica dentro da TTL — read de cache:

"usage": {
  "input_tokens": 2104,
  "output_tokens": 12,
  "cache_creation_input_tokens": 0,
  "cache_read_input_tokens": 1980
}

Limites e custo

  • O Claude exige um prefixo mínimo cacheável (cerca de 1024 tokens; mais em alguns modelos). Prefixos mais curtos simplesmente não são cacheados.
  • Até 4 breakpoints de cache por requisição, e o prefixo em cache deve ser idêntico byte a byte entre chamadas — até uma mudança de um caractere erra o cache.
  • Writes de cache custam mais que a entrada normal (5m ≈ 1,25×, 1h ≈ 2×); reads custam muito menos (≈ 0,1×). Veja os preços de cache de cada modelo na página de preços.

POST /v1/responses

Superfície OpenAI Responses-API para conversas com estado. Mesma autenticação Bearer/x-api-key. As contagens de cache aparecem como input_tokens_details.cached_tokens (leitura) mais cache_creation_input_tokens plano + cache_creation.ephemeral_* (escritas) para paridade com /v1/chat/completions.

POSThttps://api.airforce/v1/responses

Erros

Airforce retorna códigos de status HTTP padrão e um envelope de erro uniforme para ambos os endpoints.

ParameterTypeRequiredDescription
400invalid_requestOptionalJSON malformado, campo obrigatório ausente, modelo desconhecido.
401authentication_errorOptionalChave de API ausente ou inválida.
403permission_errorOptionalAs permissões planejadas ou por chave negam essa solicitação.
429rate_limitOptionalTaxa de solicitação ou limite diário de token excedido.
503upstream_errorOptionalTodas as chaves upstream do provedor solicitado falharam.
{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

Descubra modelos

Veja a lista completa de IDs de modelo e seus sinalizadores de capacidade (visão, ferramentas, raciocínio, cache, comprimento de contexto,…) em /docs/api/models.

curl https://api.airforce/v1/models \
  -H "Authorization: Bearer sk-air-YOUR_API_KEY"