Limites et quotas

Ce qui borne vos appels, et comment le lire depuis votre code. Toutes ces limites sont administrées : elles changent sans redéploiement, et votre code doit donc les lire plutôt que les supposer.

Débit#

Chaque clé porte un débit en requêtes par minute et un nombre d'appels simultanés. Les deux sont attachés à la clé, pas au compte : séparer vos clés par environnement évite qu'un script de test affame votre production.

Quand le débit est atteint, la réponse est 429 et porte Retry-After, en secondes. Respectez-le. Réessayer plus tôt n'accélère rien et aggrave la charge au moment où le service en a le moins besoin.

HTTP/1.1 429 Too Many Requests
Retry-After: 3

Et si vous réessayez, ajoutez un peu d'aléa à votre attente. Sans cela, tous vos processus bloqués en même temps reviendront en même temps, c'est ce qui transforme un ralentissement passager en panne.

Taille des requêtes#

Le corps d'une requête est borné. Au-delà, la réponse est 413 avant même que le contenu soit lu : refuser tôt coûte moins cher que charger en mémoire ce qu'on va rejeter.

Pour un document volumineux, passez par l'API Fichiers et référencez l'identifiant. C'est ce à quoi elle sert.

Fenêtre de contexte et sortie#

Chaque modèle a sa fenêtre de contexte et son plafond de jetons produits. Ne les codez pas en dur : ils sont servis par GET /v1/pricing, et c'est la seule source qui dit ce que la passerelle applique réellement.

curl https://api.cloudzir.com/v1/pricing

{
  "object": "list",
  "data": [
    {
      "model": "mina-flash",
      "currency": "DZD",
      "unit": "per_million_tokens",
      "input": 250.0,
      "cached_input": 8.0,
      "output": 700.0,
      "context_window": 64000,
      "max_output_tokens": 8192,
      "description": "Tout ce que fait Mina, à la vitesse maximale et au coût le plus bas. Le bon choix quand la réponse doit être immédiate et le volume élevé."
    }
  ]
}

L'exemple montre un seul modèle : la liste contient un objet par modèle activé.

Cette route ne demande pas de clé : la page de vente, la documentation et votre application lisent la même chose.

Solde#

Un solde nul provoque des 402 sur tous les appels facturés qui suivent. Surveillez-le avec le point de solde plutôt que de découvrir la coupure en production.

total_balance est rendu comme une chaîne à quatre décimales, pas comme un nombre flottant. Ce n'est pas une bizarrerie : un flottant ferait perdre des centimes à chaque relecture, et un solde qui dérive de quelques centimes par jour finit par ne plus correspondre à vos écritures.

Mise en cache#

Les jetons d'entrée déjà vus sont facturés au tarif cached_input, nettement plus bas. Le bloc usage de chaque réponse détaille ce qui a été mis en cache :

"usage": {
  "prompt_tokens": 148,
  "completion_tokens": 12,
  "total_tokens": 160,
  "prompt_tokens_details": { "cached_tokens": 96 },
  "prompt_cache_hit_tokens": 96,
  "prompt_cache_miss_tokens": 52
}

Ces champs sont là pour que vous puissiez vérifier ce qu'on vous compte, pas seulement pour l'observer. Voir la mise en cache du contexte pour structurer vos requêtes de façon à en profiter.

Ce qui n'est pas une limite technique#

Les quotas commerciaux d'un forfait (nombre de messages, enveloppe de générations) sont distincts des bornes ci-dessus. Les premiers sont des allocations, révisables depuis l'administration. Les secondes sont des garde-fous : elles protègent le service, et aucune allocation commerciale ne peut les désactiver.