Api.Airforce
API REFERENCE

Complétions de chat

Générez des réponses de chat sur plus de 100 modèles à partir d'une seule API. Compatible avec les complétions de chat OpenAI, les messages Anthropic et les réponses Anthropic.

Airforce parle à la fois les formats wire OpenAI Chat Completions et Anthropic Messages sur le même ensemble de modèles. Choisissez le SDK que vous utilisez déjà et changez seulement la base URL — les modèles non-Claude sont transmis de façon transparente derrière l'une ou l'autre surface.

Cette page couvre l'authentification, les formes de requête et de réponse pour les deux surfaces, le streaming, le tool calling, la vision, le reasoning et le prompt caching. Nouveau ici ? Commencez par l'exemple de base ci-dessous, faites fonctionner un appel, puis ajoutez le streaming, les tools ou le caching une fois que c'est bon.

Authentification

Chaque requête nécessite un jeton Bearer (votre clé API Airforce). L'en-tête Anthropic x-api-key l'en-tête est également accepté sur /v1/messages pour la compatibilité du SDK.

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

POST /v1/chat/completions

Chat Completions compatible OpenAI. Fonctionne avec le SDK officiel openai SDK en remplaçant base_url à https://api.airforce/v1.

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

Corps de la demande

ParameterTypeRequiredDescription
modelstringRequiredID du modèle. Utilisez GET /v1/models pour découvrir les ID disponibles.
messagesarrayRequiredHistorique des conversations. Chaque entrée a { role: "system" | "user" | "assistant" | "tool", content }. Le contenu est une chaîne ou un tableau de blocs de contenu (vision, voir ci-dessous).
max_tokensintegerOptionalNombre maximum de jetons à générer. Plafonné au max_output_tokens du modèle.
temperaturefloatOptionalTempérature d'échantillonnage, 0–2. Lower est plus déterministe. La valeur par défaut dépend du fournisseur en amont.
top_pfloatOptionalÉchantillonnage de noyau. Utilisez soit temperature, soit top_p, pas les deux.
streambooleanOptionalLorsque cela est vrai, la réponse est un flux d'événements envoyés par le serveur. Voir « Diffusion en continu » ci-dessous.
modelsarrayOptionalFallback models (max 3), e.g. ["deepseek-v3.2", "gpt-4o-mini"]. If every channel of the primary model fails, each candidate is tried in order. You are billed for — and response.model reports — the model that actually answered. Unknown or plan-gated candidates are skipped. With the OpenAI SDK pass it via extra_body.
transformsarrayOptionalPrompt transforms. Supported: ["middle-out"] — when the conversation overflows the model's context window, whole messages are dropped from the middle (system prompts, the first message and the most recent turns are kept), so long roleplay or agent histories keep working instead of erroring. Opt-in; off by default.
stream_optionsobjectOptional{ include_usage: boolean }. L’usage est toujours inclus dans le dernier fragment du stream ; ce champ est accepté pour la compatibilité OpenAI mais ne peut pas le désactiver.
stopstring | arrayOptionalJusqu'à 4 séquences d'arrêt. La génération s'arrête dès qu'une est produite.
toolsarrayOptionalDéfinitions de fonctions que le modèle peut appeler. Voir « Appel d'outil » ci-dessous.
tool_choicestring | objectOptional"auto" (par défaut), "none" ou { type: "function", function: { name } } pour forcer un appel spécifique.
response_formatobjectOptional{ type: "json_object" } force le modèle à émettre du JSON valide. Ignoré pour les modèles qui ne le prennent pas en charge.
reasoning_effortstringOptionalProfondeur de raisonnement de style OpenAI o1/o3 : "low" | "medium" | "high". Voir « Raisonnement et réflexion ».
thinkingstring | objectOptionalCommutateur de réflexion inter-fournisseurs. "on" | "off" | "auto", ou la forme Anthropic { type: "enabled", budget_tokens: N }. Voir « Raisonnement et réflexion ».
thinking_budgetintegerOptionalPlafond de jeton pour la trace de raisonnement du modèle (lorsque le fournisseur en expose une).
ignore_defaultsbooleanOptionalIgnorez les paramètres par défaut par modèle enregistrés par l'utilisateur (configurés dans le tableau de bord) pour cette demande.

Exemple de base

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
  }'

Forme de réponse

ParameterTypeRequiredDescription
idstringOptionalID de complétion stable, par ex. "chatcmpl-abc123".
objectstringOptional"chat.completion" pour les réponses non diffusées, "chat.completion.chunk" pour les réponses diffusées en continu.
createdintegerOptionalHorodatage Unix (secondes).
modelstringOptionalEcho de l'ID du modèle demandé.
choicesarrayOptionalTableau de candidats de complétion : [{ index, message: { role, content, tool_calls? }, finish_reason }].
choices[].finish_reasonstringOptional"stop" | "length" | "tool_calls" | "content_filter".
usageobjectOptional{ prompt_tokens, completion_tokens, total_tokens, completion_tokens_details?, prompt_tokens_details?, cache_creation_input_tokens?, cache_creation? }. completion_tokens_details.reasoning_tokens est défini lorsque le modèle a produit une trace de raisonnement. Les champs de cache apparaissent lorsque l'upstream renvoie des informations de cache de prompt : prompt_tokens_details.cached_tokens rapporte les lectures de cache (standard OpenAI), cache_creation_input_tokens agrège les écritures, et cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens donnent la répartition par 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
  }
}

Raisonnement et réflexion

Les modèles prenant en charge le raisonnement étendu exposent une trace de réflexion parallèlement à la sortie régulière. Airforce normalise trois conventions en amont différentes en un seul ensemble de paramètres canoniques qui fonctionnent partout.

Vérifier supports_reasoning: true sur un modèle en GET /v1/models pour savoir quels identifiants acceptent ces paramètres.

Modèles avec support de raisonnement

· live

Paramètres canoniques

ParameterTypeRequiredDescription
reasoning_effortstringOptional"low" | "medium" | "high". OpenAI o1/o3, modèles de raisonnement GPT-5 et tout routeur qui les mappe.
thinkingstring | objectOptional"on" | "off" | "auto" pour une bascule rapide, ou { type: "enabled", budget_tokens: N } pour la forme native d'Anthropic. Correspond à la pensée étendue de Claude, à la réflexion de Gemini et au raisonnement de DeepSeek.
thinking_budgetintegerOptionalNombre maximum de jetons que le modèle peut dépenser en raisonnement avant d'émettre une sortie visible. Miroirs budget_tokens.

Effort de raisonnement (style 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"
  }'

Pensée étendue (style Anthropic)

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}
  }'

La trace du raisonnement elle-même apparaît dans choices[0].message.reasoning (forme OpenAI) ou comme thinking bloque dans content (Format Anthropic). Les jetons de raisonnement sont facturés et signalés dans usage.completion_tokens_details.reasoning_tokens.

Ce détail completion_tokens_details.reasoning_tokens n'est présent que lorsque le fournisseur en amont le rapporte. Sur une réponse en stream, la trace arrive sur delta.reasoning_content à chaque chunk.


Saisie de vision et d'image

Modèles avec supports_vision: true accepter les images intégrées en tant que blocs de contenu. Soit une URL publique, soit une URL de données base64 fonctionne ; les limites de taille dépendent du modèle en amont.

Modèles avec prise en charge de la vision

· 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"}}
      ]
    }]
  }'

Appel d'outil

Modèles avec supports_tools: true peut appeler les fonctions que vous définissez. Le modèle renvoie un tool_calls tableau; vous exécutez l'appel, puis renvoyez le résultat dans un tool message.

Modèles avec prise en charge des appels d'outils

· live

Demande

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"
  }'

Réponse avec appel d'outil

{
  "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"
  }]
}

Suivi du résultat de l'outil

{
  "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\"}"}
  ]
}

Structured outputs

Set response_format to make the model return JSON. Two modes are supported:

  • { "type": "json_object" } — the response is a single valid JSON value.
  • { "type": "json_schema", "json_schema": { "name", "schema", "strict" } } — the model is steered to produce JSON that matches your JSON Schema.
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": "Extract the city and country: I live in Paris, France."}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "location",
        "schema": {
          "type": "object",
          "properties": { "city": {"type": "string"}, "country": {"type": "string"} },
          "required": ["city", "country"]
        }
      }
    }
  }'

Reliability: even when a model wraps its answer in prose or a markdown code fence, Airforce extracts the JSON payload so you always receive parseable content. If no valid JSON can be recovered, the original text is returned unchanged — so the guarantee never makes a response worse. This applies to non-streamed responses; streamed responses are passed through unchanged.


Streaming

Définissez stream: true pour recevoir des achèvements partiels en tant qu'événements envoyés par le serveur. Chaque événement est un morceau JSON ayant la même forme que la réponse non diffusée, sauf message est remplacé par delta. Le flux se termine par 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}
  }'

Format de fil

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 Messages compatible Anthropic. Fonctionne avec le SDK officiel @anthropic-ai/sdk en définissant baseURL à https://api.airforce. Transfère vers OpenAI/Google/etc. de manière transparente pour les modèles non Claude.

POSThttps://api.airforce/v1/messages

Corps de la demande

ParameterTypeRequiredDescription
modelstringRequiredID du modèle (format Anthropic ou alias routé).
messagesarrayRequiredChaque entrée : { role: "user" | "assistant", content: string | array }.
max_tokensintegerRequiredRequis par Anthropic. Plafond de jeton pour la réponse.
systemstring | arrayOptionalInvite du système. Transmettez un tableau de { type : "text", text, cache_control ? } blocs pour marquer les segments de préfixe mis en cache. Voir « Mise en cache des invites ».
temperaturefloatOptional0-1.
top_pfloatOptionalÉchantillonnage de noyau.
top_kintegerOptionalLimitez le pool d’échantillonnage aux K premiers jetons.
stop_sequencesarrayOptionalJusqu'à 4 séquences d'arrêt.
streambooleanOptionalLorsque c'est vrai, émet un flux d'événements SSE de style Anthropic (voir « Streaming »).
fallbacksarrayOptionalFallback models (max 3) in Anthropic form: [{"model": "gpt-4o-mini"}]. If every channel of the primary model fails, each candidate is tried in order; you are billed for — and the response model field reports — the model that actually answered. A plain models string array is accepted too.
toolsarrayOptionalDéfinitions des outils Anthropic : { name, description, input_schema }. La réponse peut contenir des blocs de contenu tool_use.
tool_choiceobjectOptional{ type: "auto" | "any" | "tool", name? }.
thinkingobjectOptionalPensée étendue Anthropic : { type : "enabled", budget_tokens : N }.

Exemple

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!"}
    ]
  }'

Forme de réponse

ParameterTypeRequiredDescription
idstringOptionalID du message, par ex. "msg_01ABCxyz".
typestringOptionalToujours "message".
rolestringOptionalToujours "assistant".
contentarrayOptionalTableau de blocs de contenu : { type: "text" | "tool_use" | "thinking", … }.
modelstringOptionalEcho du modèle demandé.
stop_reasonstringOptional"end_turn" | "max_tokens" | "stop_sequence" | "tool_use".
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. Les champs de cache apparaissent lorsque le cache de prompt a été utilisé. cache_creation.ephemeral_5m_input_tokens et ephemeral_1h_input_tokens donnent la répartition des écritures par TTL.

Événements en streaming

Anthropic SSE utilise des événements nommés au lieu de morceaux JSON uniques. Chaque événement a à la fois un event: nom et un data: Charge utile 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"}

POST /v1/messages/count_tokens

Anthropic-compatible token counting. Send the same system / messages / tools you would pass to /v1/messages and get an input-token estimate back without running the model — nothing is billed.

POSThttps://api.airforce/v1/messages/count_tokens
curl https://api.airforce/v1/messages/count_tokens \
  -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",
    "system": "You are a helpful assistant.",
    "messages": [{"role": "user", "content": "Hello, Claude!"}]
  }'

# → {"input_tokens": 34}

The count is a fast character-based estimate (about 4 characters per token) over system, messages and tools — close enough for context-budget checks, not an exact tokenizer run.


Mise en cache des prompts

Sur /v1/messages avec les modèles Claude, marquer un préfixe comme mis en cache en passant system comme un tableau de blocs où le segment mis en cache transporte cache_control: { type: "ephemeral" }. Les requêtes ultérieures commençant par le même préfixe facturent le tarif de lecture du cache le moins cher. Modèles avec supports_caching: true dans /v1/models prennent cela en charge.

Modèles avec mise en cache des prompts

· 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?"}
  ]
}

Comment les compteurs de cache sont rapportés dans la réponse

Les compteurs de tokens de cache sont transmis dans la forme native de chaque format, de sorte que les SDK (openai, @anthropic-ai/sdk, @google/genai) les lisent sans code personnalisé. Les champs sont omis lorsque la valeur est zéro, gardant les réponses non mises en cache légères.

/v1/chat/completions (forme 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 (forme 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 (forme Gemini)

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

Où le cache s’applique

Les marqueurs cache_control explicites sont pris en compte sur /v1/messages et /v1/chat/completions pour les modèles Claude — placez-les sur les blocs de contenu system ou message. Beaucoup d’autres fournisseurs (famille OpenAI, DeepSeek, Gemini) mettent en cache automatiquement : vous n’envoyez aucun marqueur et voyez simplement cached_tokens dans la réponse dès qu’un préfixe assez long est réutilisé.

Durée du cache : 5 minutes ou 1 heure

Un préfixe en cache vit 5 minutes par défaut et le minuteur se réinitialise à chaque accès. Pour un préfixe plus durable, ajoutez ttl: "1h" au marqueur. La réponse indique chaque TTL séparément sous cache_creation.

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

Exemple : d’abord l’écriture, puis la lecture

Envoyez exactement la même requête deux fois (l’exemple de cache ci-dessus). Le premier appel qui voit le préfixe paie une écriture de cache unique ; les appels identiques dans la TTL paient la lecture de cache bien moins chère.

Premier appel — écriture de cache (extrait usage) :

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

Deuxième appel identique dans la TTL — lecture de cache :

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

Limites et coût

  • Claude exige un préfixe minimum (environ 1024 tokens ; plus pour certains modèles). Les préfixes plus courts ne sont tout simplement pas mis en cache.
  • Jusqu’à 4 points de cache par requête, et le préfixe en cache doit être identique octet pour octet entre les appels — même un changement d’un caractère manque le cache.
  • Les écritures de cache coûtent plus que l’entrée normale (5m ≈ 1,25×, 1h ≈ 2×) ; les lectures coûtent bien moins (≈ 0,1×). Voir les prix de cache de chaque modèle sur la page tarifs.

POST /v1/responses

Surface OpenAI Responses-API pour les conversations à état. Même authentification Bearer/x-api-key. Les compteurs de cache apparaissent comme input_tokens_details.cached_tokens (lecture) plus le cache_creation_input_tokens à plat + cache_creation.ephemeral_* (écritures) pour la parité avec /v1/chat/completions.

POSThttps://api.airforce/v1/responses

POST /v1beta/models/{model}:generateContent

Google Gemini-compatible endpoint. Works with the official @google/genai SDK and the Gemini CLI by pointing the base URL at https://api.airforce/v1beta. Any routed model works — requests are translated to and from the native Gemini shape, and the model is taken from the URL path (not the body).

POSThttps://api.airforce/v1beta/models/{model}:generateContent

Authentication

Pass your Airforce API key any of the three ways Google clients use:

# 1) query parameter (Google default)
?key=sk-air-YOUR_API_KEY

# 2) header
x-goog-api-key: sk-air-YOUR_API_KEY

# 3) bearer token
Authorization: Bearer sk-air-YOUR_API_KEY

Request body

ParameterTypeRequiredDescription
contentsarrayRequiredConversation turns. Each: { role: "user" | "model", parts: [...] }. A part is { text }, { functionCall: { name, args } }, or { functionResponse: { name, response } }. "model" is Gemini's term for the assistant role.
systemInstructionobjectOptionalSystem prompt: { parts: [{ text }] }.
generationConfigobjectOptional{ temperature, maxOutputTokens, topP, stopSequences } — mapped to the canonical sampling parameters.
toolsarrayOptionalTool definitions: [{ functionDeclarations: [{ name, description, parameters }] }]. functionDeclarations are flattened across entries.
toolConfigobjectOptionalTool-choice control: { functionCallingConfig: { mode: "AUTO" | "ANY" | "NONE" } }. ANY forces a call, NONE disables tools.

Example

curl "https://api.airforce/v1beta/models/gemini-3.1-pro:generateContent" \
  -H "x-goog-api-key: sk-air-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "What is the capital of France?"}]}
    ],
    "systemInstruction": {"parts": [{"text": "You are a helpful assistant."}]},
    "generationConfig": {"temperature": 0.7, "maxOutputTokens": 256}
  }'

Response shape

ParameterTypeRequiredDescription
candidatesarrayOptionalGenerated turns: [{ content: { role: "model", parts }, finishReason, index }]. Only the first candidate is populated.
candidates[].finishReasonstringOptional"STOP" | "MAX_TOKENS" | "SAFETY" | "OTHER".
usageMetadataobjectOptional{ promptTokenCount, candidatesTokenCount, totalTokenCount, cachedContentTokenCount? }. cachedContentTokenCount appears when the upstream reported a cache read.
modelVersionstringOptionalEcho of the requested model.
{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{"text": "The capital of France is Paris."}]
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 16,
    "candidatesTokenCount": 8,
    "totalTokenCount": 24
  },
  "modelVersion": "gemini-3.1-pro"
}

POST /v1beta/models/{model}:streamGenerateContent

Streaming uses the :streamGenerateContent action and returns Server-Sent Events. Each data: line is a full Gemini-shaped chunk (not a delta object); the final chunk carries usageMetadata.

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"The capital"}]},"index":0}],"modelVersion":"gemini-3.1-pro"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":" is Paris."}]},"index":0}],"modelVersion":"gemini-3.1-pro"}

data: {"candidates":[{"content":{"role":"model","parts":[]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":16,"candidatesTokenCount":8,"totalTokenCount":24}}

List models

The catalog is also exposed in Gemini Model-resource shape so Google clients can enumerate models.

curl https://api.airforce/v1beta/models

Notes: the base URL is https://api.airforce/v1beta (or /v1), not Google's host. The model name comes from the URL path, not the request body. Only the first candidate is returned, and a subset of Gemini fields is translated — safetySettings and cachedContent are currently ignored. Billing, rate limits and smart routing apply exactly as on /v1/chat/completions.


Erreurs

Airforce renvoie des codes d'état HTTP standard et une enveloppe d'erreur uniforme pour les deux points de terminaison.

ParameterTypeRequiredDescription
400invalid_request_errorOptionalJSON mal formé, champ obligatoire manquant, modèle inconnu.
401invalid_request_error / auth_requiredOptionalClé API manquante ou invalide.
402insufficient_quotaOptionalLe modèle nécessite un abonnement actif ou un solde Pay-as-you-Go positif.
403model_access_denied / insufficient_scopeOptionalLes autorisations de plan ou par clé refusent cette demande.
404model_not_foundOptionalLe modèle demandé n’existe pas ou vous n’y avez pas accès.
429rate_limit_errorOptionalTaux de demande ou plafond de jetons quotidien dépassé.
503api_error / moderation_unavailableOptionalToutes les clés en amont du fournisseur demandé ont échoué.
{
  "error": {
    "message": "The requested model does not exist or you do not have access to it.",
    "type": "model_not_found",
    "param": null,
    "code": "404"
  }
}

Le slug descriptif se trouve dans type. code est le statut HTTP sous forme de chaîne (p. ex. "404"), et param est null sauf en cas d'erreurs de validation de plage de paramètres, où il nomme le paramètre fautif.

Découvrez les modèles

Consultez la liste complète des ID de modèle et leurs indicateurs de capacité (vision, outils, raisonnement, mise en cache, longueur du contexte, …) sur /docs/api/models.

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