TokenLab

Vidéo & ressources

Créer une vidéo

Démarrer une tâche de génération vidéo

POST
/v1/videos/generations

Aperçu

La génération vidéo est asynchrone. Une requête de création réussie renvoie un id de tâche (la même valeur que task_id) et une poll_url. Appelez GET /v1/tasks/{id} avec cet identifiant jusqu'à ce que le status soit completed ou failed, puis lisez video_url. Voir Obtenir le statut de la vidéo.

  • Le fichier résultat est conservé pendant 30 jours. Téléchargez-le si vous en avez besoin plus longtemps ; voir Rétention des données.
  • Une tâche Seedance en file d'attente peut être annulée avec Annuler une tâche.
  • Le coût peut être réservé lorsque la tâche est acceptée et est réglé lorsque la tâche se termine ou échoue. Voir Facturation et tarification.
  • Envoyez un en-tête Idempotency-Key pour réessayer une requête de création en toute sécurité après un délai d'attente.

Chaque modèle accepte ses propres opérations et champs. GET /v1/models/{model} (Obtenir un modèle) liste, pour chaque opération, les champs acceptés, les résolutions, les durées et les formats d'image. Un champ ou une valeur en dehors de cette liste renvoie 400 avec les valeurs acceptées. Définissez vous-même duration, resolution, aspect_ratio et output_audio : si vous en omettez un, TokenLab utilise la valeur par défaut du modèle pour l'opération, et si aucune valeur par défaut ne correspond, la requête renvoie 400 et nomme le champ à définir.

Entrée audio et média

Le comportement audio dépend du modèle sélectionné et de l'opération. Une vidéo peut contenir du son même lorsqu'aucun sélecteur audio n'est exposé. Omettre un sélecteur est différent de l'envoi de false.

  • veo3.1, veo3.1-fast et veo3.1-lite génèrent toujours de l'audio. Omettez output_audio ou envoyez true ; false est rejeté.
  • wan-2.6 et wan-2.7 incluent toujours de l'audio. Omettez output_audio ou envoyez true. wan-3.0 et wan-3.0-prime incluent également toujours de l'audio et ne prennent aucun sélecteur audio.
  • hailuo-h3 génère de l'audio natif et ne possède pas d'interrupteur de sourdine. N'envoyez pas de sélecteur audio qui ne figure pas dans les détails du modèle.
  • viduq3-pro et viduq3-turbo génèrent de l'audio par défaut ; envoyez output_audio: false (ou audio: false) pour une sortie silencieuse. Les modèles Seedance et PixVerse prennent output_audio ; envoyez-le explicitement au lieu de vous fier à la valeur par défaut. Utilisez-le uniquement pour les opérations qui le listent.
  • audio_url / audio_urls fournissent une entrée ou une référence audio. Ce ne sont pas des commutateurs de sortie audio. Le montage vidéo, le transfert de mouvement et le transfert de style peuvent conserver la bande sonore d'entrée ; préserver l'audio source ne signifie pas le mettre en sourdine.

Consultez les détails du modèle pour connaître les valeurs autorisées et les tarifs dépendants de l'audio. Lorsque les détails d'un modèle les listent, les alias outputAudio, generate_audio et le booléen audio doivent être cohérents avec output_audio lorsqu'ils sont combinés. Ne supposez pas que chaque version ou opération d'une famille de modèles partage les mêmes contrôles audio.

Utilisez des URLs https accessibles publiquement pour les images, les vidéos et l'audio, et maintenez-les valides jusqu'au démarrage de la tâche. Une URL de média peut contenir jusqu'à 8 192 caractères. Certains modèles acceptent également des URLs d'image data: en ligne (jusqu'à 2 000 000 de caractères par champ) ; les URLs sont plus fiables pour les fichiers volumineux. Ne mélangez pas le base64 en ligne et les URLs distantes dans la même requête.

Corps de la requête

modelstringpar défaut: veo3.1

ID du modèle vidéo. Listez les modèles vidéo actuels avec Lister les modèles (recommended_for=video), puis envoyez le modèle explicitement.

PixVerse

  • Modèle: pixverse-c1, pixverse-v6, pixverse-v5.6
  • Opérations: text-to-video, image-to-video, start-end-to-video, reference-to-video
  • Sélecteur audio: output_audio, false par défaut

Sur TokenLab, les modèles PixVerse ci-dessus n'acceptent pas operation=video-extension.

HappyHorse

  • Modèle: happyhorse-1.0
  • Opérations: text-to-video, image-to-video, reference-to-video, video-to-video
  • Sélecteur audio: Ne pas envoyer output_audio
promptstring

Description textuelle de la vidéo, jusqu'à 10 000 caractères. La plupart des opérations en nécessitent une ; les détails du modèle indiquent celles qui n'en ont pas besoin.

operationstring

Mode de génération : text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension ou motion-control. Chaque modèle ne prend en charge qu'une partie d'entre eux ; les autres renvoient 400 unsupported_operation. Si vous l'omettez, TokenLab le déduit à partir des entrées : un task_id avec extend_at ou extend_times donne video-extension, des images ou matériaux de référence donnent reference-to-video, end_image donne start-end-to-video, une entrée vidéo donne video-to-video, une entrée image (image, image_url, image_urls ou start_image) donne image-to-video, et sinon text-to-video. Envoyez-le explicitement afin qu'un champ non correspondant échoue rapidement.

image_urlstring

URL accessible publiquement de l'image de la première frame. Les modèles Seedance 2.0 acceptent également asset://asset-YYYYMMDDHHMMSS-xxxxx pour utiliser un matériau TokenLab ACTIVE comme première frame. Préférez une URL https pour une prise en charge maximale par les modèles.

imagestring

Image en ligne sous forme d'URL de données (par exemple, data:image/jpeg;base64,...). Seuls certains modèles l'acceptent ; image_url fonctionne sur un plus grand nombre.

image_urlsarray

URLs d'images pour les modèles qui listent ce champ. Voir reference_images pour les limites de nombre.

reference_imagesarray

Images de référence pour reference-to-video, sous forme d'URLs https ou d'URLs de données. La limite de nombre dépend du modèle :

  • seedance-2.0, seedance-2.0-fast et seedance-2.0-mini : jusqu'à 9 références d'image au total, incluant les matériaux. Plus renvoie 400 too_many_seedance_reference_images.
  • seedance-2.5 : jusqu'à 30 entrées d'image au total via image_urls et reference_images.
  • grok-imagine-video : jusqu'à 7, et la duration est plafonnée à 10 secondes. grok-imagine-video-1.5 et grok-imagine-video-1.5-preview ne prennent aucune image de référence.
  • Autres modèles : voir les détails du modèle. Une requête dépassant la limite renvoie 400 too_many_items.

Les modèles Seedance 2.0 acceptent également asset://asset-YYYYMMDDHHMMSS-xxxxx pour un matériau TokenLab ACTIVE. Pour la sélection de modèle, les limites 4K et les notes Mini, voir le guide des modèles vidéo Seedance 2.0. Pour grok-imagine-video, ne combinez pas d'images de référence avec image_url ou image.

start_imagestring

Image de la première trame. Avec end_image, la requête est start-end-to-video. Sans end_image, il s'agit de image-to-video, et start_image fonctionne comme image sur les modèles dont le contrat le mentionne. Accepte une URL publique ou une URL de données ; les modèles Seedance 2.0 acceptent également asset://asset-YYYYMMDDHHMMSS-xxxxx.

end_imagestring

Image de la dernière frame pour start-end-to-video. Accepte les mêmes entrées que start_image.

material_asset_idstring

ID de matériau TokenLab Seedance renvoyé par Créer un matériau. Accepté uniquement par les modèles Seedance 2.0 ; les autres modèles renvoient 400 unsupported_seedance_material_asset_model. Le matériau doit être ACTIVE et appartenir à votre compte. Ce champ est une entrée de référence générique ; pour assigner explicitement une signification de première frame, dernière frame ou image de référence, mettez asset://<material_asset_id> dans start_image, end_image ou reference_images à la place.

material_asset_idsarray

Jusqu'à 9 IDs de matériaux TokenLab Seedance. Ils comptent dans les 9 références d'image des modèles Seedance 2.0.

Les URLs d'image ordinaires sont transmises comme entrées d'image ; elles ne créent pas de matériaux réutilisables. Créez des matériaux réutilisables via l'API de matériaux, puis utilisez leurs IDs TokenLab ou leurs URIs asset://asset-YYYYMMDDHHMMSS-xxxxx. Si un matériau explicite renvoie 409 seedance_material_preparing, vérifiez les inactive_asset_ids renvoyés et réessayez une fois que ces matériaux sont devenus ACTIVE.

video_urlstring

URL accessible publiquement de la vidéo source, pour les opérations qui en acceptent une : video-to-video, video-extension et motion-control, sur les modèles qui listent ce champ.

video_urlsarray

Vidéos source ou de référence pour les modèles qui listent ce champ. seedance-2.5 accepte jusqu'à 10 entrées vidéo au total via video_url et video_urls. Voir les détails du modèle pour les autres modèles.

audio_urlstring

URL audio publique pour une référence audio ou une opération pilotée par l'audio, sur les modèles qui listent ce champ. Il s'agit d'une entrée, pas d'un commutateur de sortie audio.

audio_urlsarray

Audio de référence pour les modèles qui listent ce champ. seedance-2.5 accepte jusqu'à 10 entrées audio au total via audio_url et audio_urls et autorise une requête avec des références audio sans prompt. Pour seedance-2.5, l'audio de référence plus la vidéo de référence dure au maximum 30 secondes combinées.

task_idstring

ID d'une tâche précédente dans votre espace de travail, pour video-extension sur les modèles qui listent ce champ. Une tâche qui n'appartient pas à votre espace de travail renvoie 403 task_not_owned.

extend_atinteger

Seconde de la vidéo source où commence une video-extension. Requis par grok-imagine-video.

extend_timesstring

Secondes à ajouter dans une video-extension, sur les modèles qui listent ce champ. grok-imagine-video accepte 6 ou 10.

durationinteger

Durée de sortie en secondes. Les valeurs autorisées dépendent du modèle et de l'opération ; les autres valeurs renvoient 400 invalid_duration. Les modèles Seedance acceptent également -1 pour laisser le modèle choisir dans sa plage ; la facturation est alors estimée de manière conservatrice jusqu'à ce que la tâche se termine. Certaines opérations ne prennent pas de durée, comme motion-control et grok-imagine-video en mode video-to-video.

secondsinteger

Alias de compatibilité pour duration. Si les deux sont envoyés, ils doivent être identiques.

aspect_ratiostring

Format d'image, par exemple 16:9, 9:16, 1:1, 4:3, 3:4, 21:9 ou adaptive (Seedance). Les valeurs autorisées dépendent du modèle et de l'opération ; les autres valeurs renvoient 400 invalid_aspect_ratio.

resolutionstring

Résolution de sortie, par exemple 480p, 720p, 1080p ou 4k. Les valeurs autorisées dépendent du modèle et de l'opération, et certains modèles utilisent également 360p, 540p ou 768p. Les autres valeurs renvoient 400 invalid_resolution.

output_audioboolean

Sélecteur de sortie audio pour les opérations qui le listent. L'omission suit la valeur par défaut du modèle ; false demande une sortie silencieuse uniquement là où le modèle l'autorise. Voir les notes audio ci-dessus et les détails du modèle sélectionné.

output_formatstring

Format de conteneur, mp4 ou mov, pour les modèles qui listent ce champ, comme seedance-2.5. Omettez-le pour les modèles qui ne le listent pas.

return_last_frameboolean

Renvoie également la dernière frame générée sous forme de last_frame_url. Modèles Seedance uniquement.

watermarkboolean

Basculement du filigrane pour les modèles qui listent ce champ (modèles Seedance).

negative_promptstring

Ce qu'il faut éviter dans la vidéo générée, jusqu'à 5 000 caractères, pour les modèles qui listent ce champ.

seedinteger

Graine pour une génération reproductible, pour les modèles qui listent ce champ. Les modèles Seedance 2.0 acceptent -1 pour une graine aléatoire ; seedance-2.5 n'accepte pas ce champ.

fpsinteger

Frames par seconde (1-120), pour les modèles qui listent ce champ.

framesinteger

Nombre de frames, pour les modèles qui listent ce champ. Les modèles Seedance ne l'acceptent pas.

execution_expires_afterinteger

Secondes pendant lesquelles la tâche peut attendre dans la file d'attente avant d'expirer (3600 à 259200), pour les modèles Seedance.

priorityinteger

Priorité de la tâche de 0 à 9, pour les modèles Seedance. Ne le combinez pas avec service_tier=flex.

service_tierstring

default est accepté comme une opération sans effet de compatibilité sur les modèles Seedance 2.0 et 2.5. flex est rejeté sur ces modèles.

safety_identifierstring

Identifiant de sécurité de l'utilisateur final (jusqu'à 128 caractères), pour les modèles Seedance. S'il est omis, TokenLab utilise user lorsqu'il est fourni.

toolsarray

Outils que le modèle peut utiliser pendant la génération, pour les modèles Seedance 2.0 et 2.5. L'outil pris en charge est {"type": "web_search"}.

userstring

Un identifiant unique pour l'utilisateur final. Pour les modèles Seedance, TokenLab l'utilise également comme safety_identifier lorsque ce champ est omis.

Noms de champs compatibles

  • Les champs principaux utilisent le snake_case : aspect_ratio, output_audio et reference_images.
  • Pour la compatibilité, TokenLab accepte également ratio, generate_audio, outputAudio, seconds et referenceImages.
  • Si un champ principal et son alias sont tous deux envoyés, leurs valeurs doivent correspondre. Une discordance renvoie 400 avec conflicting_audio_selector, conflicting_duration ou conflicting_aspect_ratio.

Paramètres Seedance

Les modèles Seedance (seedance-2.0, seedance-2.0-fast, seedance-2.0-mini et seedance-2.5) prennent les noms de champs TokenLab ci-dessus et les alias seconds, ratio et generate_audio. Les versions diffèrent :

Modèles Seedance 2.0seedance-2.5
Résolutionseedance-2.0 : 480p, 720p, 1080p, 4k. seedance-2.0-fast et seedance-2.0-mini : 480p, 720p480p, 720p
Durée-1, 4 à 15 secondes-1, 4 à 30 secondes
Format d'image1:1, 3:4, 4:3, 9:16, 16:9, 21:9, adaptiveIdentique pour text-to-video et reference-to-video. Image-to-video, start-end, édition vidéo et extension nécessitent adaptive ; l'édition vidéo nécessite également duration=-1
Format de sortiemp4mp4 ou mov
seedAcceptéNon accepté
Entrées de référence9 références d'image incluant les matériaux (les matériaux ne sont acceptés que sur ces modèles)30 images, 10 vidéos et 10 fichiers audio au total

Les détails du modèle sont la source actuelle pour ces valeurs. Envoyez duration, resolution, aspect_ratio et output_audio explicitement au lieu de vous fier à une valeur par défaut ; le recommended_request du modèle montre une requête typique.

duration=-1 ou seconds=-1 permet à Seedance de choisir la durée de sortie dans la plage du modèle. TokenLab estime le coût de manière conservatrice avant que la tâche ne se termine, puis règle à partir de l'utilisation de la tâche terminée lorsqu'elle est disponible. service_tier=flex et frames sont rejetés sur ces modèles.

Exemple Seedance

cURL
curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A sleek product reveal with cinematic camera movement",
    "operation": "text-to-video",
    "duration": -1,
    "aspect_ratio": "adaptive",
    "resolution": "720p",
    "output_audio": true
  }'

Réponse

Les champs décrivant les résultats, les erreurs, les horodatages et le modèle sont renvoyés lorsqu'ils sont disponibles pour la tâche.

idstring

ID de la tâche. Identique à task_id.

task_idstring

ID de la tâche à interroger avec GET /v1/tasks/{id}.

poll_urlstring

URL de statut pour cette tâche, /v1/tasks/{id}. Appelez-la avec votre clé API.

statusstring

Statut de la tâche : pending, processing, completed, failed. Une nouvelle tâche est normalement pending.

createdinteger

Horodatage Unix de création de la tâche.

modelstring

Modèle utilisé.

billing_transaction_idstring

ID de transaction de facturation lorsque le règlement est déjà terminé. Il est distinct de l'ID de la tâche.

video_urlstring

URL de la vidéo, présente uniquement lorsque la réponse de création contient déjà le résultat. Normalement, vous la lisez à partir de la réponse de statut.

errorstring | object

Message d'erreur ou objet d'erreur structuré lorsque la tâche échoue.

Erreurs

Statut et codeSignification
400 invalid_requestUn champ est mal formé, hors plage ou manquant. error.param le nomme. Un message tel que "Set aspect_ratio explicitly" signifie que le champ omis n'a pas de valeur par défaut pour cette requête.
400 unsupported_operation, unsupported_parameter, invalid_resolution, invalid_duration, invalid_aspect_ratio, invalid_parameter_value, too_many_items, prompt_too_longLa requête ne correspond pas à ce que le modèle accepte pour l'opération. L'erreur liste généralement les valeurs acceptées.
400 invalid_parameterUne entrée ne correspond pas à l'opération, par exemple une image envoyée avec text-to-video.
400 conflicting_audio_selector, conflicting_duration, conflicting_aspect_ratioUn alias et son champ principal sont en désaccord.
400 unpriceable_selectionLa combinaison sélectionnée n'a pas de prix. Modifiez resolution, duration, aspect_ratio ou le réglage audio.
400 too_many_seedance_reference_images, unsupported_seedance_material_asset_modelTrop de références d'image pour un modèle Seedance 2.0, ou un matériau envoyé à un autre modèle.
402Solde insuffisant.
403 task_not_ownedLe task_id appartient à un autre espace de travail.
409 seedance_material_preparing, seedance_material_route_unavailableUn matériau n'est pas encore ACTIVE, ou le modèle sélectionné ne peut pas utiliser les matériaux fournis.
429Limite de débit dépassée. Voir Limites de débit.

Requête

curl -X POST "https://api.tokenlab.sh/v1/videos/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo3.1",
    "prompt": "A cat walking through a garden, cinematic lighting",
    "operation": "text-to-video",
    "duration": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

Réponse

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "veo3.1",
  "created": 1706000000
}

Image vers vidéo

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3",
        "prompt": "The scene begins from the provided image and adds gentle natural motion.",
        "operation": "image-to-video",
        "image_url": "https://example.com/image.jpg",
        "duration": 6,
        "resolution": "768p"
    }
)

Référence vers vidéo

Utilisez operation=reference-to-video lorsque le modèle prend en charge un conditionnement de référence dédié. Les références d'image vont dans reference_images ; les modèles qui prennent des vidéos et de l'audio de référence utilisent video_urls et audio_urls. duration définit uniquement la longueur de la sortie générée. Elle ne limite pas la longueur de l'entrée vidéo de référence. Voir reference_images ci-dessus pour les limites de nombre par modèle.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "veo3.1",
        "prompt": "Keep the same subject identity, palette, and framing while adding subtle natural motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Contrôle des images clés

Utilisez start_image et end_image pour contrôler les première et dernière frames :

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "viduq2-pro",
        "operation": "start-end-to-video",
        "start_image": "https://example.com/day.jpg",
        "end_image": "https://example.com/night.jpg",
        "duration": 5,
        "resolution": "720p"
    }
)

Vidéo vers vidéo

Utilisez operation=video-to-video lorsque le modèle accepte une vidéo existante comme entrée principale. Pour grok-imagine-video, envoyez une URL .mp4 HTTPS publique dans video_url et le prompt d'édition, et omettez resolution, duration et aspect_ratio.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "grok-imagine-video",
        "operation": "video-to-video",
        "video_url": "https://example.com/source.mp4",
        "prompt": "Enhance the clip while preserving the original motion."
    }
)

Extension vidéo

Utilisez operation=video-extension pour continuer un résultat précédent. Envoyez le task_id d'une tâche de votre espace de travail et un prompt ; les autres champs dépendent du modèle. grok-imagine-video nécessite également extend_at et accepte extend_times de 6 ou 10. veo3.1 et veo3.1-fast prennent task_id et prompt. Les modèles Seedance listent video_url, video_urls et task_id pour cette opération.

Contrôle de mouvement

Utilisez operation=motion-control lorsque le modèle attend à la fois une image de sujet et une vidéo de référence de mouvement. Envoyez image_url et video_url ; resolution est requise.

import requests

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "kling-3.0-motion-control",
        "operation": "motion-control",
        "prompt": "Keep the subject identity stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

Découverte de modèles

L'inventaire vidéo public et les opérations prises en charge changent avec le temps. Utilisez l'API des modèles pour vérifier la prise en charge actuelle avant de configurer un flux spécifique au modèle :

curl "https://api.tokenlab.sh/v1/models?recommended_for=video"

curl "https://api.tokenlab.sh/v1/models/veo3.1"

Lisez la réponse détaillée du modèle avant de vous fier à des opérations ou des champs spécifiques au modèle. Les opérations telles que video-extension et motion-control sont spécifiques au modèle ; confirmez la disponibilité actuelle à cet endroit au lieu de vous fier aux exemples statiques de cette page.

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é optionnelle qui permet de réessayer une requête de création en toute sécurité. Envoyez une nouvelle valeur unique, telle qu'un UUID, pour chaque tâche. Une tentative avec la même clé et le même corps renvoie le résultat de la requête de création initiale, généralement la tâche d'origine, et ne crée, ne distribue ni ne facture une seconde tâche. Un corps différent avec une clé déjà acceptée est rejeté avec 409. Une clé de plus de 255 caractères est ignorée, et la requête ne bénéficie alors d'aucune protection d'idempotence. Voir Réessayer en toute sécurité avec une clé d'idempotence.

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

application/json