Completamenti della chat
Genera risposte chat su oltre 100 modelli da un'unica API. Drop-in compatibile con i completamenti della chat OpenAI, i messaggi antropici e le risposte antropiche.
Autenticazione
Ogni richiesta necessita di un token Bearer (la tua chiave API Airforce). L'Antropico x-api-key viene accettata anche l'intestazione /v1/messages per la compatibilità dell'SDK.
Authorization: Bearer sk-air-YOUR_API_KEY
# alt for /v1/messages:
x-api-key: sk-air-YOUR_API_KEYPOST /v1/chat/completions
Completamenti chat compatibili con OpenAI. Funziona con il funzionario openai SDK eseguendo l'override base_url A https://api.airforce/v1.
https://api.airforce/v1/chat/completionsRichiedi corpo
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Required | ID modello. Utilizza GET /v1/models per scoprire gli ID disponibili. |
| messages | array | Required | Cronologia delle conversazioni. Ogni voce ha {ruolo: "sistema" | "utente" | "assistente" | "strumento", contenuto }. Il contenuto è una stringa o un array di blocchi di contenuto (visione, vedere sotto). |
| max_tokens | integer | Optional | Numero massimo di token da generare. Limitato ai max_output_tokens del modello. |
| temperature | float | Optional | Temperatura di campionamento, 0–2. Il valore inferiore è più deterministico. L'impostazione predefinita dipende dal provider upstream. |
| top_p | float | Optional | Campionamento del nucleo. Utilizza temperature o top_p, non entrambi. |
| stream | boolean | Optional | Quando è vero, la risposta è un flusso di eventi inviati dal server. Vedere "Streaming" di seguito. |
| stream_options | object | Optional | { include_usage: booleano }. Quando include_usage è vero, il blocco SSE finale trasporta il blocco di utilizzo. |
| stop | string | array | Optional | Fino a 4 sequenze di arresto. La generazione si interrompe non appena ne viene prodotta una. |
| tools | array | Optional | Definizioni di funzioni che il modello può chiamare. Vedere "Chiamata utensile" di seguito. |
| tool_choice | string | object | Optional | "auto" (predefinito), "none" o { tipo: "funzione", funzione: { nome } } per forzare una chiamata specifica. |
| response_format | object | Optional | { type: "json_object" } forza il modello a emettere JSON valido. Ignorato per i modelli che non lo supportano. |
| reasoning_effort | string | Optional | Profondità di ragionamento in stile OpenAI o1/o3: "bassa" | "medio" | "alto". Vedi "Ragionamento e pensiero". |
| thinking | string | object | Optional | Commutazione del pensiero tra provider. "acceso" | "spento" | "auto", o forma antropica {tipo: "abilitato", budget_tokens: N}. Vedi "Ragionamento e pensiero". |
| thinking_budget | integer | Optional | Token cap per la traccia del ragionamento del modello (quando il provider ne espone uno). |
| ignore_defaults | boolean | Optional | Ignora i parametri predefiniti per modello salvati dall'utente (configurati nel dashboard) per questa richiesta. |
Esempio di 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
}'Forma della risposta
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Optional | ID di completamento stabile, ad es. "chatcmpl-abc123". |
| object | string | Optional | "chat.completion" per non in streaming, "chat.completion.chunk" per in streaming. |
| created | integer | Optional | Timestamp Unix (secondi). |
| model | string | Optional | Eco dell'ID del modello richiesto. |
| choices | array | Optional | Matrice di candidati al completamento: [{ indice, messaggio: { ruolo, contenuto, tool_calls? }, motivo_finitura }]. |
| choices[].finish_reason | string | Optional | "fermare" | "lunghezza" | "chiamate_strumento" | "filtro_contenuto". |
| usage | object | Optional | { prompt_tokens, completion_tokens, total_tokens, completion_tokens_details?, prompt_tokens_details?, cache_creation_input_tokens?, cache_creation? }. completion_tokens_details.reasoning_tokens viene impostato quando il modello ha prodotto una traccia di ragionamento. I campi cache compaiono quando l'upstream ha restituito informazioni sul prompt caching: prompt_tokens_details.cached_tokens riporta le letture cache (standard OpenAI), cache_creation_input_tokens aggrega le scritture, e cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens forniscono la suddivisione per 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
}
}Ragionamento e pensiero
I modelli che supportano il ragionamento esteso espongono una traccia del pensiero accanto all'output regolare. L'Airforce normalizza tre diverse convenzioni a monte in un insieme di parametri canonici che funzionano ovunque.
Controllo supports_reasoning: true su un modello in GET /v1/models per sapere quali ID accettano questi parametri.
Modelli con supporto del ragionamento
…· liveParametri canonici
| Parameter | Type | Required | Description |
|---|---|---|---|
| reasoning_effort | string | Optional | "basso" | "medio" | "alto". OpenAI o1/o3, modelli di ragionamento GPT-5 e qualsiasi router che sia mappato su di essi. |
| thinking | string | object | Optional | "acceso" | "spento" | "auto" per un passaggio rapido o { type: "enabled", budget_tokens: N } per la forma nativa antropica. Si associa al pensiero esteso di Claude, al pensiero dei Gemelli e al ragionamento DeepSeek. |
| thinking_budget | integer | Optional | Numero massimo di token che il modello può spendere nel ragionamento prima di emettere un output visibile. Specchia budget_tokens. |
Sforzo di ragionamento (stile 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"
}'Pensiero esteso (stile antropico)
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 traccia stessa del ragionamento appare in choices[0].message.reasoning_content (forma OpenAI) o come thinking blocchi dentro content (Forma antropica). I gettoni ragionamento vengono fatturati e riportati usage.completion_tokens_details.reasoning_tokens.
Input di visione e immagine
Modelli con supports_vision: true accettare immagini incorporate come blocchi di contenuto. Funziona sia un URL pubblico che un URL di dati base64; i limiti di dimensione dipendono dal modello a monte.
Modelli con supporto visivo
…· livecurl 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"}}
]
}]
}'Chiamata dello strumento
Modelli con supports_tools: true può chiamare le funzioni definite dall'utente. Il modello restituisce a tool_calls vettore; esegui la chiamata, quindi invii il risultato in a tool messaggio.
Modelli con supporto per la chiamata degli strumenti
…· liveRichiesta
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"
}'Risposta con chiamata utensile
{
"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"
}]
}Follow-up con il risultato dello strumento
{
"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
Impostato stream: true per ricevere completamenti parziali come eventi inviati dal server. Ogni evento è un blocco JSON con la stessa forma della risposta non trasmessa in streaming, tranne message è sostituito da delta. Lo streaming termina con 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 filo
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 di messaggistica compatibile con gli antropici. Funziona con il funzionario @anthropic-ai/sdk impostando baseURL A https://api.airforce. Inoltra a OpenAI/Google/ecc. in modo trasparente per i modelli non Claude.
https://api.airforce/v1/messagesRichiedi corpo
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Required | ID modello (formato Anthropic o alias instradato). |
| messages | array | Required | Ogni voce: { ruolo: "utente" | "assistente", contenuto: stringa | vettore }. |
| max_tokens | integer | Required | Richiesto da Anthropic. Limite token per la risposta. |
| system | string | array | Optional | Richiesta di sistema. Passa un array di {tipo: "testo", testo, cache_control? } blocchi per contrassegnare i segmenti di prefisso memorizzati nella cache. Vedere "Messa in cache dei prompt". |
| temperature | float | Optional | 0–1. |
| top_p | float | Optional | Campionamento del nucleo. |
| top_k | integer | Optional | Limita il pool di campionamento ai token top-K. |
| stop_sequences | array | Optional | Fino a 4 sequenze di arresto. |
| stream | boolean | Optional | Quando è vero, emette un flusso di eventi SSE in stile antropico (vedi "Streaming"). |
| tools | array | Optional | Definizioni degli strumenti antropici: { name, description, input_schema }. La risposta può contenere blocchi di contenuto tool_use. |
| tool_choice | object | Optional | { tipo: "automatico" | "qualsiasi" | "strumento", nome? }. |
| thinking | object | Optional | Pensiero antropico esteso: { type: "enabled", budget_tokens: N }. |
Esempio
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 della risposta
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Optional | ID del messaggio, ad es. "msg_01ABCxyz". |
| type | string | Optional | Sempre "messaggio". |
| role | string | Optional | Sempre "assistente". |
| content | array | Optional | Matrice di blocchi di contenuto: {tipo: "testo" | "uso_strumento" | "pensare", … }. |
| model | string | Optional | Eco del modello richiesto. |
| stop_reason | string | Optional | "fine_turno" | "max_token" | "stop_sequenza" | "strumento_uso". |
| usage | object | Optional | { input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. I campi cache compaiono quando è stato usato il prompt caching. cache_creation.ephemeral_5m_input_tokens e ephemeral_1h_input_tokens forniscono la suddivisione delle scritture per TTL. |
Eventi in streaming
Anthropic SSE utilizza eventi denominati anziché blocchi JSON una tantum. Ogni evento ha sia un event: nome e a data: Carico 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"}Memorizzazione nella cache immediata
SU /v1/messages con i modelli Claude, contrassegna un prefisso come memorizzato nella cache passando system come un array di blocchi in cui trasporta il segmento memorizzato nella cache cache_control: { type: "ephemeral" }. Le richieste successive che iniziano con lo stesso prefisso addebitano la tariffa di lettura della cache più economica. Modelli con supports_caching: true In /v1/models sostenere questo.
Modelli con memorizzazione nella cache immediata
…· 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?"}
]
}Come vengono riportati i conteggi cache nella risposta
I conteggi dei token cache vengono passati nella forma nativa di ogni formato, così gli SDK (openai, @anthropic-ai/sdk, @google/genai) li leggono senza codice personalizzato. I campi vengono omessi quando il valore è zero, mantenendo leggere le risposte non cached.
/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
}Dove si applica la cache
I marcatori cache_control espliciti sono rispettati su /v1/messages e /v1/chat/completions per i modelli Claude — mettili sui blocchi di contenuto system o message. Molti altri provider (famiglia OpenAI, DeepSeek, Gemini) mettono in cache automaticamente: non invii marcatori e vedi semplicemente cached_tokens nella risposta quando un prefisso abbastanza lungo viene riutilizzato.
Durata della cache: 5 minuti o 1 ora
Un prefisso in cache vive 5 minuti per impostazione predefinita e il timer si rinnova a ogni hit. Per un prefisso più duraturo, aggiungi ttl: "1h" al marcatore. La risposta riporta ogni TTL separatamente sotto cache_creation.
"cache_control": { "type": "ephemeral", "ttl": "1h" }Esempio: prima write, poi read
Invia esattamente la stessa richiesta due volte (l’esempio di cache sopra). La prima chiamata che vede il prefisso paga una write di cache una tantum; le chiamate identiche entro la TTL pagano la read di cache molto più economica.
Prima chiamata — write di cache (estratto usage):
"usage": {
"input_tokens": 2104,
"output_tokens": 12,
"cache_creation_input_tokens": 1980,
"cache_read_input_tokens": 0
}Seconda chiamata identica entro la TTL — read di cache:
"usage": {
"input_tokens": 2104,
"output_tokens": 12,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 1980
}Limiti e costo
- Claude richiede un prefisso minimo memorizzabile (circa 1024 token; di più per alcuni modelli). I prefissi più corti semplicemente non vengono messi in cache.
- Fino a 4 breakpoint di cache per richiesta, e il prefisso in cache deve essere identico byte per byte tra le chiamate — anche una modifica di un carattere manca la cache.
- Le write di cache costano più dell’input normale (5m ≈ 1,25×, 1h ≈ 2×); le read costano molto meno (≈ 0,1×). Vedi i prezzi di cache di ogni modello nella pagina prezzi.
POST /v1/responses
Superficie OpenAI Responses-API per conversazioni stateful. Stessa autenticazione Bearer/x-api-key. I conteggi cache compaiono come input_tokens_details.cached_tokens (lettura) più cache_creation_input_tokens flat + cache_creation.ephemeral_* (scritture) per parità con /v1/chat/completions.
https://api.airforce/v1/responsesErrori
Airforce restituisce codici di stato HTTP standard e una busta di errore uniforme per entrambi gli endpoint.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 400 | invalid_request | Optional | JSON non valido, campo obbligatorio mancante, modello sconosciuto. |
| 401 | authentication_error | Optional | Chiave API mancante o non valida. |
| 403 | permission_error | Optional | Le autorizzazioni per piano o per chiave negano questa richiesta. |
| 429 | rate_limit | Optional | La tariffa della richiesta o il limite massimo di token giornaliero è stato superato. |
| 503 | upstream_error | Optional | Tutte le chiavi upstream per il provider richiesto non sono riuscite. |
{
"error": {
"message": "Model 'gpt-99' not found.",
"type": "invalid_request",
"param": "model",
"code": "model_not_found"
}
}Scopri i modelli
Consulta l'elenco completo degli ID modello e i relativi flag di capacità (visione, strumenti, ragionamento, memorizzazione nella cache, lunghezza del contesto, ...) all'indirizzo /docs/api/models.
curl https://api.airforce/v1/models \
-H "Authorization: Bearer sk-air-YOUR_API_KEY"