Api.Airforce
API REFERENCE

Fins de discussion

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 anthropiques et les réponses anthropiques.

Authentification

Chaque demande nécessite un jeton Bearer (votre clé API Airforce). L'Anthropique 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

Achèvements de chat compatibles OpenAI. Travaille avec le fonctionnaire 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" | "utilisateur" | "assistant" | "outil", contenu }. 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.
stream_optionsobjectOptional{ include_usage : booléen }. Lorsque include_usage est vrai, le bloc SSE final contient le bloc d'utilisation.
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 : "faible" | "moyen" | "haut". Voir « Raisonnement et réflexion ».
thinkingstring | objectOptionalChangement de réflexion entre fournisseurs. "sur" | "éteint" | "auto", ou Anthropic-shape { 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 d'achèvement stable, par ex. "chatcmmpl-abc123".
objectstringOptional"chat.completion" pour les diffusions non diffusées, "chat.completion.chunk" pour les diffusions en continu.
createdintegerOptionalHorodatage Unix (secondes).
modelstringOptionalEcho de l'ID du modèle demandé.
choicesarrayOptionalTableau de candidats à l'achèvement : [{ index, message : { role, content, tool_calls ? }, finish_reason }].
choices[].finish_reasonstringOptional"arrêter" | "longueur" | "appels_outils" | "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"faible" | "moyen" | "haut". OpenAI o1/o3, modèles de raisonnement GPT-5 et tout routeur qui les mappe.
thinkingstring | objectOptional"sur" | "éteint" | "auto" pour une bascule rapide, ou { type: "enabled", budget_tokens: N } pour la forme native d'Anthropic. Cartes vers la pensée étendue de Claude, la pensée Gémeaux et le raisonnement 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 anthropique)

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_content (forme OpenAI) ou comme thinking bloque dans content (Forme anthropique). Les jetons de raisonnement sont facturés et signalés dans usage.completion_tokens_details.reasoning_tokens.


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 assistance visuelle

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

Streaming

Ensemble 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 de messages compatible avec Anthropic. Travaille avec le fonctionnaire @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 : { rôle : "utilisateur" | "assistant", contenu : chaîne | tableau }.
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 anthropique (voir « Streaming »).
toolsarrayOptionalDéfinitions des outils anthropiques : { nom, description, input_schema }. La réponse peut contenir des blocs de contenu tool_use.
tool_choiceobjectOptional{ tapez : "auto" | "n'importe lequel" | "outil", nom ? }.
thinkingobjectOptionalPensée étendue anthropique : { 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 : "texte" | "outil_use" | "pensée", … }.
modelstringOptionalEcho du modèle demandé.
stop_reasonstringOptional"fin_tour" | "max_jetons" | "stop_séquence" | "outil_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"}

Mise en cache rapide

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 soutenir cela.

Modèles avec mise en cache rapide

· 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

Erreurs

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

ParameterTypeRequiredDescription
400invalid_requestOptionalJSON mal formé, champ obligatoire manquant, modèle inconnu.
401authentication_errorOptionalClé API manquante ou invalide.
403permission_errorOptionalLes autorisations de plan ou par clé refusent cette demande.
429rate_limitOptionalTaux de demande ou plafond de jetons quotidien dépassé.
503upstream_errorOptionalToutes les clés en amont du fournisseur demandé ont échoué.
{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

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"