استكمالات الدردشة
أنشئ استجابات للدردشة عبر أكثر من 100 نموذج من واجهة برمجة تطبيقات واحدة. تسجيل دخول متوافق مع إكمالات الدردشة في OpenAI ورسائل Anthropic واستجابات Anthropic.
يتحدث Airforce صيغتي التواصل الخاصتين بـ OpenAI Chat Completions و Anthropic Messages عبر المجموعة نفسها من الموديلات. اختر الـ SDK الذي تستخدمه بالفعل وغيّر فقط الـ base URL — تُمرَّر الموديلات غير Claude بشفافية خلف أي من الواجهتين.
تغطي هذه الصفحة المصادقة، وأشكال الطلب والاستجابة لكلتا الواجهتين، والـ streaming، والـ tool calling، والـ vision، والـ reasoning، والـ prompt caching. جديد هنا؟ ابدأ بالمثال الأساسي أدناه، واجعل استدعاءً واحداً يعمل، ثم أضف الـ streaming أو الـ tools أو الـ caching بعد ذلك.
المصادقة
يحتاج كل طلب إلى رمز حامل (مفتاح Airforce API الخاص بك). Anthropic x-api-key يتم قبول الرأس أيضًا /v1/messages للتوافق مع SDK.
Authorization: Bearer sk-air-YOUR_API_KEY
# alt for /v1/messages:
x-api-key: sk-air-YOUR_API_KEYPOST /v1/chat/completions
عمليات إكمال الدردشة المتوافقة مع OpenAI. يعمل مع المسؤول openai SDK عن طريق التجاوز base_url ل https://api.airforce/v1.
https://api.airforce/v1/chat/completionsهيئة الطلب
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Required | معرف النموذج. استخدم GET /v1/models لاكتشاف المعرفات المتاحة. |
| messages | array | Required | سجلّ المحادثة. كل إدخال يحتوي على { role: "system" | "user" | "assistant" | "tool", content }. المحتوى عبارة عن سلسلة نصية أو مصفوفة من كتل المحتوى (الرؤية، انظر أدناه). |
| max_tokens | integer | Optional | الحد الأقصى لعدد الرموز التي سيتم إنشاؤها. الحد الأقصى لـ max_output_tokens الخاص بالنموذج. |
| temperature | float | Optional | درجة حرارة أخذ العينات، 0-2. أقل هو أكثر حتمية. الافتراضي يعتمد على الموفر الرئيسي. |
| top_p | float | Optional | أخذ عينات النواة. استخدم إما درجة الحرارة أو top_p، وليس كليهما. |
| stream | boolean | Optional | عندما يكون هذا صحيحًا، تكون الاستجابة عبارة عن دفق من الأحداث المرسلة من الخادم. انظر "البث" أدناه. |
| models | array | Optional | Fallback models (max 3), e.g. ["deepseek-v3.2", "gpt-4o-mini"]. If every channel of the primary model fails, each candidate is tried in order. You are billed for — and response.model reports — the model that actually answered. Unknown or plan-gated candidates are skipped. With the OpenAI SDK pass it via extra_body. |
| transforms | array | Optional | Prompt transforms. Supported: ["middle-out"] — when the conversation overflows the model's context window, whole messages are dropped from the middle (system prompts, the first message and the most recent turns are kept), so long roleplay or agent histories keep working instead of erroring. Opt-in; off by default. |
| stream_options | object | Optional | { include_usage: boolean }. يُضمَّن الاستخدام دائمًا في آخر جزء من البث؛ يُقبل هذا الحقل من أجل التوافق مع OpenAI لكن لا يمكن إيقافه. |
| stop | string | array | Optional | ما يصل إلى 4 تسلسلات توقف. يتوقف الجيل بمجرد إنتاجه. |
| tools | array | Optional | تعريفات الوظيفة التي قد يستدعيها النموذج. راجع "استدعاء الأداة" أدناه. |
| tool_choice | string | object | Optional | "auto" (افتراضي)، "none"، أو { type: "function", function: { name } } لفرض استدعاء محدّد. |
| response_format | object | Optional | { type: "json_object" } يفرض على النموذج إصدار JSON صالحًا. تم تجاهله بالنسبة للنماذج التي لا تدعمه. |
| reasoning_effort | string | Optional | عمق التفكير بأسلوب OpenAI o1/o3: "منخفض" | "متوسطة" | "عالي". انظر "الاستدلال والتفكير". |
| thinking | string | object | Optional | مفتاح تبديل التفكير عبر المزوّدين. "on" | "off" | "auto"، أو بصيغة Anthropic { type: "enabled", budget_tokens: N }. راجع "Reasoning & thinking". |
| thinking_budget | integer | Optional | الحد الأقصى للرمز المميز لتتبع المنطق الخاص بالنموذج (عندما يكشف الموفر عن واحد). |
| ignore_defaults | boolean | Optional | تخطي المعلمات الافتراضية المحفوظة لكل نموذج (التي تم تكوينها في لوحة المعلومات) لهذا الطلب. |
مثال أساسي
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
}'شكل الرد
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Optional | معرّف إكمال ثابت، على سبيل المثال "chatcmpl-abc123". |
| object | string | Optional | "chat.completion" لغير المتدفقة، "chat.completion.chunk" للبث المباشر. |
| created | integer | Optional | الطابع الزمني لنظام التشغيل Unix (بالثواني). |
| model | string | Optional | صدى معرف النموذج المطلوب. |
| choices | array | Optional | مصفوفة من مرشّحي الإكمال: [{ index, message: { role, content, tool_calls? }, finish_reason }]. |
| choices[].finish_reason | string | Optional | "توقف" | "الطول" | "tool_calls" | "مرشح_المحتوى". |
| 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 عندما ينتج النموذج أثر استدلال. تظهر حقول التخزين المؤقت عندما يعيد upstream معلومات التخزين المؤقت للموجه: 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
}
}الاستدلال والتفكير
النماذج التي تدعم الاستدلال الموسع تكشف أثرًا للتفكير إلى جانب المخرجات العادية. يقوم Airforce بتطبيع ثلاث اتفاقيات مختلفة في مجموعة واحدة من المعلمات الأساسية التي تعمل في كل مكان.
يفحص supports_reasoning: true على نموذج في GET /v1/models لمعرفة المعرفات التي تقبل هذه المعلمات.
نماذج مع دعم المنطق
…· liveالمعلمات الكنسي
| Parameter | Type | Required | Description |
|---|---|---|---|
| reasoning_effort | string | Optional | "منخفض" | "متوسطة" | "عالي". OpenAI o1/o3 ونماذج الاستدلال GPT-5 وأي جهاز توجيه يتصل بها. |
| thinking | string | object | Optional | "on" | "off" | "auto" للتبديل السريع، أو { type: "enabled", budget_tokens: N } للصيغة الأصلية من Anthropic. تتطابق مع التفكير الموسَّع في Claude، وتفكير Gemini، واستدلال DeepSeek. |
| thinking_budget | integer | Optional | الحد الأقصى من الرموز المميزة التي قد يستخدمها النموذج في التفكير قبل إصدار مخرجات مرئية. مرايا الميزانية_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"
}'التفكير الموسع (نمط Anthropic)
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 (شكل OpenAI) أو كما يلي thinking كتل في content (تنسيق Anthropic). يتم إصدار فاتورة بالرموز المميزة للاستدلال والإبلاغ عنها usage.completion_tokens_details.reasoning_tokens.
يكون تفصيل completion_tokens_details.reasoning_tokens موجوداً فقط عندما يُبلّغ عنه المزوّد الأساسي. في الاستجابة بنمط stream يصل الأثر على delta.reasoning_content لكل chunk.
الرؤية وإدخال الصورة
نماذج مع supports_vision: true قبول الصور المضمنة ككتل المحتوى. يعمل إما عنوان URL عام أو عنوان URL لبيانات base64؛ تعتمد حدود الحجم على النموذج الأولي.
نماذج مع دعم الرؤية
…· 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"}}
]
}]
}'استدعاء الأداة
نماذج مع 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\"}"}
]
}Structured outputs
Set response_format to make the model return JSON. Two modes are supported:
{ "type": "json_object" }— the response is a single valid JSON value.{ "type": "json_schema", "json_schema": { "name", "schema", "strict" } }— the model is steered to produce JSON that matches your JSON Schema.
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": "Extract the city and country: I live in Paris, France."}],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "location",
"schema": {
"type": "object",
"properties": { "city": {"type": "string"}, "country": {"type": "string"} },
"required": ["city", "country"]
}
}
}
}'Reliability: even when a model wraps its answer in prose or a markdown code fence, Airforce extracts the JSON payload so you always receive parseable content. If no valid JSON can be recovered, the original text is returned unchanged — so the guarantee never makes a response worse. This applies to non-streamed responses; streamed responses are passed through unchanged.
جاري
تعيين 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
واجهة برمجة تطبيقات الرسائل المتوافقة مع Anthropic. يعمل مع المسؤول @anthropic-ai/sdk عن طريق الإعداد baseURL ل https://api.airforce. إعادة التوجيه إلى OpenAI/Google/إلخ. بشفافية بالنسبة للنماذج غير كلود.
https://api.airforce/v1/messagesهيئة الطلب
| Parameter | Type | Required | Description |
|---|---|---|---|
| model | string | Required | معرف النموذج (تنسيق Anthropic أو اسم مستعار موجه). |
| messages | array | Required | كل إدخال: { role: "user" | "assistant", content: string | array }. |
| max_tokens | integer | Required | مطلوب من قبل Anthropic. غطاء رمزي للاستجابة. |
| system | string | array | Optional | موجّه النظام. مرّر مصفوفة من كتل { type: "text", text, cache_control? } لتمييز مقاطع البادئة المخزَّنة مؤقتًا. راجع "Prompt caching". |
| temperature | float | Optional | 0-1. |
| top_p | float | Optional | أخذ عينات النواة. |
| top_k | integer | Optional | قصر تجمع العينات على رموز Top-K. |
| stop_sequences | array | Optional | ما يصل إلى 4 تسلسلات توقف. |
| stream | boolean | Optional | عندما يكون صحيحًا، يُصدر دفق أحداث SSE على نمط Anthropic (راجع "البث"). |
| fallbacks | array | Optional | Fallback models (max 3) in Anthropic form: [{"model": "gpt-4o-mini"}]. If every channel of the primary model fails, each candidate is tried in order; you are billed for — and the response model field reports — the model that actually answered. A plain models string array is accepted too. |
| tools | array | Optional | تعريفات أدوات Anthropic: { name, description, input_schema }. قد تحتوي الاستجابة على كتل محتوى tool_use. |
| tool_choice | object | Optional | { type: "auto" | "any" | "tool", name? }. |
| thinking | object | Optional | التفكير الموسَّع من Anthropic: { 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!"}
]
}'شكل الرد
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Optional | معرف الرسالة، على سبيل المثال. "msg_01ABCxyz". |
| type | string | Optional | دائما "رسالة". |
| role | string | Optional | دائما "مساعد". |
| content | array | Optional | مصفوفة من كتل المحتوى: { type: "text" | "tool_use" | "thinking", … }. |
| model | string | Optional | صدى النموذج المطلوب. |
| stop_reason | string | Optional | "end_turn" | "max_tokens" | "stop_sequence" | "استخدام الأداة". |
| usage | object | Optional | { 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"}POST /v1/messages/count_tokens
Anthropic-compatible token counting. Send the same system / messages / tools you would pass to /v1/messages and get an input-token estimate back without running the model — nothing is billed.
https://api.airforce/v1/messages/count_tokenscurl https://api.airforce/v1/messages/count_tokens \
-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",
"system": "You are a helpful assistant.",
"messages": [{"role": "user", "content": "Hello, Claude!"}]
}'
# → {"input_tokens": 34}The count is a fast character-based estimate (about 4 characters per token) over system, messages and tools — close enough for context-budget checks, not an exact tokenizer run.
التخزين المؤقت الفوري
على /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?"}
]
}كيف يتم الإبلاغ عن أعداد التخزين المؤقت في الاستجابة
يتم تمرير أعداد رموز التخزين المؤقت في الشكل الأصلي لكل تنسيق، لذا تقرأها SDKs (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
}أين ينطبق التخزين المؤقت
تُحترم علامات cache_control الصريحة على /v1/messages و /v1/chat/completions لنماذج Claude — ضعها على كتل محتوى system أو message. تقوم مزودات أخرى كثيرة (عائلة OpenAI و DeepSeek و Gemini) بالتخزين المؤقت تلقائيًا: لا ترسل أي علامات وترى ببساطة cached_tokens في الاستجابة بمجرد إعادة استخدام بادئة طويلة بما يكفي.
مدة التخزين المؤقت: 5 دقائق أو ساعة واحدة
تعيش البادئة المخزّنة 5 دقائق افتراضيًا ويتجدد المؤقّت مع كل إصابة. لبادئة أطول عمرًا، أضف ttl: "1h" إلى العلامة. تُبلّغ الاستجابة عن كل TTL على حدة ضمن cache_creation.
"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 رمزًا؛ وأكثر لبعض النماذج). البوادئ الأقصر لا تُخزَّن ببساطة.
- حتى 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.
https://api.airforce/v1/responsesPOST /v1beta/models/{model}:generateContent
Google Gemini-compatible endpoint. Works with the official @google/genai SDK and the Gemini CLI by pointing the base URL at https://api.airforce/v1beta. Any routed model works — requests are translated to and from the native Gemini shape, and the model is taken from the URL path (not the body).
https://api.airforce/v1beta/models/{model}:generateContentAuthentication
Pass your Airforce API key any of the three ways Google clients use:
# 1) query parameter (Google default)
?key=sk-air-YOUR_API_KEY
# 2) header
x-goog-api-key: sk-air-YOUR_API_KEY
# 3) bearer token
Authorization: Bearer sk-air-YOUR_API_KEYRequest body
| Parameter | Type | Required | Description |
|---|---|---|---|
| contents | array | Required | Conversation turns. Each: { role: "user" | "model", parts: [...] }. A part is { text }, { functionCall: { name, args } }, or { functionResponse: { name, response } }. "model" is Gemini's term for the assistant role. |
| systemInstruction | object | Optional | System prompt: { parts: [{ text }] }. |
| generationConfig | object | Optional | { temperature, maxOutputTokens, topP, stopSequences } — mapped to the canonical sampling parameters. |
| tools | array | Optional | Tool definitions: [{ functionDeclarations: [{ name, description, parameters }] }]. functionDeclarations are flattened across entries. |
| toolConfig | object | Optional | Tool-choice control: { functionCallingConfig: { mode: "AUTO" | "ANY" | "NONE" } }. ANY forces a call, NONE disables tools. |
Example
curl "https://api.airforce/v1beta/models/gemini-3.1-pro:generateContent" \
-H "x-goog-api-key: sk-air-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{"role": "user", "parts": [{"text": "What is the capital of France?"}]}
],
"systemInstruction": {"parts": [{"text": "You are a helpful assistant."}]},
"generationConfig": {"temperature": 0.7, "maxOutputTokens": 256}
}'Response shape
| Parameter | Type | Required | Description |
|---|---|---|---|
| candidates | array | Optional | Generated turns: [{ content: { role: "model", parts }, finishReason, index }]. Only the first candidate is populated. |
| candidates[].finishReason | string | Optional | "STOP" | "MAX_TOKENS" | "SAFETY" | "OTHER". |
| usageMetadata | object | Optional | { promptTokenCount, candidatesTokenCount, totalTokenCount, cachedContentTokenCount? }. cachedContentTokenCount appears when the upstream reported a cache read. |
| modelVersion | string | Optional | Echo of the requested model. |
{
"candidates": [{
"content": {
"role": "model",
"parts": [{"text": "The capital of France is Paris."}]
},
"finishReason": "STOP",
"index": 0
}],
"usageMetadata": {
"promptTokenCount": 16,
"candidatesTokenCount": 8,
"totalTokenCount": 24
},
"modelVersion": "gemini-3.1-pro"
}POST /v1beta/models/{model}:streamGenerateContent
Streaming uses the :streamGenerateContent action and returns Server-Sent Events. Each data: line is a full Gemini-shaped chunk (not a delta object); the final chunk carries usageMetadata.
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"The capital"}]},"index":0}],"modelVersion":"gemini-3.1-pro"}
data: {"candidates":[{"content":{"role":"model","parts":[{"text":" is Paris."}]},"index":0}],"modelVersion":"gemini-3.1-pro"}
data: {"candidates":[{"content":{"role":"model","parts":[]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":16,"candidatesTokenCount":8,"totalTokenCount":24}}List models
The catalog is also exposed in Gemini Model-resource shape so Google clients can enumerate models.
curl https://api.airforce/v1beta/modelsNotes: the base URL is https://api.airforce/v1beta (or /v1), not Google's host. The model name comes from the URL path, not the request body. Only the first candidate is returned, and a subset of Gemini fields is translated — safetySettings and cachedContent are currently ignored. Billing, rate limits and smart routing apply exactly as on /v1/chat/completions.
أخطاء
تقوم Airforce بإرجاع رموز حالة HTTP القياسية ومغلف خطأ موحد لكلا نقطتي النهاية.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 400 | invalid_request_error | Optional | JSON غير صحيح، الحقل المطلوب مفقود، النموذج غير معروف. |
| 401 | invalid_request_error / auth_required | Optional | مفتاح API مفقود أو غير صالح. |
| 402 | insufficient_quota | Optional | يتطلب النموذج اشتراكًا نشطًا أو رصيد Pay-as-you-Go موجبًا. |
| 403 | model_access_denied / insufficient_scope | Optional | ترفض أذونات الخطة أو لكل مفتاح هذا الطلب. |
| 404 | model_not_found | Optional | النموذج المطلوب غير موجود أو ليس لديك صلاحية الوصول إليه. |
| 429 | rate_limit_error | Optional | تم تجاوز معدل الطلب أو الحد الأقصى اليومي للرمز المميز. |
| 503 | api_error / moderation_unavailable | Optional | فشلت كافة المفاتيح الأولية للموفر المطلوب. |
{
"error": {
"message": "The requested model does not exist or you do not have access to it.",
"type": "model_not_found",
"param": null,
"code": "404"
}
}يوجد الـ slug الوصفي في type. أما code فهو حالة HTTP كسلسلة نصية (مثل "404")، وparam يكون null باستثناء أخطاء التحقّق من نطاق المعاملات، حيث يسمّي المعامل المخالف.
اكتشف النماذج
راجع القائمة الكاملة لمعرفات النماذج وعلامات قدراتها (الرؤية، الأدوات، الاستدلال، التخزين المؤقت، طول السياق، ...) على /docs/api/models.
curl https://api.airforce/v1/models \
-H "Authorization: Bearer sk-air-YOUR_API_KEY"