Créer une vidéo

Vue d’ensemble

La génération vidéo est asynchrone. Une fois la requête envoyée, vous recevez un task_id et un poll_url, puis vous interrogez ce task jusqu’au résultat final.

Comportement de polling

Pour un polling fiable, utilisez exactement le poll_url renvoyé par la requête de création. Si une réponse de création renvoie poll_url, appelez exactement cette URL. Lorsqu’elle pointe vers /v1/tasks/{id}, traitez-la comme l’endpoint fixe canonique de statut.

Comportement des modèles et des médias

La sortie audio dépend du modèle. Dans TokenLab, les requêtes Veo 3 et Seedance activent l’audio par défaut lorsque output_audio est omis. Lorsqu’un modèle prend en charge le contrôle audio, utilisez output_audio pour l’activer ou le désactiver explicitement. Les alias outputAudio et generate_audio sont acceptés pour compatibilité et doivent correspondre à output_audio si plusieurs champs sont fournis. En production, privilégiez des URLs https publiques pour les images, vidéos et fichiers audio. Les modèles compatibles acceptent toujours les data: URLs, mais les gros payloads base64 compliquent les retries, l’observabilité et le débogage.

Corps de la requête

model

string

défaut:"veo3.1"

ID du modele video. Utilisez les IDs de modèle affichés par TokenLab comme veo3.1, wan-2.7, happyhorse-1.0, viduq3, pixverse-v6 ou kling-3.0-video; choisissez text-to-video, image-to-video, reference-to-video ou d autres variantes avec operation. Voir le guide video et Models API.

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

prompt

string

requis

Description textuelle de la vidéo à générer. Ce champ est requis pour la plupart des modèles publics.

operation

string

Opération vidéo à exécuter. Les valeurs acceptées sont text-to-video, image-to-video, reference-to-video, start-end-to-video, video-to-video, video-extension, audio-to-video et motion-control. TokenLab peut déduire l’opération à partir des entrées, mais une valeur explicite est recommandée en production.

image_url

string

URL de l’image de départ pour les flux image-vers-vidéo. Pour la compatibilité la plus large, privilégiez image_url.

image

string

Image inline au format data: (par exemple data:image/jpeg;base64,...). Les modèles compatibles la prennent en charge, mais image_url reste l’option la plus robuste.

reference_images

array

Images de référence pour les flux avec conditionnement dédié. Le nombre autorisé dépend du modèle. Pour seedance-2.0 et seedance-2.0-fast, TokenLab prend actuellement en charge jusqu’à 9 images de référence, ainsi que jusqu’à 3 vidéos de référence et 3 audios de référence. Pour le choix du modèle, les limites 4K et les notes Mini, consultez le guide des modèles vidéo Seedance 2.0. Les URL publiques https sont recommandées ; les modèles compatibles acceptent aussi les URL data:. Pour grok-imagine-video, reference-to-video accepte jusqu’à 7 références image et duration est limitée à 10 secondes. grok-imagine-video-1.5-preview est limité à image-to-video et n’accepte pas les références image.

material_asset_id

string

ID de matériau Seedance TokenLab renvoyé par Créer un matériau ou par la préparation automatique d’image. Utilisez-le après le statut ACTIVE avec les modèles Seedance qui peuvent utiliser la bibliothèque de matériaux TokenLab.

material_asset_ids

array

Plusieurs ID de matériaux Seedance TokenLab. Ils partagent la limite de références image Seedance avec reference_images; le modèle sélectionné doit pouvoir utiliser la bibliothèque de matériaux TokenLab.

Lorsque le modèle Seedance sélectionné peut utiliser la bibliothèque de matériaux TokenLab, TokenLab prépare les champs image (image, image_url, image_urls, reference_images, start_image, end_image) comme matériaux réutilisables avant la génération. Si la préparation n’est pas terminée en 60 secondes, l’API renvoie 409 seedance_material_preparing avec auto_material_asset_ids; réessayez lorsque ces matériaux sont ACTIVE. Si le modèle sélectionné ne peut pas utiliser la bibliothèque, les images ordinaires continuent sur le chemin image habituel et les ID de matériaux explicites échouent de façon sûre avec une erreur de disponibilité des matériaux.

reference_image_type

string

Champ facultatif pour les modèles qui distinguent les références asset et style.

kling_elements

array

Définitions de références d’éléments Kling 3.0. Pris en charge uniquement avec kling-3.0-video pour les requêtes conditionnées par image. Définissez 1 à 3 éléments ; chaque élément contient name, un description optionnel et element_input_urls avec 2 à 4 URL d’images. Référencez un élément dans prompt avec @name. Ne combinez pas kling_elements avec output_audio=true ; omettez output_audio ou définissez-le sur false pour les requêtes avec références d’éléments.

video_url

string

URL publique de la vidéo source. Requise pour les flux video-to-video basés sur une URL vidéo et pour motion-control ; certains flux dérivés utilisent plutôt task_id.

video_urls

array

Entrées vidéo de référence supplémentaires pour les modèles qui prennent en charge un conditionnement multimodal. Le nombre autorisé dépend du modèle. Pour seedance-2.0 et seedance-2.0-fast, TokenLab prend actuellement en charge jusqu’à 3 vidéos de référence.

audio_url

string

URL publique du fichier audio pour les modèles audio-to-video.

audio_urls

array

Entrées audio de référence supplémentaires pour les modèles qui prennent en charge un conditionnement multimodal. Le nombre autorisé dépend du modèle. Pour seedance-2.0 et seedance-2.0-fast, TokenLab prend actuellement en charge jusqu’à 3 audios de référence.

task_id

string

Identifiant de tâche utilisé par certains flux de continuation, d’extension ou dérivés.

extend_at

integer

Offset de départ spécifique au modèle pour certains flux video-extension.

extend_times

string

Multiplicateur ou nombre de répétitions spécifique au modèle pour certains flux video-extension.

duration

integer

Durée de la vidéo générée en secondes. Pour les modèles Seedance 1.5/2.0, l’omission de ce champ utilise 5; envoyer -1 laisse le modèle choisir dans sa plage prise en charge, et la facturation est estimée de façon conservatrice jusqu’à la fin de la tâche.

seconds

integer

Alias compatible de duration. Si seconds et duration sont envoyés ensemble, ils doivent être identiques. Pour Seedance, seconds=-1 a le même sens de durée automatique que duration=-1.

aspect_ratio

string

Format d’image canonique, par exemple adaptive, 16:9, 9:16, 1:1, 4:3, 3:4 ou 21:9. Seedance utilise adaptive par défaut lorsque ce champ est omis.

resolution

string

Résolution de sortie dépendante du modèle. Seedance utilise 720p par défaut ; seedance-2.0 prend en charge 480p, 720p, 1080p et 4k, tandis que seedance-2.0-fast et seedance-2.0-mini sont limités à 480p et 720p.

output_audio

boolean

Sélecteur canonique de sortie audio dépendant du modèle. Veo 3 et Seedance utilisent true par défaut lorsque le champ est omis. kling-3.0-video accepte ce sélecteur pour les requêtes sans référence d’élément et produit une sortie silencieuse par défaut lorsqu’il est omis. Ne combinez pas output_audio=true avec kling_elements.

draft

boolean

Sélecteur du workflow Draft de Seedance 1.5 Pro. Utilisez draft=true avec les modèles Seedance compatibles avec les tâches draft. Ne l’envoyez pas avec draft_task_id.

draft_task_id

string

ID de tâche draft Seedance 1.5 Pro à promouvoir. Envoyez l’ID d’une tâche draft précédente pour créer la vidéo finale ; ce n’est pas un champ vidéo générique.

ratio

string

Alias compatible de aspect_ratio. Si ratio et aspect_ratio sont envoyés ensemble, ils doivent être identiques.

generate_audio

boolean

Alias compatible de output_audio. Si generate_audio, output_audio et outputAudio apparaissent ensemble, toutes les valeurs doivent correspondre.

execution_expires_after

integer

Fenêtre optionnelle d’expiration d’exécution en secondes pour les modèles vidéo compatibles. Seedance utilise 172800 secondes par défaut lorsque le champ est omis.

priority

integer

Priorité optionnelle de tâche de 0 à 9 pour les modèles vidéo compatibles. Ne combinez pas priority avec service_tier=flex.

safety_identifier

string

Identifiant optionnel de sécurité de l’utilisateur final pour les modèles vidéo compatibles. S’il est omis pour Seedance, TokenLab utilise user lorsqu’il est fourni.

service_tier

string

default est accepté comme no-op compatible pour les modèles Seedance 2.0. flex n’est autorisé que lorsque le modèle sélectionné le prend en charge.

frames

integer

Nombre optionnel d’images pour les modèles vidéo compatibles. Les modèles Seedance 2.0 et Seedance 1.5 Pro ne prennent pas ce champ en charge.

camera_fixed

boolean

Sélecteur optionnel de caméra fixe pour les modèles vidéo compatibles. Les modèles Seedance 2.0 ne prennent pas ce champ en charge.

fps

integer

Fréquence d’images (1–120). N’a d’effet que sur les modèles qui l’exposent publiquement.

negative_prompt

string

Éléments à éviter dans la génération.

seed

integer

Graine aléatoire pour une génération reproductible. Seedance utilise -1 comme graine aléatoire lorsque le champ est omis.

cfg_scale

number

Intensité de suivi du prompt (0–20), effective uniquement sur les modèles qui la prennent en charge.

motion_strength

number

Intensité du mouvement (0–1), effective uniquement sur les modèles compatibles.

start_image

string

URL de l’image de premier frame, ou entrée image compatible, pour start-end-to-video.

end_image

string

URL de l’image de dernier frame, ou entrée image compatible, pour start-end-to-video.

size

string

Niveau de taille propre au modèle pour les modèles vidéo compatibles.

watermark

boolean

Option de filigrane pour les modèles qui l’exposent. Seedance utilise false par défaut lorsque le champ est omis.

effect_type

string

Sélecteur d’effet spécifique au modèle pour certains flux d’édition ou d’effets.

user

string

Identifiant unique de l’utilisateur final. Pour Seedance, TokenLab utilise aussi cette valeur comme safety_identifier lorsque ce champ est omis.

Notes de compatibilité

Les champs publics canoniques utilisent le snake_case : reference_images, reference_image_type et output_audio.
Les champs publics canoniques restent en snake_case : aspect_ratio, output_audio, reference_images et reference_image_type.
Pour compatibilité, TokenLab accepte aussi ratio, generate_audio, outputAudio, seconds, referenceImages et referenceImageType.
Si des champs canoniques et des alias sont envoyés ensemble, leurs valeurs doivent correspondre ; les alias en conflit sont rejetés avant la création de la tâche.

Bonnes pratiques d’entrée

Pour image_url, reference_images, video_url et audio_url, privilégiez des URLs https publiques.
Évitez, si possible, de mélanger base64 inline et URLs distantes dans une même requête.
Assurez-vous que les URLs média distantes restent valides pendant la fenêtre de retry et la création asynchrone.

Paramètres Seedance

Pour les modèles Seedance 1.5/2.0, l’endpoint unifié suit les noms de champs TokenLab tout en acceptant les alias compatibles seconds, ratio et generate_audio. Lorsque les sélecteurs Seedance sont omis, ces valeurs par défaut sont utilisées : duration=5, resolution=720p, aspect_ratio=adaptive, output_audio=true, watermark=false, return_last_frame=false, execution_expires_after=172800, priority=0 et seed=-1. duration=-1 ou seconds=-1 laisse Seedance choisir la durée de sortie dans la plage prise en charge par le modèle. TokenLab estime le coût de façon conservatrice avant la fin de la tâche, puis règle selon l’usage de la tâche terminée lorsque disponible. service_tier=default est accepté comme no-op compatible pour Seedance 2.0 ; service_tier=flex, frames et camera_fixed sont rejetés lorsque le modèle sélectionné ne les prend pas en charge.

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.0",
    "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

string

Identifiant canonique de tâche asynchrone. Lorsque id et task_id sont tous les deux présents, considérez-les comme la même tâche.

task_id

string

Identifiant unique du task pour le polling.

poll_url

string

URL de polling recommandée pour ce task. Utilisez ce chemin tel quel lors des vérifications d’état.

billing_transaction_id

string

ID de transaction de facturation TokenLab lorsque le règlement est déjà terminé. Il s’agit de l’identifiant utilisé pour le dashboard / le rapprochement, distinct de l’id / task_id asynchrone.

status

string

Statut initial : pending.

created

integer

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

model

string

Modèle utilisé.

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,
    "aspect_ratio": "16:9"
  }'

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

Image vers vidéo

response = requests.post(
    "https://api.tokenlab.sh/v1/videos/generations",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "model": "hailuo-2.3-standard",
        "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,
        "aspect_ratio": "16:9"
    }
)

Kling 3.0 Elements

Utilisez kling_elements avec kling-3.0-video lorsque vous avez besoin de références d’éléments. Fournissez une requête conditionnée par image (image_url, image_urls, start_image ou end_image) et référencez chaque élément dans le prompt avec @name. Ne combinez pas kling_elements avec output_audio=true ; omettez output_audio ou définissez-le sur false pour les requêtes avec références d’éléments.

response = requests.post("https://api.tokenlab.sh/v1/videos/generations",
    headers=headers,
    json={
        "model": "kling-3.0-video",
        "prompt": "Place @hero_bag on a studio turntable with soft product lighting.",
        "operation": "image-to-video",
        "image_url": "https://example.com/studio-start.png",
        "duration": 5,
        "resolution": "720p",
        "kling_elements": [
            {
                "name": "hero_bag",
                "description": "black leather handbag",
                "element_input_urls": [
                    "https://example.com/bag-front.png",
                    "https://example.com/bag-side.png"
                ]
            }
        ]
    }
)

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é. Dans le détails du modèle de TokenLab, les références d’image utilisent reference_images, tandis que les vidéos et audios de référence multimodaux utilisent video_urls et audio_urls. Pour seedance-2.0 et seedance-2.0-fast, TokenLab prend actuellement en charge jusqu’à 9 images de référence, ainsi que jusqu’à 3 vidéos de référence et 3 audios de référence. Pour le choix du modèle, les limites 4K et les notes Mini, consultez le guide des modèles vidéo Seedance 2.0. duration contrôle uniquement la durée de sortie générée ; il ne fixe pas de limite distincte pour la durée de la vidéo de référence en entrée. Pour grok-imagine-video, reference-to-video accepte jusqu’à 7 références image (reference_images ou image_urls) et duration est limitée à 10 secondes. Ne combinez pas les références image avec des entrées de première frame image_url / image. grok-imagine-video-1.5-preview est limité à image-to-video.

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 and palette while adding subtle motion.",
        "operation": "reference-to-video",
        "reference_images": [
            "https://example.com/ref-a.jpg",
            "https://example.com/ref-b.jpg"
        ],
        "reference_image_type": "asset",
        "duration": 8,
        "resolution": "720p",
        "aspect_ratio": "9:16"
    }
)

Contrôle début / fin

Utilisez start_image et end_image pour contrôler la première et la dernière image.

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

Vidéo vers vidéo

Pour le video-to-video de grok-imagine-video, envoyez une URL .mp4 HTTPS publique dans video_url. TokenLab la traduit vers le corps REST xAI video.url. Vous pouvez définir resolution sur 480p ou 720p; duration et aspect_ratio ne sont pas acceptés pour ce flux d’édition. Si un modèle accepte une vidéo existante comme entrée principale, utilisez operation=video-to-video.

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.",
        "resolution": "720p"
    }
)

Contrôle de mouvement

Quand un modèle exige à la fois une image de sujet et une vidéo de mouvement de référence, utilisez operation=motion-control. TokenLab normalise la forme publique image_url + video_url vers le format motion-control de ce modèle.

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 stable while following the motion reference.",
        "image_url": "https://example.com/subject.png",
        "video_url": "https://example.com/motion.mp4",
        "resolution": "720p"
    }
)

Découverte des modèles

L’inventaire vidéo public et les opérations prises en charge évoluent dans le temps. Utilisez la Models API comme référence actuelle avant d’implémenter un flux propre à un modèle :

curl "https://api.tokenlab.sh/v1/models?recommended_for=video" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models/veo3.1" \
  -H "Authorization: Bearer sk-your-api-key"

Lisez la réponse de détail du modèle avant de dépendre d’opérations ou de champs propres au modèle. Les opérations comme audio-to-video et video-extension sont propres à certains modèles ; confirmez leur disponibilité actuelle à cet endroit plutôt que de vous appuyer sur les exemples statiques de cette page.

​Vue d’ensemble

​Comportement de polling

​Comportement des modèles et des médias

​Corps de la requête

​Notes de compatibilité

​Bonnes pratiques d’entrée

​Paramètres Seedance

​Exemple Seedance

​Réponse

​Image vers vidéo

​Kling 3.0 Elements

​Référence vers vidéo

​Contrôle début / fin

​Vidéo vers vidéo

​Contrôle de mouvement

​Découverte des modèles

Vue d’ensemble

Comportement de polling

Comportement des modèles et des médias

Corps de la requête

Notes de compatibilité

Bonnes pratiques d’entrée

Paramètres Seedance

Exemple Seedance

Réponse

Image vers vidéo

Kling 3.0 Elements

Référence vers vidéo

Contrôle début / fin

Vidéo vers vidéo

Contrôle de mouvement

Découverte des modèles