Chat Completions

Génère une réponse à partir d'une liste de messages. Compatible OpenAI Chat Completions.

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

Authentification#

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

Paramètres du corps#

Champ	Type	Défaut	Description
`model` requis	string	-	`mina-flash`, `mina-low` ou `mina-full`. Sinon `404`.
`max_cost_micro_dzd`	integer	-	Plafond de dépense en micro-DZD, uniquement avec `mina-auto`. La requête échoue si elle le dépasse.
`messages` requis	array	-	Liste non vide. Rôles : `system`, `developer` (= system), `user`, `assistant`, `tool`.
`max_tokens`	integer	4096	Jetons de sortie maximum. Plafonné par le modèle (8192 / 16384 / 32768) ; au-delà, `400`. Alias accepté : `max_completion_tokens`.
`temperature`	number	modèle	0 à 2. Bas = moins variable, sans garantie de réponses identiques.
`top_p`	number	modèle	Intervalle ]0, 1].
`stream`	boolean	false	Réponse en SSE (guide).
`stream_options`	object	-	`{"include_usage": true}` ajoute un dernier chunk avec `usage`.
`stop`	string ou array	-	4 séquences d'arrêt maximum.
`tools`	array	-	64 outils maximum (guide).
`tool_choice`	string ou object	auto	`auto` · `none` · `required` · `{"type":"function","function":{"name":"…"}}`
`response_format`	object	-	`{"type":"text"}` ou `{"type":"json_object"}`. `json_schema` refusé (`400`).
`frequency_penalty`, `presence_penalty`	number	0	−2 à 2.
`reasoning_effort`	string	-	`off` · `minimal` · `low` · `medium` · `high` · `xhigh` · `max` (guide).
`thinking`	object	modèle	`{"type":"enabled"}` ou `{"type":"disabled"}`. Prime sur le défaut du modèle.
`user`	string	-	Identifiant de votre utilisateur final : isole les limites de débit. Alphanumérique, ≤ 512.
`n`	integer	1	Seule la valeur 1 est acceptée.

Ignorés sans erreur : logprobs, top_logprobs, seed, logit_bias, parallel_tool_calls, service_tier, metadata.

Objet message#

Champ	Description
`role`	Rôle du message.
`content`	Chaîne, ou liste de blocs `{"type":"text","text":"…"}` et `{"type":"image_url","image_url":{"url":"…"}}` (Vision).
`tool_calls`	Sur un message `assistant` : appels demandés au tour précédent.
`tool_call_id`	Sur un message `tool` : identifiant de l'appel auquel il répond.
`name`	Nom optionnel de l'émetteur.

Requête#

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

Réponse#

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

Champ	Description
`id`	Identifiant de la complétion.
`model`	Toujours le modèle Mina demandé.
`choices[].message`	`content` et, le cas échéant, `tool_calls`.
`finish_reason`	`stop` (terminé) · `length` (`max_tokens` atteint) · `tool_calls` (outil demandé).
`usage`	Jetons facturés : source de vérité.

En-têtes de réponse#

En-tête	Description
`X-Request-Id`	Identifiant unique de la requête (UUID) : à fournir au support. Un `X-Request-ID` envoyé par le client est repris tel quel.
`X-RateLimit-Limit-Requests`	RPM de votre palier.
`X-RateLimit-Remaining-Requests`	Requêtes restantes dans la fenêtre.
`Retry-After`	Sur `429`/`503` : secondes avant réessai.

Réponse en streaming#

Avec "stream": true, la réponse est un flux SSE d'objets chat.completion.chunk terminé par data: [DONE]. Structure détaillée dans le guide Streaming.

Codes d'erreur#

400, 401, 402, 403, 404, 429, 500, 503 : voir Codes d'erreur.