Api.Airforce
API REFERENCE

Hoàn thành trò chuyện

Tạo phản hồi trò chuyện trên hơn 100 mô hình từ một API. Tính năng đăng nhập tương thích với các lần hoàn thành trò chuyện OpenAI, Tin nhắn nhân loại và Phản hồi nhân loại.

Xác thực

Mọi yêu cầu đều cần có mã thông báo Bearer (khóa API Airforce của bạn). nhân loại x-api-key tiêu đề cũng được chấp nhận trên /v1/messages để tương thích với SDK.

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

POST /v1/chat/completions

Hoàn thành trò chuyện tương thích với OpenAI. Làm việc với chính thức openai SDK bằng cách ghi đè base_url ĐẾN https://api.airforce/v1.

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

Nội dung yêu cầu

ParameterTypeRequiredDescription
modelstringRequiredID mẫu. Sử dụng GET /v1/models để khám phá các ID có sẵn.
messagesarrayRequiredLịch sử hội thoại. Mỗi mục có { role: "system" | "người dùng" | "trợ lý" | "công cụ", nội dung }. Nội dung là một chuỗi hoặc một mảng các khối nội dung (tầm nhìn, xem bên dưới).
max_tokensintegerOptionalSố lượng mã thông báo tối đa để tạo. Giới hạn ở max_output_tokens của mô hình.
temperaturefloatOptionalNhiệt độ lấy mẫu, 0–2. Thấp hơn là xác định hơn. Mặc định phụ thuộc vào nhà cung cấp ngược dòng.
top_pfloatOptionalLấy mẫu hạt nhân. Sử dụng nhiệt độ hoặc top_p, không phải cả hai.
streambooleanOptionalKhi đúng, phản hồi là một luồng Sự kiện do máy chủ gửi. Xem "Truyền phát" bên dưới.
stream_optionsobjectOptional{ include_usage: boolean }. Khi include_usage là true thì đoạn SSE cuối cùng mang khối use.
stopstring | arrayOptionalLên đến 4 chuỗi dừng. Thế hệ dừng lại ngay khi một thế hệ được sản xuất.
toolsarrayOptionalĐịnh nghĩa hàm mà mô hình có thể gọi. Xem "Gọi công cụ" bên dưới.
tool_choicestring | objectOptional"auto" (mặc định), "none" hoặc { type: "function", function: { name } } để thực hiện một cuộc gọi cụ thể.
response_formatobjectOptional{ type: "json_object" } buộc mô hình phát ra JSON hợp lệ. Bỏ qua các mô hình không hỗ trợ nó.
reasoning_effortstringOptionalĐộ sâu lý luận kiểu OpenAI o1/o3: "thấp" | "trung bình" | "cao". Xem phần "Lý luận và suy nghĩ".
thinkingstring | objectOptionalChuyển đổi tư duy giữa các nhà cung cấp. "bật" | "tắt" | "auto" hoặc Hình dạng nhân loại { type: "enabled", budget_tokens: N }. Xem phần "Lý luận và suy nghĩ".
thinking_budgetintegerOptionalGiới hạn mã thông báo cho dấu vết lý luận của mô hình (khi nhà cung cấp hiển thị một dấu vết).
ignore_defaultsbooleanOptionalBỏ qua các tham số mặc định đã lưu cho mỗi mô hình của người dùng (được định cấu hình trong trang tổng quan) cho yêu cầu này.

Ví dụ cơ bản

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

Hình dạng phản hồi

ParameterTypeRequiredDescription
idstringOptionalID hoàn thành ổn định, ví dụ: "chatcmpl-abc123".
objectstringOptional"chat.completion" dành cho không phát trực tuyến, "chat.completion.chunk" dành cho phát trực tuyến.
createdintegerOptionalDấu thời gian Unix (giây).
modelstringOptionalTiếng vang của ID mẫu được yêu cầu.
choicesarrayOptionalMảng ứng viên hoàn thành: [{index, message: { role, content, tool_calls? }, finish_reason }].
choices[].finish_reasonstringOptional"dừng lại" | "chiều dài" | "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 được đặt khi mô hình tạo ra dấu vết suy luận. Các trường cache xuất hiện khi upstream trả về thông tin prompt-caching: prompt_tokens_details.cached_tokens báo cáo lượt đọc cache (chuẩn OpenAI), cache_creation_input_tokens tổng hợp lượt ghi, và cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens cho biết phân chia theo 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
  }
}

Lý luận và suy nghĩ

Các mô hình hỗ trợ lý luận mở rộng cho thấy dấu vết tư duy bên cạnh kết quả đầu ra thông thường. Lực lượng Không quân bình thường hóa ba quy ước ngược dòng khác nhau thành một tập hợp các tham số chuẩn có thể hoạt động ở mọi nơi.

Kiểm tra supports_reasoning: true trên một mô hình trong GET /v1/models để biết ID nào chấp nhận các tham số này.

Các mô hình có hỗ trợ lý luận

· live

Thông số chuẩn

ParameterTypeRequiredDescription
reasoning_effortstringOptional"thấp" | "trung bình" | "cao". Các mô hình suy luận OpenAI o1/o3, GPT-5 và bất kỳ bộ định tuyến nào ánh xạ tới chúng.
thinkingstring | objectOptional"bật" | "tắt" | "auto" để chuyển đổi nhanh hoặc { type: "enabled", budget_tokens: N } cho hình dạng người bản địa. Bản đồ tới tư duy mở rộng của Claude, tư duy của Song Tử và lý luận DeepSeek.
thinking_budgetintegerOptionalMã thông báo tối đa mà mô hình có thể sử dụng để suy luận trước khi phát ra đầu ra hiển thị. Phản chiếu ngân sách_token.

Nỗ lực suy luận (kiểu 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"
  }'

Tư duy mở rộng (kiểu nhân loại)

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

Bản thân dấu vết lý luận xuất hiện trong choices[0].message.reasoning_content (hình dạng OpenAI) hoặc dưới dạng thinking khối trong content (hình nhân học). Mã thông báo lý luận được lập hoá đơn và báo cáo trong usage.completion_tokens_details.reasoning_tokens.


Đầu vào tầm nhìn và hình ảnh

Mô hình với supports_vision: true chấp nhận hình ảnh được nhúng dưới dạng khối nội dung. URL công khai hoặc URL dữ liệu base64 đều hoạt động; giới hạn kích thước phụ thuộc vào mô hình ngược dòng.

Các mô hình có hỗ trợ thị giác

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

Công cụ gọi

Mô hình với supports_tools: true có thể gọi các hàm bạn xác định. Mô hình trả về một tool_calls mảng; bạn thực hiện cuộc gọi, sau đó gửi lại kết quả trong tool tin nhắn.

Các mô hình có hỗ trợ gọi công cụ

· live

Lời yêu cầu

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

Phản hồi bằng lệnh gọi công cụ

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

Theo dõi kết quả của công cụ

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

Truyền phát

Bộ stream: true để nhận được các lần hoàn thành một phần dưới dạng Sự kiện do máy chủ gửi. Mỗi sự kiện là một đoạn JSON có hình dạng giống như phản hồi không được phát trực tuyến, ngoại trừ message được thay thế bởi delta. Luồng kết thúc bằng 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}
  }'

Định dạng dây

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 tin nhắn tương thích với con người. Làm việc với chính thức @anthropic-ai/sdk bằng cách thiết lập baseURL ĐẾN https://api.airforce. Chuyển tiếp tới OpenAI/Google/v.v. minh bạch cho các mô hình không phải Claude.

POSThttps://api.airforce/v1/messages

Nội dung yêu cầu

ParameterTypeRequiredDescription
modelstringRequiredID mẫu (định dạng nhân loại hoặc bí danh được định tuyến).
messagesarrayRequiredMỗi mục: { vai trò: "người dùng" | "trợ lý", nội dung: chuỗi | mảng }.
max_tokensintegerRequiredĐược yêu cầu bởi Anthropic. Giới hạn mã thông báo cho phản hồi.
systemstring | arrayOptionalHệ thống nhắc nhở. Truyền một mảng {type: "text", text, cache_control? } khối để đánh dấu các phân đoạn tiền tố được lưu trong bộ nhớ cache. Xem "Bộ nhớ đệm nhanh".
temperaturefloatOptional0–1.
top_pfloatOptionalLấy mẫu hạt nhân.
top_kintegerOptionalGiới hạn nhóm lấy mẫu ở các mã thông báo top-K.
stop_sequencesarrayOptionalLên đến 4 chuỗi dừng.
streambooleanOptionalKhi đúng, sẽ phát ra luồng sự kiện SSE kiểu Anthropic (xem "Truyền phát").
toolsarrayOptionalĐịnh nghĩa công cụ nhân học: { name, description, input_schema }. Phản hồi có thể chứa các khối nội dung tool_use.
tool_choiceobjectOptional{ loại: "tự động" | "bất kỳ" | "công cụ", tên? }.
thinkingobjectOptionalTư duy mở rộng mang tính nhân loại: { type: "enabled", budget_tokens: N }.

Ví dụ

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

Hình dạng phản hồi

ParameterTypeRequiredDescription
idstringOptionalID tin nhắn, ví dụ: "tin nhắn_01ABCxyz".
typestringOptionalLuôn luôn "tin nhắn".
rolestringOptionalLuôn luôn là "trợ lý".
contentarrayOptionalMảng khối nội dung: { type: "text" | "tool_use" | "suy nghĩ", … }.
modelstringOptionalTiếng vang của mô hình được yêu cầu.
stop_reasonstringOptional"end_turn" | "max_tokens" | "stop_sequence" | "công cụ_sử dụng".
usageobjectOptional{ input_tokens, output_tokens, cache_read_input_tokens?, cache_creation_input_tokens?, cache_creation? }. Các trường cache xuất hiện khi prompt caching được sử dụng. cache_creation.ephemeral_5m_input_tokens và ephemeral_1h_input_tokens cho biết phân chia ghi theo TTL.

Truyền phát sự kiện

SSE nhân loại sử dụng các sự kiện được đặt tên thay vì các đoạn JSON một lần. Mỗi sự kiện đều có một event: tên và một data: Tải trọng 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"}

Bộ nhớ đệm nhắc nhở

TRÊN /v1/messages với các mô hình Claude, đánh dấu tiền tố là được lưu trong bộ nhớ đệm bằng cách chuyển system dưới dạng một mảng các khối trong đó phân đoạn được lưu trong bộ nhớ đệm mang cache_control: { type: "ephemeral" }. Các yêu cầu tiếp theo bắt đầu bằng cùng một tiền tố sẽ tính phí tốc độ đọc bộ đệm rẻ hơn. Mô hình với supports_caching: true TRONG /v1/models ủng hộ điều này.

Các mô hình có bộ nhớ đệm nhanh chóng

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

Cách số liệu cache được báo cáo trong phản hồi

Số liệu token cache được chuyển qua trong hình dạng gốc của từng định dạng, vì vậy SDK (openai, @anthropic-ai/sdk, @google/genai) đọc chúng mà không cần mã tùy chỉnh. Các trường được bỏ qua khi giá trị bằng không, giữ cho các phản hồi không cache gọn nhẹ.

/v1/chat/completions (dạng 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 (dạng 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 (dạng Gemini)

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

Caching áp dụng ở đâu

Các marker cache_control rõ ràng được tôn trọng trên /v1/messages và /v1/chat/completions cho các mô hình Claude — đặt chúng trên khối nội dung system hoặc message. Nhiều nhà cung cấp khác (họ OpenAI, DeepSeek, Gemini) cache tự động: bạn không gửi marker nào và chỉ cần thấy cached_tokens trong phản hồi khi một prefix đủ dài được tái sử dụng.

Thời lượng cache: 5 phút hoặc 1 giờ

Một prefix đã cache mặc định tồn tại 5 phút và bộ đếm làm mới sau mỗi lần trúng. Để prefix tồn tại lâu hơn, thêm ttl: "1h" vào marker. Phản hồi báo cáo từng TTL riêng dưới cache_creation.

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

Ví dụ: ghi trước, đọc sau

Gửi đúng cùng một yêu cầu hai lần (ví dụ caching ở trên). Lần gọi đầu tiên thấy prefix trả một lần ghi cache; các lần gọi giống hệt trong TTL trả lần đọc cache rẻ hơn nhiều.

Lần gọi đầu — ghi cache (trích usage):

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

Lần gọi giống hệt thứ hai trong TTL — đọc cache:

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

Giới hạn & chi phí

  • Claude yêu cầu prefix tối thiểu có thể cache (khoảng 1024 token; lớn hơn với một số mô hình). Các prefix ngắn hơn đơn giản là không được cache.
  • Tối đa 4 điểm cache mỗi yêu cầu, và prefix đã cache phải giống nhau từng byte giữa các lần gọi — chỉ một ký tự khác cũng trượt cache.
  • Ghi cache đắt hơn input thường (5m ≈ 1,25×, 1h ≈ 2×); đọc rẻ hơn nhiều (≈ 0,1×). Xem giá cache của từng mô hình trên trang giá.

POST /v1/responses

Giao diện OpenAI Responses-API cho các cuộc trò chuyện có trạng thái. Cùng xác thực Bearer/x-api-key. Số liệu cache xuất hiện dưới dạng input_tokens_details.cached_tokens (đọc) cộng với cache_creation_input_tokens phẳng + cache_creation.ephemeral_* (ghi) để tương đương với /v1/chat/completions.

POSThttps://api.airforce/v1/responses

Lỗi

Airforce trả về mã trạng thái HTTP tiêu chuẩn và đường bao lỗi thống nhất cho cả hai điểm cuối.

ParameterTypeRequiredDescription
400invalid_requestOptionalJSON không đúng định dạng, thiếu trường bắt buộc, mô hình không xác định.
401authentication_errorOptionalKhóa API bị thiếu hoặc không hợp lệ.
403permission_errorOptionalQuyền gói hoặc quyền theo từng khóa từ chối yêu cầu này.
429rate_limitOptionalĐã vượt quá tỷ lệ yêu cầu hoặc giới hạn mã thông báo hàng ngày.
503upstream_errorOptionalTất cả các khóa ngược dòng cho nhà cung cấp được yêu cầu đều không thành công.
{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

Khám phá mô hình

Xem danh sách đầy đủ các ID mô hình và cờ khả năng của chúng (tầm nhìn, công cụ, lý luận, bộ nhớ đệm, độ dài ngữ cảnh, ...) tại /docs/api/models.

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