Authentification et conventions de base

Cette page décrit les conventions communes à toutes les interfaces : adresse de base, authentification, format des requêtes et des réponses, pagination, limitation de débit, idempotence et gestion des erreurs. Pour les paramètres et exemples de chaque interface, voir Vue d'ensemble des interfaces ainsi que la page dédiée à chaque interface.

Adresse de base

Authentification

Toutes les interfaces utilisent la même clé API de plateforme :

Authorization: Bearer sk-你的APIKey
Content-Type: application/json

Le préfixe Bearer peut être omis (mais ce n'est pas recommandé)

Quatre écritures testées :

La plateforme accepte également le jeton brut ; par conséquent, un retour 200 ne signifie pas que le client est correctement configuré. À l'inverse, si un client renvoie 401, vérifiez d'abord s'il omet complètement l'en-tête Authorization, plutôt que de suspecter directement la clé elle-même. Utilisez toujours l'écriture Bearer.

Lorsque la clé API est absente, incorrecte, désactivée ou n'appartient pas au compte actuel, l'interface renvoie HTTP 401 :

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)",
    "type": "new_api_error"
  }
}

Attention : code est une chaîne vide. En cas d'échec d'authentification, la plateforme ne remplit pas code ; par conséquent, ne déterminez pas si une requête a échoué en fonction du fait que code est vide ; basez-vous sur le code de statut HTTP. Le request id présent dans message peut être extrait directement pour ouvrir un ticket.

Ce type d'échec d'authentification a une structure identique sur toutes les interfaces, et message contient l'identifiant de la requête pour faciliter le diagnostic.

Structure des réponses

La plateforme utilise trois structures de réponse ; le client doit toujours vérifier à la fois le code de statut HTTP et le corps de la réponse.

Interfaces de modèle, texte, image, vidéo et audio

En cas de succès, l'objet de résultat est renvoyé directement ; en cas d'échec, un code HTTP non 2xx est renvoyé avec un objet error :

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

La consultation d'une tâche vidéo est une exception : lorsqu'une tâche est introuvable, l'interface renvoie 400 avec un corps de réponse au niveau racine { code, message, data } (code vaut la chaîne task_not_exist), et non l'objet error décrit ci-dessus. Voir Codes d'erreur et diagnostic. Les valeurs de code, type et param varient selon le type d'erreur ; lors du diagnostic, fiez-vous principalement à message et ne vous contentez pas de faire correspondre un texte code fixe.

Interfaces de la bibliothèque de ressources

Les succès et les échecs utilisent une structure unifiée :

{ "code": 0, "data": {}, "msg": "OK" }

{ "code": 401, "data": null, "msg": "API Key 无效或已失效" }

En cas d'échec, le code de statut HTTP correspond à code (400 / 401 / 404 / 429 / 502 / 503). Une revue de ressource non terminée n'est pas une erreur : elle est indiquée par le champ status dans une réponse 200 (Processing / Active / Failed).

Pagination

Les interfaces de liste telles que les groupes de ressources et la liste des ressources utilisent des paramètres de pagination uniformes :

Dans la réponse, data.total est le nombre total d'éléments, et data.page / data.page_size sont les paramètres de pagination effectivement appliqués. Lisez toujours total pour déterminer s'il reste une page suivante, et non le « nombre d'éléments renvoyés cette fois ».

Limitation de débit et nouvelles tentatives

Ne réessayez que pour 429 et les 5xx passagers ; 400, 401, 403, 404 et 409 relèvent de problèmes de requête ou de permissions, et une nouvelle tentative n'aboutira pas.

Idempotence et soumissions en double

La plateforme ne fournit pas de clé d'idempotence automatique inter-interfaces ; assurez-vous côté métier de ne soumettre qu'une seule fois :

• pour chaque action utilisateur, enregistrez d'abord un enregistrement métier dans votre propre base de données, puis appelez l'interface de la plateforme ;
• pour les tâches vidéo et la soumission de ressources, enregistrez l'ID renvoyé par la plateforme et, avant de réessayer, vérifiez si l'élément a déjà été créé ;
• ne soumettez pas à nouveau une ressource en cours de traitement (Processing), sinon plusieurs copies seront créées ;
• la facturation se base sur les tâches effectivement soumises avec succès ; une soumission en double entraîne une double facturation.

Ordre d'appel recommandé

GET  /v1/models                     选择模型，确认能力与可用性
POST /api/v1/materials/groups       需要素材时创建分组
POST /api/v1/materials/assets       提交图片，保存 asset_id
GET  /api/v1/materials/assets/{id}  轮询到 status 为 Active
POST /v1/video/generations          提交视频任务，用 asset://<id> 引用素材
GET  /v1/video/generations/{id}     轮询任务，读取结果或错误

Recommandations d'intégration côté serveur

1. définissez un délai d'attente raisonnable pour chaque requête et distinguez « délai dépassé » et « annulation par l'utilisateur » ;
2. effectuez un nombre limité de nouvelles tentatives avec backoff pour 429 et les 5xx passagers ; renvoyez directement les autres erreurs à l'appelant ;
3. enregistrez le numéro de requête métier, l'ID du modèle, l'ID de la ressource, l'ID de la tâche et l'identifiant de requête renvoyé par la plateforme, pour faciliter le diagnostic ;
4. n'inscrivez pas la clé API dans les journaux, le reporting d'erreurs, le suivi côté frontend ou les captures d'écran ;
5. pour les fichiers volumineux, privilégiez une adresse HTTPS publique de stockage objet ou une référence asset:// de la bibliothèque de ressources ; ne les intégrez pas dans le corps de la requête.

Étape suivante