TokenLab

Guides médias

Migrer Seedance depuis Volcengine

Conservez votre format de requête Volcengine et migrez Seedance vers TokenLab

Si votre application utilise déjà l'API Seedance de Volcengine, vous pouvez conserver ses chemins REST, le corps content[], les champs de réponse, les callbacks et les Actions de matériel en PascalCase. Modifiez l'hôte de l'API et remplacez la signature AK/SK par une clé API TokenLab.

Ce qui change

ChangementClient Volcengine existantTokenLab
URL de baseVotre endpoint Volcenginehttps://api.tokenlab.sh/
AuthentificationSignature de requête AK/SKAuthorization: Bearer <TOKENLAB_API_KEY>
Transport de tâcheChemins REST officiels /api/v3/contents/generations/tasksConservé
Actions de matériel/validationParamètres de requête Action et VersionConservés
Corps de tâchecontent[] style VolcengineConservé
Corps de matérielChamps PascalCase tels que GroupId et ProjectNameConservés
Résultat asynchroneCycle de vie de tâche VolcengineID de tâche TokenLab cgt-... avec polling et callback optionnel

Les requêtes signées uniquement avec AK/SK renvoient 401 AuthenticationError. Chaque requête TokenLab doit inclure Authorization: Bearer <TOKENLAB_API_KEY>.

Choisir un endpoint

Client existantEndpoint TokenLab
Client de tâche REST Volcengine/api/v3/contents/generations/tasks et ses chemins de tâche
Client d'Action de matériel ou de validationPOST /?Action=...&Version=2024-01-01 ou POST /api/v3?Action=...&Version=2024-01-01

Pour les tâches vidéo, conservez la méthode REST, le chemin et le corps JSON existants. Les requêtes de matériel et de vérification continuent d'utiliser les paramètres de requête Action et Version. L'endpoint Action accepte également les Actions de tâche CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks et DeleteContentsGenerationsTasks ; utilisez les chemins REST pour les nouveaux travaux.

Chemins de tâche officiels

Méthode et cheminObjectif
POST /api/v3/contents/generations/tasksCréer une tâche vidéo
GET /api/v3/contents/generations/tasks/{id}Lire une tâche
GET /api/v3/contents/generations/tasksLister les tâches
DELETE /api/v3/contents/generations/tasks/{id}Annuler une tâche en file d'attente. Une tâche ayant démarré renvoie 409 task_not_cancellable

Les clients REST peuvent utiliser ces références équivalentes :

Règles du corps de requête

  • content[] accepte les éléments text, image_url, video_url, audio_url et draft_task.
  • Pour image_url, omettez role ou utilisez first_frame pour la conversion image-vers-vidéo. Utilisez last_frame avec une première image, ou reference_image pour la conversion référence-vers-vidéo.
  • Un URI de matériel public tel que asset://asset-YYYYMMDDHHMMSS-xxxxx peut être utilisé là où le flux de travail Seedance sélectionné accepte ce rôle de média.
  • Le corps REST n'accepte que les champs officiels, incluant model, content, ratio, duration, resolution, generate_audio, watermark, return_last_frame, seed, execution_expires_after et safety_identifier. Les valeurs par défaut dépendent du modèle : generate_audio est false pour les modèles seedance-2.0 et true pour seedance-2.5, et duration est 5 pour les modèles seedance-2.0 et -1 pour seedance-2.5. Ce format REST accepte les valeurs de resolution 480p, 720p et 1080p (480p et 720p pour seedance-2.5) mais pas 4k, qui n'est accepté que par l'API unifiée /v1/videos/generations. seedance-2.5 rejette seed, frames et camera_fixed.
  • callback_url accepte un endpoint HTTP(S) public. TokenLab envoie le même corps de tâche pour queued, running, succeeded, failed et expired ; seuls succeeded et failed suivent le comportement officiel : un délai d'attente de cinq secondes et une nouvelle tentative si votre endpoint n'accuse pas réception de la notification.

Exemple REST minimal

curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Idempotency-Key: $CLIENT_JOB_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "content": [
      {"type":"text","text":"A cinematic product reveal"},
      {"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p"
  }'

Stockez l'ID cgt-... renvoyé. Effectuez un polling jusqu'à ce que le status devienne succeeded, failed, cancelled ou expired ; ne considérez pas la réponse de création comme une vidéo terminée. Si vous fournissez une callback_url, autorisez les notifications répétées de succeeded ou failed et continuez le polling comme chemin de récupération.

Gardez les types v1 et v3 séparés

Ne réutilisez pas une structure de réponse /v1/tasks/{id} pour cet endpoint. L'API v1 unifiée rapporte pending, processing, completed et failed ; l'API v3 compatible Volc rapporte queued, running, succeeded, failed, cancelled et expired. La réponse v3 officielle représente également duration sous forme de chaîne JSON et omet error sur les tâches non échouées.

Pour une récupération sécurisée après un délai d'attente de création ou une déconnexion, ajoutez un Idempotency-Key unique à la requête de création REST. Réessayer le même corps avec la même clé renvoie l'ID cgt-... original ; la même clé avec un corps différent renvoie 409.

Matériels et vérification de personne réelle

Le même endpoint Action prend également en charge les 10 opérations de matériel et de groupe de matériel. Consultez Actions de matériel (Compatible Volc) pour leurs corps PascalCase exacts, filtres, pagination, enveloppe de réponse et URLs de matériel de 12 heures.

Les matériels de personne réelle ajoutent deux Actions avant le téléchargement :

  1. Créer une session de validation visuelle
  2. Obtenir le résultat de validation visuelle

La seconde Action renvoie le GroupId vérifié. Utilisez cet ID avec CreateAsset ; un client ne peut pas créer un groupe LivenessFace directement.

Liste de contrôle de migration

  1. Remplacez l'hôte de l'API par https://api.tokenlab.sh.
  2. Remplacez la signature AK/SK par une clé API Bearer TokenLab.
  3. Conservez la méthode, le chemin et la casse du corps de requête de tâche REST officiels ; conservez Action et version uniquement pour les opérations de matériel ou de validation.
  4. Conservez le même ProjectName à travers les requêtes de matériel et de vérification associées.
  5. Stockez les IDs de tâche, de groupe et d'asset TokenLab renvoyés par ces endpoints.
  6. Vérifiez une réponse de création, de polling, de liste et d'erreur avant de basculer le trafic de production.

Sur cette page