Limitation du débit

Les limites protègent la plateforme des pics et garantissent un service régulier à tous. Elles s'appliquent par clé API, et vous pouvez les subdiviser vous-même entre vos propres utilisateurs finaux.

Les deux limites#

Limites par palier#

Le palier est attaché à chaque clé et fixé à sa création : c'est le palier par défaut de la plateforme, standard à ce jour, y compris pour la première clé d'un compte neuf et sans recharge préalable. Il est indiqué pour chaque clé dans API keys. Besoin de plus ? Écrivez-nous depuis Help & Feedback en précisant votre volume cible : le passage en pro est gratuit, il sert juste à protéger la capacité partagée.

En-têtes de réponse#

Les réponses des endpoints de génération portent l'état de votre fenêtre courante (les endpoints de consultation, comme la liste des modèles ou le solde, n'en posent pas) :

X-Request-Id: 4334a6f1-5889-4999-92b6-8d8fb538dbe4
X-RateLimit-Limit-Requests: 300
X-RateLimit-Remaining-Requests: 287

Conservez X-Request-Id dans vos journaux : c'est la référence à donner au support pour retrouver une requête précise. Si vous envoyez vous-même un en-tête X-Request-ID, il est repris tel quel, pratique pour recoller vos traces aux nôtres.

Isolement par utilisateur final#

Si vous exposez CloudZIR à vos propres clients, transmettez leur identifiant : la fenêtre RPM est alors comptée séparément pour chacun. Un utilisateur qui abuse ne bloque plus les autres.

{
  "model": "mina-low",
  "messages": [{"role": "user", "content": "Bonjour"}],
  "user": "client-4821"
}

{
  "model": "mina-low",
  "max_tokens": 512,
  "messages": [{"role": "user", "content": "Bonjour"}],
  "metadata": {"user_id": "client-4821"}
}

Contraintes : chaîne alphanumérique (tiret et souligné acceptés), 512 caractères maximum. N'y mettez jamais de donnée personnelle (email, téléphone) : utilisez un identifiant opaque.

Bien réagir à un 429#

Un 429 n'est pas une erreur de votre code : c'est une invitation à ralentir. Respectez Retry-After et ajoutez une attente exponentielle avec jitter.

import random, time
import httpx

def appeler_avec_reprise(payload, cle, essais=5):
    for tentative in range(essais):
        r = httpx.post(
            "https://api.cloudzir.com/v1/chat/completions",
            headers={"Authorization": f"Bearer {cle}"},
            json=payload,
            timeout=120,
        )
        if r.status_code not in (429, 503):
            r.raise_for_status()
            return r.json()
        attente = float(r.headers.get("Retry-After", 2 ** tentative))
        time.sleep(attente + random.uniform(0, 0.5))   # jitter
    raise RuntimeError("Limite de débit persistante")

async function appelerAvecReprise(payload, cle, essais = 5) {
  for (let t = 0; t < essais; t++) {
    const r = await fetch("https://api.cloudzir.com/v1/chat/completions", {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${cle}` },
      body: JSON.stringify(payload),
    });
    if (r.status !== 429 && r.status !== 503) {
      if (!r.ok) throw new Error(await r.text());
      return r.json();
    }
    const attente = Number(r.headers.get("Retry-After") ?? 2 ** t) * 1000;
    await new Promise((res) => setTimeout(res, attente + Math.random() * 500));
  }
  throw new Error("Limite de débit persistante");
}

Attente pendant les pics#

Quand un moteur démarre à froid, la connexion est maintenue ouverte plutôt que coupée :

• en streaming : des commentaires SSE : keep-alive sont envoyés toutes les 15 secondes, votre client SSE les ignore, ce sont des lignes de commentaire ;
• en non-streaming : la requête reste simplement en attente.

Prévoyez un timeout client d'au moins 120 secondes sur mina-full ; un timeout trop court coupe des requêtes qui allaient aboutir (et qui vous seront tout de même facturées si le modèle a déjà produit du texte).

Si toute la capacité est saturée#

L'API renvoie 503 overloaded avec Retry-After. Cette réponse n'est jamais facturée. Traitez-la comme un 429 : réessayez avec attente.