Limites de requêtes de l'API

Les 5 niveaux

Chaque requête passe par cinq contrôles. Le premier qui refuse l'emporte.

Plafonds quotidiens par endpoint

Certains endpoints ont des limites plus strictes car ils consomment beaucoup de CPU ou de GPU :

Taille maximale des fichiers

• 200 Mo par fichier pour l'API (contre 100 Mo sur le site web).
• Certains outils IA lourds ont des limites internes plus basses — par exemple upscale-image est plafonné à 20 Mo pour garder les traitements GPU sous les 2 minutes.

Headers sur chaque réponse

Chaque réponse API réussie inclut les headers suivants pour que vous puissiez suivre votre quota sans interroger /api/v1/limits :

X-RateLimit-Limit-Day: 1000
X-RateLimit-Remaining-Day: 873
X-RateLimit-Reset-Day: 1775865600     # unix timestamp
X-RateLimit-Limit-Hour: 150
X-RateLimit-Remaining-Hour: 142
X-RateLimit-Limit-Endpoint: 50
X-RateLimit-Remaining-Endpoint: 38

Que se passe-t-il quand vous atteignez une limite

L'API renvoie 429 Too Many Requests avec un header Retry-After (en secondes) et un header X-RateLimit-Reason indiquant quel niveau a été touché :

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Reason: cooldown

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded (cooldown). Retry after 1 seconds.",
    "details": { "reason": "cooldown", "retry_after": 1 }
  }
}

Valeurs possibles pour X-RateLimit-Reason : cooldown, burst, hourly, daily, endpoint:<name>, banned.

Escalade vers le ban

Des abus répétés déclenchent un ban temporaire. Concrètement : 10 refus de rate limit en 1 heure depuis la même IP → ban de 24 heures avec HTTP 403 Forbidden et error.code: BANNED.

Si vous pensez avoir été banni injustement (par exemple parce que vous partagez une IP avec beaucoup d'utilisateurs), contactez-nous sur /contact et nous examinerons le cas.

Bonnes pratiques pour éviter l'étranglement

• Attendez au moins 1 seconde entre deux requêtes consécutives (ou utilisez le header Retry-After sur les 429).
• Utilisez les endpoints batch pour le traitement en masse : POST /api/v1/batch accepte jusqu'à 20 fichiers en un seul appel HTTP (chaque fichier compte toujours dans votre quota quotidien, mais vous économisez les allers-retours).
• Surveillez les headers : quand X-RateLimit-Remaining-Day descend sous 100, ralentissez ou mettez vos résultats en cache.
• Vérifiez votre usage à tout moment avec GET /api/v1/limits — cet endpoint ne compte PAS dans votre quota.
• Ne relancez pas instantanément sur un 429 — respectez Retry-After. Les relances immédiates peuvent déclencher l'escalade vers un ban.

Besoin de limites plus hautes ?

Les limites actuelles sont des valeurs par défaut MVP. Nous observons l'usage réel et les ajusterons selon la demande. Si vous avez un cas d'usage légitime nécessitant des quotas plus élevés, contactez-nous via /contact.

Une future offre payante pourra proposer des quotas dédiés, des files prioritaires et une rétention de fichiers plus longue — mais l'offre gratuite restera toujours disponible.