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_KEYPOST /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.
https://api.airforce/v1/chat/completionsNội dung yêu cầu
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Required | ID mẫu. Sử dụng GET /v1/models để khám phá các ID có sẵn. |
| messages | array | Required | Lị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_tokens | integer | Optional | Số lượng mã thông báo tối đa để tạo. Giới hạn ở max_output_tokens của mô hình. |
| temperature | float | Optional | Nhiệ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_p | float | Optional | Lấy mẫu hạt nhân. Sử dụng nhiệt độ hoặc top_p, không phải cả hai. |
| stream | boolean | Optional | Khi đú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_options | object | Optional | { include_usage: boolean }. Khi include_usage là true thì đoạn SSE cuối cùng mang khối use. |
| stop | string | array | Optional | Lên đến 4 chuỗi dừng. Thế hệ dừng lại ngay khi một thế hệ được sản xuất. |
| tools | array | Optional | Định nghĩa hàm mà mô hình có thể gọi. Xem "Gọi công cụ" bên dưới. |
| tool_choice | string | object | Optional | "auto" (mặc định), "none" hoặc { type: "function", function: { name } } để thực hiện một cuộc gọi cụ thể. |
| response_format | object | Optional | { 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_effort | string | Optional | Độ 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ĩ". |
| thinking | string | object | Optional | Chuyể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_budget | integer | Optional | Giớ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_defaults | boolean | Optional | Bỏ 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Optional | ID hoàn thành ổn định, ví dụ: "chatcmpl-abc123". |
| object | string | Optional | "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. |
| created | integer | Optional | Dấu thời gian Unix (giây). |
| model | string | Optional | Tiếng vang của ID mẫu được yêu cầu. |
| choices | array | Optional | Mảng ứng viên hoàn thành: [{index, message: { role, content, tool_calls? }, finish_reason }]. |
| choices[].finish_reason | string | Optional | "dừng lại" | "chiều dài" | "tool_calls" | "content_filter". |
| 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 đượ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
…· liveThông số chuẩn
| Parameter | Type | Required | Description |
|---|---|---|---|
| reasoning_effort | string | Optional | "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. |
| thinking | string | object | Optional | "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_budget | integer | Optional | Mã 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
…· 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"}}
]
}]
}'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ụ
…· liveLờ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.
https://api.airforce/v1/messagesNội dung yêu cầu
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Required | ID mẫu (định dạng nhân loại hoặc bí danh được định tuyến). |
| messages | array | Required | Mỗi mục: { vai trò: "người dùng" | "trợ lý", nội dung: chuỗi | mảng }. |
| max_tokens | integer | Required | Được yêu cầu bởi Anthropic. Giới hạn mã thông báo cho phản hồi. |
| system | string | array | Optional | Hệ 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". |
| temperature | float | Optional | 0–1. |
| top_p | float | Optional | Lấy mẫu hạt nhân. |
| top_k | integer | Optional | Giới hạn nhóm lấy mẫu ở các mã thông báo top-K. |
| stop_sequences | array | Optional | Lên đến 4 chuỗi dừng. |
| stream | boolean | Optional | Khi đúng, sẽ phát ra luồng sự kiện SSE kiểu Anthropic (xem "Truyền phát"). |
| tools | array | Optional | Đị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_choice | object | Optional | { loại: "tự động" | "bất kỳ" | "công cụ", tên? }. |
| thinking | object | Optional | Tư 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
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Optional | ID tin nhắn, ví dụ: "tin nhắn_01ABCxyz". |
| type | string | Optional | Luôn luôn "tin nhắn". |
| role | string | Optional | Luôn luôn là "trợ lý". |
| content | array | Optional | Mảng khối nội dung: { type: "text" | "tool_use" | "suy nghĩ", … }. |
| model | string | Optional | Tiếng vang của mô hình được yêu cầu. |
| stop_reason | string | Optional | "end_turn" | "max_tokens" | "stop_sequence" | "công cụ_sử dụng". |
| usage | object | Optional | { 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.
https://api.airforce/v1/responsesLỗ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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 400 | invalid_request | Optional | JSON không đúng định dạng, thiếu trường bắt buộc, mô hình không xác định. |
| 401 | authentication_error | Optional | Khóa API bị thiếu hoặc không hợp lệ. |
| 403 | permission_error | Optional | Quyền gói hoặc quyền theo từng khóa từ chối yêu cầu này. |
| 429 | rate_limit | Optional | Đã vượt quá tỷ lệ yêu cầu hoặc giới hạn mã thông báo hàng ngày. |
| 503 | upstream_error | Optional | Tấ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"