Créer une tâche (Compatible Volc)

AperçuCopy Anchor Link

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

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

Authentification et points de terminaisonCopy Anchor Link

• Utilisez Authorization: Bearer <TOKENLAB_API_KEY>.
• La signature AK/SK Volc 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 contenuCopy Anchor Link

• 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.
• role: "reference_image", reference_video et reference_audio sont utilisés comme références.
• 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.
• Les champs racine material_asset_id et material_asset_ids sont rejetés. Placez l’URI du matériau TokenLab dans image_url.url. priority est pris en charge uniquement pour Seedance 2.5.

Notes sur les paramètresCopy Anchor Link

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

Pour Seedance 2.5, les requêtes avec première image, première/dernière image, extension vidéo et vidéo vers vidéo exigent ratio: "adaptive". La conversion vidéo vers vidéo exige aussi duration: -1. output_format accepte mp4 ou mov uniquement pour Seedance 2.5.

• ratio accepte 16:9, 4:3, 1:1, 3:4, 9:16, 21:9 ou adaptive.
• watermark, return_last_frame, seed, execution_expires_after et safety_identifier sont acceptés lorsqu'ils sont valides pour le modèle sélectionné.
• callback_url peut pointer vers un point de terminaison HTTP(S) public.

Livraison des rappels (Callback)Copy Anchor Link

Lorsque callback_url est présent, TokenLab envoie une requête HTTP POST 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 de 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 imagesCopy Anchor Link

Les URL d’images HTTP(S) publiques et les URL data prises en charge sont utilisées telles quelles, sans enregistrement automatique comme matériaux réutilisables. Les références explicites asset://asset-... utilisent des matériaux TokenLab existants. La propriété et la disponibilité sont vérifiées avant la génération. Si un matériau est encore en préparation, attendez qu’il soit prêt puis réessayez. En cas d’échec, consultez error.code et error.message.

Pour les matériaux 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éationCopy Anchor Link

{
  "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 doubleCopy Anchor Link

Envoyez une Idempotency-Key unique avec les requêtes de création. Si la connexion se ferme avant que la réponse n'arrive, 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.
• Si la requête originale est encore en cours d’enregistrement, TokenLab renvoie 409 IdempotencyRequestInProgress. Réessayez plus tard avec la même clé et le même corps.
• La réutilisation de la clé avec un corps différent renvoie 409 IdempotencyConflict et ne crée jamais de seconde tâche.

L'idempotence s'applique au chemin de création REST v3 officiel. Elle ne modifie pas la forme de la réponse JSON et n'est pas déduite de X-Request-ID ou de corps de requête identiques sans clé.

ExempleCopy Anchor Link

Création RESTCopy Anchor Link

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": "doubao-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ériaux 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"}
  }
]

Étape suivanteCopy Anchor Link

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": "doubao-seedance-2-0-260128",    "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"}