Accéder au contenu
Français (France)
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 ne s’affiche 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.

Périmètres

Chaque clé possède des périmètres. L’API des modèles vérifie les suivants :

Action Périmètre requis
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’ancien 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é autorisée à 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 le périmètre approprié 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 (24 dernières heures), ou les deux. Avant de facturer une exécution, le coût est comparé à ce que la clé a déjà dépensé via cette API (remboursements déduits). 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’au 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é ne possède pas son propre budget.

Limites de débit

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

En-tête Signification
X-RateLimit-Limit Requêtes autorisées dans la fenêtre actuelle
X-RateLimit-Remaining Requêtes restantes dans 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 ; relancez-la lorsqu’une requête est terminée.