Passer au contenu
Français (Canada)
Obtenir une clé API
Guide de l’API

Authentification

Afficher en Markdown Mis à jour

Tout appel qui exécute un modèle ou lit vos requêtes nécessite une clé API. Le catalogue (GET /models, GET /categories), POST /quote et le document OpenAPI sont publics.

Clés API

Créez et révoquez des clés à l’adresse https://doitong.com/developers/dashboard#keys. Une clé ressemble à doitong_ suivi de 64 caractères hexadécimaux et n’est affichée qu’une seule fois, lors de sa création. Envoyez-la dans l’en-tête Authorization :

terminal
curl https://api.doitong.com/v1/account -H "Authorization: Bearer $DOITONG_API_KEY"

X-API-Key: <key> fonctionne également.

Une requête sans clé reçoit 401 avec le code missing_api_key; une clé inconnue, révoquée ou expirée reçoit également 401.

Portées

Chaque clé possède des portées. L’API des modèles vérifie les suivantes :

Action Portée requise
Exécuter un modèle, annuler une requête, supprimer les fichiers d’une requête, modifier le paramètre de stockage models:run (les clés avec l’ancienne portée images:create ou videos:create fonctionnent également)
Créer une URL d’envoi models:run ou media:upload
Lire les requêtes et le compte models:read (une clé qui peut exécuter des modèles peut également les lire)

Les nouvelles clés reçoivent models:read et models:run par défaut. Un appel sans la portée appropriée reçoit 403 avec le code insufficient_scope.

Budgets de crédits

Une clé peut avoir son propre budget en crédits API (1 000 crédits API = 1 $), défini par le propriétaire du compte : un budget total, un budget quotidien (les dernières 24 heures), ou les deux. Avant de facturer une exécution, le coût est comparé à ce que la clé a déjà dépensé par l’intermédiaire de cette API (après déduction des remboursements). Une exécution qui le dépasserait est refusée avec 402 budget_exceeded et rien n’est facturé.

Une clé sans budget peut dépenser jusqu’à concurrence du solde API. Par ailleurs, une exécution que le solde API ne peut pas couvrir reçoit 402 insufficient_credits avec un top_up_url.

GET https://api.doitong.com/v1/account affiche le solde API et le budget restant de la clé (tous deux en crédits API) :

200 OK · account
{
  "object": "account",
  "credits": 125000,
  "balance": { "credits": 125000, "usd": "125.00" },
  "top_up_url": "https://doitong.com/developers/dashboard#balance",
  "key": {
    "name": "Production server",
    "prefix": "doitong_3fa9c1e...",
    "scopes": ["models:read", "models:run"],
    "budget_remaining": 50000,
    "rate_limit": 3600,
    "rate_limit_remaining": 3571
  },
  "webhook_signing_secret": "whsec_..."
}

budget_remaining vaut null lorsque la clé n’a pas de budget propre.

Limites de débit

Chaque clé peut effectuer 3600 requêtes par heure, sauf si sa limite a été définie autrement. Chaque réponse authentifiée contient l’état actuel :

En-tête Signification
X-RateLimit-Limit Requêtes autorisées pendant la fenêtre actuelle
X-RateLimit-Remaining Requêtes restantes pendant la fenêtre actuelle
X-RateLimit-Reset Heure Unix de réinitialisation de la fenêtre

Au-delà de la limite, vous recevez 429 avec un en-tête Retry-After (secondes). L’interrogation longue avec ?wait= compte comme une requête par appel; attendre coûte donc moins cher qu’interroger rapidement.

Il existe également une limite de 10 requêtes en cours (queued ou running) par compte. Le démarrage d’une requête supplémentaire renvoie 429 too_many_inflight; démarrez-la de nouveau lorsqu’une autre est terminée.