> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Créer une vidéo

> Crée une tâche de génération 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

<ParamField body="model" type="string" default="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](/fr/guides/video-generation) et [Models API](/fr/api-reference/models/list-models).
</ParamField>

<Note>
  **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`
</Note>

<ParamField body="prompt" type="string" required>
  Description textuelle de la vidéo à générer. Ce champ est requis pour la plupart des modèles publics.
</ParamField>

<ParamField body="operation" type="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.
</ParamField>

<ParamField body="image_url" type="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`.
</ParamField>

<ParamField body="image" type="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.
</ParamField>

<ParamField body="reference_images" type="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](/fr/guides/seedance-2-video). 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.
</ParamField>

<ParamField body="material_asset_id" type="string">
  ID de matériau Seedance TokenLab renvoyé par [Créer un matériau](/fr/api-reference/video/create-material-asset) 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.
</ParamField>

<ParamField body="material_asset_ids" type="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.
</ParamField>

<Info>
  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.
</Info>

<ParamField body="reference_image_type" type="string">
  Champ facultatif pour les modèles qui distinguent les références `asset` et `style`.
</ParamField>

<ParamField body="kling_elements" type="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.
</ParamField>

<ParamField body="video_url" type="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`.
</ParamField>

<ParamField body="video_urls" type="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.
</ParamField>

<ParamField body="audio_url" type="string">
  URL publique du fichier audio pour les modèles `audio-to-video`.
</ParamField>

<ParamField body="audio_urls" type="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.
</ParamField>

<ParamField body="task_id" type="string">
  Identifiant de tâche utilisé par certains flux de continuation, d’extension ou dérivés.
</ParamField>

<ParamField body="extend_at" type="integer">
  Offset de départ spécifique au modèle pour certains flux `video-extension`.
</ParamField>

<ParamField body="extend_times" type="string">
  Multiplicateur ou nombre de répétitions spécifique au modèle pour certains flux `video-extension`.
</ParamField>

<ParamField body="duration" type="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.
</ParamField>

<ParamField body="seconds" type="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`.
</ParamField>

<ParamField body="aspect_ratio" type="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.
</ParamField>

<ParamField body="resolution" type="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`.
</ParamField>

<ParamField body="output_audio" type="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`.
</ParamField>

<ParamField body="draft" type="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`.
</ParamField>

<ParamField body="draft_task_id" type="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.
</ParamField>

<ParamField body="ratio" type="string">
  Alias compatible de `aspect_ratio`. Si `ratio` et `aspect_ratio` sont envoyés ensemble, ils doivent être identiques.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Alias compatible de `output_audio`. Si `generate_audio`, `output_audio` et `outputAudio` apparaissent ensemble, toutes les valeurs doivent correspondre.
</ParamField>

<ParamField body="execution_expires_after" type="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.
</ParamField>

<ParamField body="priority" type="integer">
  Priorité optionnelle de tâche de `0` à `9` pour les modèles vidéo compatibles. Ne combinez pas `priority` avec `service_tier=flex`.
</ParamField>

<ParamField body="safety_identifier" type="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.
</ParamField>

<ParamField body="service_tier" type="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.
</ParamField>

<ParamField body="frames" type="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.
</ParamField>

<ParamField body="camera_fixed" type="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.
</ParamField>

<ParamField body="fps" type="integer">
  Fréquence d’images (1–120). N’a d’effet que sur les modèles qui l’exposent publiquement.
</ParamField>

<ParamField body="negative_prompt" type="string">
  Éléments à éviter dans la génération.
</ParamField>

<ParamField body="seed" type="integer">
  Graine aléatoire pour une génération reproductible. Seedance utilise `-1` comme graine aléatoire lorsque le champ est omis.
</ParamField>

<ParamField body="cfg_scale" type="number">
  Intensité de suivi du prompt (0–20), effective uniquement sur les modèles qui la prennent en charge.
</ParamField>

<ParamField body="motion_strength" type="number">
  Intensité du mouvement (0–1), effective uniquement sur les modèles compatibles.
</ParamField>

<ParamField body="start_image" type="string">
  URL de l’image de premier frame, ou entrée image compatible, pour `start-end-to-video`.
</ParamField>

<ParamField body="end_image" type="string">
  URL de l’image de dernier frame, ou entrée image compatible, pour `start-end-to-video`.
</ParamField>

<ParamField body="size" type="string">
  Niveau de taille propre au modèle pour les modèles vidéo compatibles.
</ParamField>

<ParamField body="watermark" type="boolean">
  Option de filigrane pour les modèles qui l’exposent. Seedance utilise `false` par défaut lorsque le champ est omis.
</ParamField>

<ParamField body="effect_type" type="string">
  Sélecteur d’effet spécifique au modèle pour certains flux d’édition ou d’effets.
</ParamField>

<ParamField body="user" type="string">
  Identifiant unique de l’utilisateur final. Pour Seedance, TokenLab utilise aussi cette valeur comme `safety_identifier` lorsque ce champ est omis.
</ParamField>

## 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

```bash cURL theme={null}
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

<ResponseField name="id" type="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.
</ResponseField>

<ResponseField name="task_id" type="string">
  Identifiant unique du task pour le polling.
</ResponseField>

<ResponseField name="poll_url" type="string">
  URL de polling recommandée pour ce task. Utilisez ce chemin tel quel lors des vérifications d’état.
</ResponseField>

<ResponseField name="billing_transaction_id" type="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.
</ResponseField>

<ResponseField name="status" type="string">
  Statut initial : `pending`.
</ResponseField>

<ResponseField name="created" type="integer">
  Timestamp Unix de création de la tâche.
</ResponseField>

<ResponseField name="model" type="string">
  Modèle utilisé.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "status": "pending",
    "model": "veo3.1",
    "created": 1706000000
  }
  ```
</ResponseExample>

## Image vers vidéo

```python theme={null}
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.

```python theme={null}
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](/fr/guides/seedance-2-video). `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.

```python theme={null}
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.

```python theme={null}
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`.

```python theme={null}
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.

```python theme={null}
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](/fr/api-reference/models/list-models) comme référence actuelle avant d’implémenter un flux propre à un modèle :

```bash theme={null}
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.