Chat Completions

يولّد استجابة انطلاقًا من قائمة رسائل. متوافقة مع OpenAI Chat Completions.

POST https://api.cloudzir.com/v1/chat/completions

المصادقة#

Authorization: Bearer zir_ai_<48 caractères hexadécimaux>
Content-Type: application/json

معاملات الجسم#

الحقل	النوع	الافتراضي	الوصف
`model` إلزامي	string	-	`mina-flash` أو `mina-low` أو `mina-full`. وإلا `404`.
`max_cost_micro_dzd`	integer	-	سقف إنفاق بالميكرو دينار جزائري، متاح فقط مع `mina-auto`. يفشل الطلب إذا تجاوزه.
`messages` إلزامي	array	-	قائمة غير فارغة. الأدوار : `system`، `developer` (= system)، `user`، `assistant`، `tool`.
`max_tokens`	integer	4096	أقصى رموز إخراج. محدود بسقف النموذج (8192 / 16384 / 32768) ؛ وإلا `400`. الاسم البديل المقبول : `max_completion_tokens`.
`temperature`	number	النموذج	0 إلى 2. منخفض = أقل تباينًا، دون ضمان استجابات متطابقة.
`top_p`	number	النموذج	المجال ]0, 1].
`stream`	boolean	false	استجابة بصيغة SSE (الدليل).
`stream_options`	object	-	`{"include_usage": true}` يضيف قطعة أخيرة بحقل `usage`.
`stop`	string أو array	-	4 سلاسل توقف كحد أقصى.
`tools`	array	-	64 أداة كحد أقصى (الدليل).
`tool_choice`	string أو object	auto	`auto` · `none` · `required` · `{"type":"function","function":{"name":"…"}}`
`response_format`	object	-	`{"type":"text"}` أو `{"type":"json_object"}`. `json_schema` مرفوض (`400`).
`frequency_penalty`، `presence_penalty`	number	0	−2 إلى 2.
`reasoning_effort`	string	-	`off` · `minimal` · `low` · `medium` · `high` · `xhigh` · `max` (الدليل).
`thinking`	object	النموذج	`{"type":"enabled"}` أو `{"type":"disabled"}`. له الأولوية على افتراضي النموذج.
`user`	string	-	معرّف مستخدمكم النهائي : يعزل حدود المعدل. أبجدي رقمي، ≤ 512.
`n`	integer	1	القيمة 1 فقط مقبولة.

مُتجاهَلة دون خطأ : logprobs، top_logprobs، seed، logit_bias، parallel_tool_calls، service_tier، metadata.

كائن الرسالة#

الحقل	الوصف
`role`	دور الرسالة.
`content`	سلسلة نصية، أو قائمة كتل `{"type":"text","text":"…"}` و`{"type":"image_url","image_url":{"url":"…"}}` (الرؤية).
`tool_calls`	في رسالة `assistant` : الاستدعاءات المطلوبة في الجولة السابقة.
`tool_call_id`	في رسالة `tool` : معرّف الاستدعاء الذي تجيب عنه.
`name`	اسم اختياري للمُرسِل.

الطلب#

curl https://api.cloudzir.com/v1/chat/completions \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mina-low",
    "messages": [
      {"role": "system", "content": "Tu es un assistant concis."},
      {"role": "user", "content": "Cite trois wilayas côtières."}
    ],
    "max_tokens": 200,
    "temperature": 0.3
  }'

الاستجابة#

{
  "id": "chatcmpl-4334a6f158894999",
  "object": "chat.completion",
  "created": 1766400000,
  "model": "mina-low",
  "choices": [
    {
      "index": 0,
      "message": {"role": "assistant", "content": "Alger, Oran et Béjaïa."},
      "finish_reason": "stop"
    }
  ],
  "usage": {"prompt_tokens": 28, "completion_tokens": 9, "total_tokens": 37}
}

الحقل	الوصف
`id`	معرّف الإكمال.
`model`	دائمًا نموذج Mina المطلوب.
`choices[].message`	`content` وعند الاقتضاء `tool_calls`.
`finish_reason`	`stop` (انتهى) · `length` (بلغ `max_tokens`) · `tool_calls` (طُلبت أداة).
`usage`	الرموز المفوترة؛ مصدر الحقيقة.

ترويسات الاستجابة#

الترويسة	الوصف
`X-Request-Id`	معرّف فريد للطلب (UUID) : يُقدَّم للدعم. أي `X-Request-ID` يرسله العميل يُعاد كما هو.
`X-RateLimit-Limit-Requests`	RPM مستواكم.
`X-RateLimit-Remaining-Requests`	الطلبات المتبقية في النافذة.
`Retry-After`	على `429`/`503` : ثوانٍ قبل إعادة المحاولة.

الاستجابة بالبث المباشر#

مع "stream": true، الاستجابة تدفق SSE من كائنات chat.completion.chunk ينتهي بـdata: [DONE]. البنية مفصّلة في دليل البث المباشر.

أكواد الأخطاء#

400، 401، 402، 403، 404، 429، 500، 503؛ انظروا أكواد الأخطاء.

استجابة API