TokenLab

Vidéo & ressources

Créer une tâche (Compatible Volc)

Créer une tâche Seedance avec l'API compatible Volc.

POST
/api/v3/contents/generations/tasks

Aperçu

Les clients Seedance existants de style Volc peuvent utiliser TokenLab en modifiant l'adresse API et la clé.

Les exemples utilisent Seedance 2.0. Ce point de terminaison prend également en charge Seedance 2.5 avec les différences spécifiques au modèle ci-dessous. Les exemples d'URI de matériel TokenLab réutilisables sur cette page s'appliquent à Seedance 2.0.

Voir aussi Modèles vidéo Seedance 2.0 et Génération de vidéo.

Authentification et points de terminaison

  • Utilisez Authorization: Bearer <TOKENLAB_API_KEY>.
  • La signature Volc AK/SK n'est pas acceptée. Les requêtes doivent inclure une clé Bearer TokenLab.
  • Utilisez le chemin de tâche officiel : POST /api/v3/contents/generations/tasks.

Règles de contenu

  • type: "text" correspond au texte de l'invite (prompt).
  • type: "image_url" sans role, ou avec role: "first_frame", est traité comme la première image.
  • role: "last_frame" doit être associé à une première image.
  • type: "video_url" nécessite role: "reference_video", et type: "audio_url" nécessite role: "reference_audio". role: "reference_image" marque une image de référence.
  • Limites d'éléments : Seedance 2.0 accepte jusqu'à 16 éléments content (1 texte, 9 images, 3 vidéos, 3 audios, 1 draft_task). Seedance 2.5 accepte jusqu'à 51 éléments (1 texte, 30 images, 10 vidéos, 10 audios, 1 draft_task).
  • image_url.url accepte une URL d'image publique ou un URI de matériel tel que asset://asset-YYYYMMDDHHMMSS-xxxxx. Le role détermine si ce matériel est une première image, une dernière image ou une image de référence.
  • Ne mélangez pas les entrées de première/dernière image avec des médias de référence dans une même requête.
  • Le corps REST n'accepte que les champs présents sur cette page. Tout autre champ de niveau supérieur, y compris material_asset_id et material_asset_ids, renvoie 400 UnsupportedParameter. Placez un URI de matériel TokenLab dans image_url.url.

Notes sur les paramètres

model accepte un ID de modèle TokenLab tel que seedance-2.0 ou seedance-2.5. Les clients existants peuvent continuer à envoyer l'ID de modèle Volcengine qu'ils utilisent déjà pour ces modèles. La réponse get-task renvoie la valeur model que vous avez envoyée. Une valeur non reconnue renvoie 400 InvalidParameter.

duration est un nombre entier de secondes ; -1 sélectionne la durée automatique. Les valeurs par défaut et les limites diffèrent selon le modèle :

ParamètreSeedance 2.0Seedance 2.5
duration4–15 / -1 (par défaut : 5)4–30 / -1 (par défaut : -1)
resolution480p, 720p, 1080p (par défaut : 720p)480p, 720p (par défaut : 720p)
generate_audioboolean (par défaut : false)boolean (par défaut : true)
priorityNon pris en chargeinteger : 0–9
seedinteger : -1–4294967295 (par défaut : -1)Non pris en charge
execution_expires_after3600–259200 secondes (par défaut : 172800)3600–259200 secondes (par défaut : 172800)

Pour Seedance 2.5, les requêtes de première image, première/dernière image, extension vidéo et vidéo-à-vidéo nécessitent ratio: "adaptive" ; la vidéo-à-vidéo nécessite également duration: -1. output_format accepte uniquement mp4 ou mov pour Seedance 2.5.

  • ratio accepte 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 ou adaptive (par défaut : adaptive).
  • watermark et return_last_frame sont des booléens (par défaut : false). safety_identifier est une chaîne de jusqu'à 64 caractères.
  • service_tier accepte uniquement default ; flex renvoie 400 UnsupportedParameter.
  • tools accepte au plus un élément, {"type": "web_search"}.
  • draft: true, frames et camera_fixed ne sont pas pris en charge. camera_fixed: false est accepté uniquement pour Seedance 2.0.
  • callback_url peut pointer vers un point de terminaison HTTP(S) public allant jusqu'à 2 048 caractères.

Livraison des rappels (Callback)

Lorsque callback_url est présent, TokenLab envoie un POST HTTP lorsque le statut de la tâche change. Les statuts de rappel sont queued, running, succeeded, failed et expired. Le corps JSON correspond à la réponse get-task.

Une réponse 2xx confirme la livraison. Pour succeeded et failed, une livraison qui n'aboutit pas dans les cinq secondes est réessayée jusqu'à trois fois. Le rappel ne contient que l'en-tête de contenu JSON standard et aucun en-tête de livraison spécifique à TokenLab. Les redirections ne sont pas suivies et les cibles réseau privées ou réservées sont rejetées.

Enregistrez l'ID de la tâche. Si un rappel n'est pas livré, vous pouvez toujours récupérer le résultat avec le point de terminaison get-task.

Préparation des images

Les URL d'image HTTP(S) publiques et les URL de données prises en charge sont utilisées telles quelles ; elles ne sont pas automatiquement enregistrées en tant que matériel réutilisable. Les références explicites asset://asset-... utilisent des matériels TokenLab existants. TokenLab vérifie la propriété et la disponibilité avant la génération. Si un matériel référencé est toujours en cours de préparation, attendez qu'il soit prêt et réessayez ; inspectez error.code et error.message lorsque la création échoue.

Pour les matériels existants, utilisez l'ID public asset-YYYYMMDDHHMMSS-xxxxx plutôt qu'un ID d'actif original renvoyé par un autre système. TokenLab vérifie la propriété du matériel avant la génération.

Réponse de création

{
  "id": "cgt-20260102030405-a1b2c"
}

La réponse de création ne contient que l'ID de la tâche. Enregistrez-le afin de pouvoir récupérer le statut et les résultats à tout moment.

Prévenir les tâches en double

Envoyez un Idempotency-Key unique (1–255 caractères, sans saut de ligne) avec les requêtes de création. Si la connexion se ferme avant l'arrivée de la réponse, réessayez avec la même clé API, la même clé d'idempotence et le même corps de requête :

  • Si la tâche originale a été créée, TokenLab renvoie le même ID cgt-... et ajoute Idempotency-Replayed: true.
  • La réutilisation de la clé avec un corps différent renvoie 409 avec le code idempotency_conflict et ne crée jamais de seconde tâche.
  • Une clé de plus de 255 caractères ou contenant des sauts de ligne renvoie 400 InvalidParameter.

La clé ne modifie pas la forme de la réponse JSON. TokenLab ne déduit pas les doublons à partir de X-Request-ID ou de corps de requête identiques sans clé.

Exemple

Création REST

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.0",
    "content": [
      {"type": "text", "text": "A cinematic forest at sunset"},
      {"type": "image_url", "role": "reference_image", "image_url": {"url": "https://example.com/ref.png"}}
    ],
    "ratio": "16:9",
    "duration": 5,
    "resolution": "720p",
    "generate_audio": false,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

Pour les matériels existants, placez chaque URI dans l'élément content[] officiel et déclarez son rôle :

[
  {
    "type": "image_url",
    "role": "first_frame",
    "image_url": {"url": "asset://asset-20260720123458-start"}
  },
  {
    "type": "image_url",
    "role": "last_frame",
    "image_url": {"url": "asset://asset-20260720123459-end01"}
  }
]

Erreurs

Les erreurs REST utilisent {"error": {"code", "message", "param", "type"}}. Les problèmes de requête renvoient 400 avec InvalidParameter ou UnsupportedParameter, et une clé Bearer manquante renvoie 401 AuthenticationError. Les erreurs provenant de la génération vidéo, telles qu'un solde insuffisant (402) ou une limite de débit (429), conservent leur statut HTTP.

Les mêmes opérations sont également disponibles en tant qu'Actions CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks et DeleteContentsGenerationsTasks sur POST /api/v3?Version=2024-01-01. Les nouvelles intégrations doivent utiliser les chemins REST ci-dessus.

Étape suivante

Utilisez l'ID cgt-... renvoyé avec Obtenir une tâche (Compatible Volc) jusqu'à ce que la tâche atteigne un statut terminal.

curl -X POST "https://example.com/api/v3/contents/generations/tasks" \  -H "Content-Type: application/json" \  -d '{    "model": "seedance-2.0",    "content": [      {        "type": "text",        "text": "A cinematic forest at sunset"      },      {        "type": "image_url",        "role": "reference_image",        "image_url": {          "url": "https://example.com/ref.png"        }      }    ],    "ratio": "16:9",    "duration": 5,    "resolution": "720p",    "generate_audio": false  }'
{  "id": "string"}

Autorisation

BearerAuth
AuthorizationBearer <token>

Authentification par clé API. Créez ou gérez vos clés API dans Dashboard > API > API Keys.

Emplacement: header

En-têtes

X-TokenLab-Delivery-Policy?string

Politique de livraison par requête. Remplace les valeurs par défaut de la clé API et de l'espace de travail. Tente automatiquement TokenLab Verified en premier et peut basculer une fois vers Official uniquement avant la sortie, l'acceptation de la requête ou la création de ressource persistante.

Valeurs possibles

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Clé générée par le client pour la création de tâche REST idempotente, de 1 à 255 caractères sans saut de ligne. Sous la même accréditation API TokenLab, la réutilisation de la même clé avec le même corps JSON renvoie l'ID de tâche cgt original ; la réutilisation avec un corps différent renvoie 409 avec le code idempotency_conflict. Une clé trop longue ou contenant des sauts de ligne renvoie 400. Conservez l'accréditation, la clé et le corps de la requête inchangés lors d'une nouvelle tentative après un délai d'attente ou une déconnexion.

Longueur1 <= length <= 255

Corps de la requête

application/json

Réponse

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json