Api.Airforce
API REFERENCE

聊天完成狀況

透過一個 API 產生跨 100 多個模型的聊天回應。與 OpenAI 聊天完成、人擇訊息和人擇響應相容。

驗證

每個請求都需要一個 Bearer 令牌(您的 Airforce API 金鑰)。人擇 x-api-key 標頭也被接受 /v1/messages 用於 SDK 相容性。

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

POST /v1/chat/completions

OpenAI 相容的聊天完成。與官方合作 openai SDK透過覆蓋 base_url https://api.airforce/v1.

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

請求正文

ParameterTypeRequiredDescription
modelstringRequired型號 ID。使用 GET /v1/models 發現可用的 ID。
messagesarrayRequired對話歷史記錄。每個條目都有 { role: "system" | “使用者” | “助理”| “工具”,內容}。內容是一個字串或內容塊數組(願景,見下文)。
max_tokensintegerOptional產生的最大令牌數。上限為模型的 max_output_tokens。
temperaturefloatOptional採樣溫度,0–2。越低則更具確定性。預設值取決於上游提供者。
top_pfloatOptional細胞核取樣。使用溫度或top_p,而不是兩者都使用。
streambooleanOptional當為 true 時,回應是伺服器發送的事件流。請參閱下面的“串流”。
stream_optionsobjectOptional{ include_usage: 布林值 }。當 include_usage 為 true 時,最終的 SSE 區塊攜帶使用區塊。
stopstring | arrayOptional最多 4 個停止序列。一旦生產出來,生產就會停止。
toolsarrayOptional模型可能呼叫的函數定義。請參閱下面的「工具呼叫」。
tool_choicestring | objectOptional「auto」(預設)、「none」或 { type: "function", function: { name } } 強制執行特定呼叫。
response_formatobjectOptional{ type: "json_object" } 強制模型發出有效的 JSON。不支援的型號將被忽略。
reasoning_effortstringOptionalOpenAI o1/o3 式推理深度:「低」| 「中」| 「高的」。參見“推理與思考”。
thinkingstring | objectOptional跨提供者思維轉換。 “開”| “關閉”| “auto”,或 Anthropic-shape { type:“enabled”,budget_tokens:N }。參見“推理與思考”。
thinking_budgetintegerOptional模型推理追蹤的令牌上限(當提供者公開時)。
ignore_defaultsbooleanOptional跳過使用者為此請求保存的每個模型的預設參數(在儀表板中配置)。

基本範例

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

回應形狀

ParameterTypeRequiredDescription
idstringOptional穩定的完成 ID,例如“chatcmpl-abc123”。
objectstringOptional「chat.completion」用於非串流傳輸,「chat.completion.chunk」用於串流傳輸。
createdintegerOptionalUnix 時間戳(秒)。
modelstringOptional回顯所請求的型號 ID。
choicesarrayOptional完成候選數組:[{索引,訊息:{角色,內容,工具呼叫? },完成原因}]。
choices[].finish_reasonstringOptional“停止”| “長度”| “工具呼叫”| “內容過濾器”。
usageobjectOptional{ prompt_tokens, completion_tokens, total_tokens, completion_tokens_details?, prompt_tokens_details?, cache_creation_input_tokens?, cache_creation? }。當模型生成推理痕跡時設定 completion_tokens_details.reasoning_tokens。當上游回傳提示快取資訊時會出現快取欄位:prompt_tokens_details.cached_tokens 回報快取讀取(OpenAI 標準),cache_creation_input_tokens 彙總寫入,cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens 提供 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
  }
}

推理與思考

支援擴展推理的模型會在常規輸出旁公開思維軌跡。空軍將三種不同的上游約定標準化為一組適用於任何地方的規範參數。

查看 supports_reasoning: true 在模型上 GET /v1/models 了解哪些 ID 接受這些參數。

具有推理支持的模型

· live

規範參數

ParameterTypeRequiredDescription
reasoning_effortstringOptional“低”| “中”| “高的”。 OpenAI o1/o3、GPT-5 推理模型以及映射到它們的任何路由器。
thinkingstring | objectOptional「開」| 「關閉」| 「auto」用於快速切換,或 { type: "enabled",budget_tokens: N } 用於 Anthropic-native 形狀。映射到克勞德擴展思維、雙子座思維和 DeepSeek 推理。
thinking_budgetintegerOptional模型在發出可見輸出之前可以花費推理的最大令牌。鏡像budget_tokens。

推理工作(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"
  }'

擴展思維(人擇式)

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

推理痕跡本身出現在 choices[0].message.reasoning_content (OpenAI 形狀)或作為 thinking 阻塞在 content (人類形狀)。推理令牌的計費和報告在 usage.completion_tokens_details.reasoning_tokens.


視覺與影像輸入

型號有 supports_vision: true 接受作為內容區塊嵌入的圖像。公用 URL 或 Base64 資料 URL 皆可;大小限制取決於上游模型。

具有視覺支援的型號

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

工具調用

型號有 supports_tools: true 可以呼叫您定義的函數。該模型返回一個 tool_calls 大批;您運行該調用,然後將結果傳回 tool 訊息.

支援工具調用的型號

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

透過工具呼叫進行回應

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

跟進工具結果

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

串流媒體

stream: true 接收部分完成作為伺服器發送的事件。每個事件都是一個 JSON 區塊,其形狀與非串流響應相同,除了 message 被替換為 delta. 串流結束於 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}
  }'

接線格式

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。與官方合作 @anthropic-ai/sdk 透過設定 baseURL https://api.airforce. 轉發到 OpenAI/Google/等。對於非克勞德模型來說是透明的。

POSThttps://api.airforce/v1/messages

請求正文

ParameterTypeRequiredDescription
modelstringRequired模型 ID(人類格式或路由別名)。
messagesarrayRequired每個條目:{ 角色:“用戶”| “助理”,內容:字串 |大批 }。
max_tokensintegerRequired人類需要。響應的令牌上限。
systemstring | arrayOptional系統提示。傳遞一個 { type: "text", text, cache_control? 的陣列} 區塊來標記快取的前綴段。請參閱“提示快取”。
temperaturefloatOptional0–1。
top_pfloatOptional細胞核取樣。
top_kintegerOptional將採樣池限制為前 K 個代幣。
stop_sequencesarrayOptional最多 4 個停止序列。
streambooleanOptional如果為 true,則發出 Anthropic 風格的 SSE 事件流(請參閱「流」)。
toolsarrayOptional人擇工具定義:{ 名稱、描述、input_schema }。回應可能包含 tool_use 內容區塊。
tool_choiceobjectOptional{ 類型:“自動”| “任何”| “工具”,名字? }。
thinkingobjectOptional人擇擴展思維:{ type: "enabled",budget_tokens: N }。

例子

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

回應形狀

ParameterTypeRequiredDescription
idstringOptional訊息 ID,例如“msg_01ABCxyz”。
typestringOptional總是“消息”。
rolestringOptional永遠是「助手」。
contentarrayOptional內容塊陣列:{ type: "text" | “工具使用” | “思考”,…}。
modelstringOptional所請求型號的迴聲。
stop_reasonstringOptional“結束轉彎”| “最大代幣”| “停止序列”| “工具使用”。
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }。當使用了提示快取時會出現快取欄位。cache_creation.ephemeral_5m_input_tokens 和 ephemeral_1h_input_tokens 提供按 TTL 的寫入拆分。

串流媒體活動

Anthropic SSE 使用命名事件而不是一次性 JSON 區塊。每個事件都有一個 event: 姓名和一個 data: 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"}

提示快取

/v1/messages 對於 Claude 模型,透過傳遞將前綴標記為緩存 system 作為緩存段攜帶的塊數組 cache_control: { type: "ephemeral" }. 以相同前綴開頭的後續請求將收取更便宜的快取讀取速率。型號有 supports_caching: true /v1/models 支持這一點。

具有提示快取的模型

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

快取計數在回應中的報告方式

快取令牌計數以每種格式的原生形狀傳遞,因此 SDK (openai、@anthropic-ai/sdk、@google/genai) 無需自訂程式碼即可讀取。當值為零時省略欄位,使未快取的回應保持精簡。

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

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

快取在哪些情況下生效

對於 Claude 模型,明確的 cache_control 標記在 /v1/messages 與 /v1/chat/completions 上皆生效——把它們放在 system 或 message 的內容區塊上。許多其他供應商(OpenAI 系、DeepSeek、Gemini)會自動快取:你無需傳送任何標記,只要重用夠長的前綴,回應中就會出現 cached_tokens。

快取時長:5 分鐘或 1 小時

快取的前綴預設存活 5 分鐘,每次命中都會刷新計時。若需更長存活的前綴,請在標記中加入 ttl: "1h" 。回應會在 cache_creation 下分別回報每種 TTL。

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

範例:先寫入,再讀取

把完全相同的請求傳送兩次(上面的快取範例)。第一次看到該前綴的呼叫支付一次性的快取寫入;TTL 內相同的呼叫支付便宜許多的快取讀取。

第一次呼叫——快取寫入(usage 摘錄):

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

TTL 內第二次相同呼叫——快取讀取:

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

限制與費用

  • Claude 要求最小可快取前綴(約 1024 個 token;某些模型更大)。更短的前綴根本不會被快取。
  • 每個請求最多 4 個快取斷點,且快取的前綴在多次呼叫間必須逐位元組相同——哪怕改動一個字元也會錯過快取。
  • 快取寫入比一般輸入更貴(5m ≈ 1.25×,1h ≈ 2×);讀取便宜許多(≈ 0.1×)。各模型的快取價格見定價頁面。

POST /v1/responses

用於有狀態對話的 OpenAI Responses-API 表面。相同的 Bearer/x-api-key 認證。快取計數顯示為 input_tokens_details.cached_tokens(讀取)加上平面的 cache_creation_input_tokens + cache_creation.ephemeral_*(寫入),與 /v1/chat/completions 對等。

POSThttps://api.airforce/v1/responses

錯誤

Airforce 為兩個端點傳回標準 HTTP 狀態代碼和統一的錯誤信封。

ParameterTypeRequiredDescription
400invalid_requestOptionalJSON 格式錯誤、缺少必填欄位、未知型號。
401authentication_errorOptionalAPI 金鑰缺失或無效。
403permission_errorOptional計劃或每鍵權限拒絕此請求。
429rate_limitOptional超出請求率或每日代幣上限。
503upstream_errorOptional所請求的提供程序的所有上游金鑰均失敗。
{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

探索型號

請參閱模型 ID 及其功能標誌(視覺、工具、推理、快取、上下文長度等)的完整清單: /docs/api/models.

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