Api.Airforce
API REFERENCE

استكمالات الدردشة

أنشئ استجابات للدردشة عبر أكثر من 100 نموذج من واجهة برمجة تطبيقات واحدة. تسجيل دخول متوافق مع إكمالات الدردشة في OpenAI والرسائل الإنسانية والاستجابات الإنسانية.

المصادقة

يحتاج كل طلب إلى رمز حامل (مفتاح 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معرف النموذج. استخدم GET /v1/models لاكتشاف المعرفات المتاحة.
messagesarrayRequiredتاريخ المحادثة. كل إدخال له دور {: "النظام" | "المستخدم" | "مساعد" | "أداة"، محتوى }. المحتوى عبارة عن سلسلة أو مصفوفة من كتل المحتوى (الرؤية، انظر أدناه).
max_tokensintegerOptionalالحد الأقصى لعدد الرموز التي سيتم إنشاؤها. الحد الأقصى لـ max_output_tokens الخاص بالنموذج.
temperaturefloatOptionalدرجة حرارة أخذ العينات، 0-2. أقل هو أكثر حتمية. الافتراضي يعتمد على الموفر الرئيسي.
top_pfloatOptionalأخذ عينات النواة. استخدم إما درجة الحرارة أو top_p، وليس كليهما.
streambooleanOptionalعندما يكون هذا صحيحًا، تكون الاستجابة عبارة عن دفق من الأحداث المرسلة من الخادم. انظر "البث" أدناه.
stream_optionsobjectOptional{ include_usage: منطقي }. عندما يكون include_usage صحيحًا، فإن مقطع SSE النهائي يحمل كتلة الاستخدام.
stopstring | arrayOptionalما يصل إلى 4 تسلسلات توقف. يتوقف الجيل بمجرد إنتاجه.
toolsarrayOptionalتعريفات الوظيفة التي قد يستدعيها النموذج. راجع "استدعاء الأداة" أدناه.
tool_choicestring | objectOptional"تلقائي" (افتراضي)، "لا شيء"، أو { النوع: "وظيفة"، الوظيفة: { الاسم } } لفرض مكالمة محددة.
response_formatobjectOptional{ type: "json_object" } يفرض على النموذج إصدار JSON صالحًا. تم تجاهله بالنسبة للنماذج التي لا تدعمه.
reasoning_effortstringOptionalعمق التفكير بأسلوب OpenAI o1/o3: "منخفض" | "متوسطة" | "عالي". انظر "الاستدلال والتفكير".
thinkingstring | objectOptionalتبديل التفكير عبر الموفر. "على" | "إيقاف" | "تلقائي"، أو شكل إنساني { النوع: "ممكّن"، رموز الميزانية: 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معرف إكمال ثابت، على سبيل المثال. "chatcmple-abc123".
objectstringOptional"chat.completion" لغير المتدفقة، "chat.completion.chunk" للبث المباشر.
createdintegerOptionalالطابع الزمني لنظام التشغيل Unix (بالثواني).
modelstringOptionalصدى معرف النموذج المطلوب.
choicesarrayOptionalمجموعة من المرشحين للإكمال: [{index، message: { role, content, tool_calls? }، Finish_reason }].
choices[].finish_reasonstringOptional"توقف" | "الطول" | "tool_calls" | "مرشح_المحتوى".
usageobjectOptional{ 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
  }
}

الاستدلال والتفكير

النماذج التي تدعم الاستدلال الموسع تكشف أثرًا للتفكير إلى جانب المخرجات العادية. تقوم القوات الجوية بتطبيع ثلاث اتفاقيات مختلفة في مجموعة واحدة من المعلمات الأساسية التي تعمل في كل مكان.

يفحص supports_reasoning: true على نموذج في GET /v1/models لمعرفة المعرفات التي تقبل هذه المعلمات.

نماذج مع دعم المنطق

· live

المعلمات الكنسي

ParameterTypeRequiredDescription
reasoning_effortstringOptional"منخفض" | "متوسطة" | "عالي". OpenAI o1/o3 ونماذج الاستدلال GPT-5 وأي جهاز توجيه يتصل بها.
thinkingstring | objectOptional"على" | "إيقاف" | "تلقائي" للتبديل السريع، أو { type: "enabled"، Budget_tokens: N } للشكل البشري الأصلي. خرائط لكلود توسعت في التفكير، وتفكير الجوزاء، وتفكير DeepSeek.
thinking_budgetintegerOptionalالحد الأقصى من الرموز المميزة التي قد يستخدمها النموذج في التفكير قبل إصدار مخرجات مرئية. مرايا الميزانية_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 عام أو عنوان URL لبيانات base64؛ تعتمد حدود الحجم على النموذج الأولي.

نماذج مع دعم الرؤية

· 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

واجهة برمجة تطبيقات الرسائل المتوافقة مع البشر. يعمل مع المسؤول @anthropic-ai/sdk عن طريق الإعداد baseURL ل https://api.airforce. إعادة التوجيه إلى OpenAI/Google/إلخ. بشفافية بالنسبة للنماذج غير كلود.

POSThttps://api.airforce/v1/messages

هيئة الطلب

ParameterTypeRequiredDescription
modelstringRequiredمعرف النموذج (تنسيق إنساني أو اسم مستعار موجه).
messagesarrayRequiredكل إدخال: { الدور: "المستخدم" | "مساعد"، المحتوى: سلسلة | مصفوفة }.
max_tokensintegerRequiredمطلوب من قبل الأنثروبي. غطاء رمزي للاستجابة.
systemstring | arrayOptionalموجه النظام. تمرير مجموعة من النوع {: "نص"، نص، ذاكرة التخزين المؤقت_التحكم؟ } كتل لتمييز مقاطع البادئة المخزنة مؤقتًا. راجع "التخزين المؤقت الفوري".
temperaturefloatOptional0-1.
top_pfloatOptionalأخذ عينات النواة.
top_kintegerOptionalقصر تجمع العينات على رموز Top-K.
stop_sequencesarrayOptionalما يصل إلى 4 تسلسلات توقف.
streambooleanOptionalعندما يكون صحيحًا، يُصدر دفق أحداث SSE على النمط الأنثروبي (راجع "البث").
toolsarrayOptionalتعريفات الأداة الإنسانية: {الاسم، الوصف، مخطط الإدخال}. قد تحتوي الاستجابة على كتل محتوى tool_use.
tool_choiceobjectOptional{ النوع: "تلقائي" | "أي" | "أداة"، الاسم؟ }.
thinkingobjectOptionalالتفكير الإنساني الموسع: { النوع: "ممكّن"، رموز الميزانية: 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معرف الرسالة، على سبيل المثال. "msg_01ABCxyz".
typestringOptionalدائما "رسالة".
rolestringOptionalدائما "مساعد".
contentarrayOptionalمصفوفة كتل المحتوى: { النوع: "نص" | "استخدام_الأداة" | ""التفكير"،..."."
modelstringOptionalصدى النموذج المطلوب.
stop_reasonstringOptional"end_turn" | "max_tokens" | "stop_sequence" | "استخدام الأداة".
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?"}
  ]
}

كيف يتم الإبلاغ عن أعداد التخزين المؤقت في الاستجابة

يتم تمرير أعداد رموز التخزين المؤقت في الشكل الأصلي لكل تنسيق، لذا تقرأها 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.

POSThttps://api.airforce/v1/responses

أخطاء

تقوم Airforce بإرجاع رموز حالة HTTP القياسية ومغلف خطأ موحد لكلا نقطتي النهاية.

ParameterTypeRequiredDescription
400invalid_requestOptionalJSON غير صحيح، الحقل المطلوب مفقود، النموذج غير معروف.
401authentication_errorOptionalمفتاح API مفقود أو غير صالح.
403permission_errorOptionalترفض أذونات الخطة أو لكل مفتاح هذا الطلب.
429rate_limitOptionalتم تجاوز معدل الطلب أو الحد الأقصى اليومي للرمز المميز.
503upstream_errorOptionalفشلت كافة المفاتيح الأولية للموفر المطلوب.
{
  "error": {
    "message": "Model 'gpt-99' not found.",
    "type": "invalid_request",
    "param": "model",
    "code": "model_not_found"
  }
}

اكتشف النماذج

راجع القائمة الكاملة لمعرفات النماذج وعلامات قدراتها (الرؤية، الأدوات، الاستدلال، التخزين المؤقت، طول السياق، ...) على /docs/api/models.

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