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
| Changement | Client Volcengine existant | TokenLab |
|---|---|---|
| URL de base | Votre endpoint Volcengine | https://api.tokenlab.sh/ |
| Authentification | Signature de requête AK/SK | Authorization: Bearer <TOKENLAB_API_KEY> |
| Transport de tâche | Chemins REST officiels /api/v3/contents/generations/tasks | Conservé |
| Actions de matériel/validation | Paramètres de requête Action et Version | Conservés |
| Corps de tâche | content[] style Volcengine | Conservé |
| Corps de matériel | Champs PascalCase tels que GroupId et ProjectName | Conservés |
| Résultat asynchrone | Cycle de vie de tâche Volcengine | ID 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 existant | Endpoint 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 validation | POST /?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 chemin | Objectif |
|---|---|
POST /api/v3/contents/generations/tasks | Créer une tâche vidéo |
GET /api/v3/contents/generations/tasks/{id} | Lire une tâche |
GET /api/v3/contents/generations/tasks | Lister 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 :
- Créer une tâche (Compatible Volc)
- Obtenir une tâche (Compatible Volc)
- Lister les tâches (Compatible Volc)
- Annuler une tâche (Compatible Volc)
Règles du corps de requête
content[]accepte les élémentstext,image_url,video_url,audio_urletdraft_task.- Pour
image_url, omettezroleou utilisezfirst_framepour la conversion image-vers-vidéo. Utilisezlast_frameavec une première image, oureference_imagepour la conversion référence-vers-vidéo. - Un URI de matériel public tel que
asset://asset-YYYYMMDDHHMMSS-xxxxxpeut ê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_afteretsafety_identifier. Les valeurs par défaut dépendent du modèle :generate_audioestfalsepour les modèlesseedance-2.0ettruepourseedance-2.5, etdurationest5pour les modèlesseedance-2.0et-1pourseedance-2.5. Ce format REST accepte les valeurs deresolution480p,720pet1080p(480pet720ppourseedance-2.5) mais pas4k, qui n'est accepté que par l'API unifiée/v1/videos/generations.seedance-2.5rejetteseed,framesetcamera_fixed. callback_urlaccepte un endpoint HTTP(S) public. TokenLab envoie le même corps de tâche pourqueued,running,succeeded,failedetexpired; seulssucceededetfailedsuivent 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 :
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
- Remplacez l'hôte de l'API par
https://api.tokenlab.sh. - Remplacez la signature AK/SK par une clé API Bearer TokenLab.
- 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.
- Conservez le même
ProjectNameà travers les requêtes de matériel et de vérification associées. - Stockez les IDs de tâche, de groupe et d'asset TokenLab renvoyés par ces endpoints.
- Vérifiez une réponse de création, de polling, de liste et d'erreur avant de basculer le trafic de production.