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

# Génération de vidéos Seedance — POST /v1/videos

> Créez des tâches de génération de vidéos Seedance avec des entrées textuelles et multimodales, interrogez leur statut et téléchargez les vidéos terminées via Flatkey.

Utilisez `POST /v1/videos` pour créer une tâche asynchrone de génération de vidéos Seedance. Interrogez la tâche jusqu'à ce qu'elle se termine, puis téléchargez la vidéo depuis l'URL Flatkey retournée.

Les modèles pris en charge incluent `seedance-2.0` et `seedance-2.0-fast`. La disponibilité dépend de votre compte ; utilisez [`GET /v1/models`](/fr/api-reference/models) pour récupérer la liste des modèles actuels.

## Point de terminaison

```http theme={"dark"}
POST https://router.flatkey.ai/v1/videos
```

<Note>
  Flatkey accepte également `POST /v1/video/generations` et `GET /v1/video/generations/{task_id}`. Utilisez `/v1/videos` pour la structure de réponse standard et les données `usage` natives.
</Note>

## Requête

### En-têtes

| En-tête         | Valeur                    |
| --------------- | ------------------------- |
| `Authorization` | `Bearer $FLATKEY_API_KEY` |
| `Content-Type`  | `application/json`        |

### Paramètres du corps

<ParamField body="model" type="string" required>
  Identifiant du modèle Seedance. Utilisez `"seedance-2.0"` ou `"seedance-2.0-fast"`.
</ParamField>

<ParamField body="content" type="array" required>
  Éléments d'entrée multimodaux. Incluez au moins un élément textuel non vide, une URL d'image ou une URL de vidéo.
</ParamField>

<ParamField body="resolution" type="string">
  Résolution de sortie : `"480p"`, `"720p"` ou `"1080p"`.
</ParamField>

<ParamField body="ratio" type="string">
  Format d'image de sortie : `"16:9"`, `"4:3"`, `"1:1"`, `"3:4"`, `"9:16"`, `"21:9"` ou `"adaptive"`.
</ParamField>

<ParamField body="duration" type="integer">
  Durée de la vidéo de 4 à 15 secondes. Utilisez `-1` pour laisser le modèle choisir.
</ParamField>

<ParamField body="seed" type="integer">
  Graine aléatoire. Omettez-la pour utiliser une graine aléatoire.
</ParamField>

<ParamField body="watermark" type="boolean">
  Indique si un filigrane doit être ajouté. Par défaut : `false`.
</ParamField>

<ParamField body="generate_audio" type="boolean">
  Indique si un audio synchronisé doit être généré.
</ParamField>

### Éléments `content`

| `type`      | Champ de valeur | `role` pris en charge                          | Utilisation                                                             |
| ----------- | --------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `text`      | `text`          | —                                              | Invite textuelle. Plusieurs éléments textuels sont joints dans l'ordre. |
| `image_url` | `image_url.url` | `first_frame`, `last_frame`, `reference_image` | Image d'entrée ou de référence. Jusqu'à 9 images.                       |
| `video_url` | `video_url.url` | `reference_video`                              | Vidéo de référence. Jusqu'à 3 vidéos.                                   |
| `audio_url` | `audio_url.url` | `reference_audio`                              | Audio de référence. Jusqu'à 3 extraits.                                 |

Si une image utilise le rôle `first_frame` ou `last_frame`, l'API utilise le mode première/dernière image. Les autres images sont traitées comme des références.

### Paramètres avancés

<ParamField body="input_type" type="string">
  Mode d'entrée explicite : `"reference"` ou `"first_last_frame"`. Omettez-le pour déduire le mode depuis `content`.
</ParamField>

<ParamField body="web_search" type="boolean">
  Active l'augmentation par recherche web pour la tâche.
</ParamField>

<ParamField body="super_resolution_config" type="object">
  Agrandit la vidéo générée tout en conservant le même identifiant de tâche public.

  <Expandable title="Champs de super_resolution_config">
    <ParamField body="resolution" type="string">
      Résolution cible : `"720p"`, `"1080p"`, `"2k"` ou `"4k"`. Elle doit dépasser la résolution d'origine et ne peut pas être combinée avec `resolution_limit`.
    </ParamField>

    <ParamField body="resolution_limit" type="integer">
      Limite personnalisée en pixels pour le petit côté, de 64 à 2160. Ne peut pas être combinée avec `resolution`.
    </ParamField>

    <ParamField body="scene" type="string">
      Scène d'agrandissement : `"aigc"`, `"short_series"`, `"ugc"` ou `"old_film"`.
    </ParamField>

    <ParamField body="tool_version" type="string">
      Mode d'agrandissement : `"standard"` (par défaut) ou `"professional"`.
    </ParamField>

    <ParamField body="fps" type="integer">
      Fréquence d'images de sortie de 1 à 120. Les valeurs supérieures à la fréquence d'images source activent l'interpolation d'images.
    </ParamField>
  </Expandable>
</ParamField>

<Warning>
  `camera_fixed`, `frames`, `callback_url` et `return_last_frame` sont acceptés pour la compatibilité mais n'ont actuellement aucun effet.
</Warning>

## Exemples de requêtes

<CodeGroup>
  ```python python theme={"dark"}
  import os
  import requests

  response = requests.post(
      "https://router.flatkey.ai/v1/videos",
      headers={
          "Authorization": f"Bearer {os.environ['FLATKEY_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "model": "seedance-2.0",
          "content": [
              {
                  "type": "text",
                  "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
              }
          ],
          "resolution": "1080p",
          "ratio": "16:9",
          "duration": 5,
      },
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript node theme={"dark"}
  const response = await fetch("https://router.flatkey.ai/v1/videos", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FLATKEY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "seedance-2.0",
      content: [
        {
          type: "text",
          text: "An astronaut walking on the moon, cinematic lighting, slow camera push-in",
        },
      ],
      resolution: "1080p",
      ratio: "16:9",
      duration: 5,
    }),
  });

  if (!response.ok) throw new Error(await response.text());
  console.log(await response.json());
  ```

  ```bash curl theme={"dark"}
  curl https://router.flatkey.ai/v1/videos \
    -H "Authorization: Bearer $FLATKEY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "seedance-2.0",
      "content": [
        {
          "type": "text",
          "text": "An astronaut walking on the moon, cinematic lighting, slow camera push-in"
        }
      ],
      "resolution": "1080p",
      "ratio": "16:9",
      "duration": 5
    }'
  ```
</CodeGroup>

### Entrée première et dernière image

```json theme={"dark"}
{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "The camera slowly moves forward" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/first.jpg" },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/last.jpg" },
      "role": "last_frame"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5
}
```

### Référence multimodale avec agrandissement

```json theme={"dark"}
{
  "model": "seedance-2.0",
  "content": [
    { "type": "text", "text": "A woman smiles at the camera during a beach sunset" },
    {
      "type": "image_url",
      "image_url": { "url": "https://example.com/reference.jpg" },
      "role": "reference_image"
    }
  ],
  "resolution": "1080p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false,
  "super_resolution_config": {
    "resolution": "4k",
    "scene": "aigc",
    "tool_version": "professional",
    "fps": 60
  }
}
```

## Réponse

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "task_id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "model": "seedance-2.0",
  "status": "queued",
  "progress": 0,
  "created_at": 1780306574
}
```

### Champs de la réponse

<ResponseField name="id" type="string">
  Identifiant public de la tâche utilisé pour interroger la tâche et télécharger la vidéo terminée. `task_id` contient la même valeur.
</ResponseField>

<ResponseField name="status" type="string">
  Statut de la tâche : `queued`, `in_progress`, `completed` ou `failed`.
</ResponseField>

<ResponseField name="progress" type="integer">
  Progression de la génération de 0 à 100.
</ResponseField>

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

## Interroger le statut de la tâche

```http theme={"dark"}
GET https://router.flatkey.ai/v1/videos/{task_id}
```

```bash theme={"dark"}
curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"
```

Pendant la génération, la réponse inclut la progression actuelle :

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}
```

Lorsque la tâche se termine, la réponse inclut l'URL de la vidéo et l'utilisation des tokens :

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "completed",
  "progress": 100,
  "model": "seedance-2.0",
  "usage": {
    "completion_tokens": 120,
    "total_tokens": 120
  },
  "metadata": {
    "url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content"
  },
  "created_at": 1780306574,
  "completed_at": 1780306750
}
```

Les tâches échouées retournent les détails de l'erreur avec la réponse de la tâche :

```json theme={"dark"}
{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": "video_generation_failed"
  }
}
```

Tout solde prélevé à l'avance est automatiquement remboursé.

### Valeurs de statut

| Statut        | Signification                                                                                                              |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `queued`      | La tâche est en attente de démarrage.                                                                                      |
| `in_progress` | La vidéo est en cours de génération. `progress` varie de 0 à 100.                                                          |
| `completed`   | La vidéo est prête à l'adresse `metadata.url`, et l'utilisation des tokens est disponible dans `usage`.                    |
| `failed`      | La génération a échoué. Les détails sont disponibles dans `error.message`, et tout solde prélevé à l'avance est remboursé. |

## Télécharger la vidéo

```http theme={"dark"}
GET https://router.flatkey.ai/v1/videos/{task_id}/content
```

```bash theme={"dark"}
curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4
```

Le point de terminaison de contenu diffuse des données `video/mp4`. Il ne nécessite pas de token Bearer et peut être utilisé directement comme source `<video>`.

<Warning>
  Le point de terminaison de contenu ne fonctionne qu'une fois la tâche terminée et est limité en débit par adresse IP cliente. Traitez l'URL comme sensible car toute personne la possédant peut télécharger la vidéo.
</Warning>

## Erreurs

Les erreurs survenant au moment de la requête utilisent l'enveloppe d'erreur standard de Flatkey :

```json theme={"dark"}
{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}
```

| Scénario                          | Comportement                                                                      |
| --------------------------------- | --------------------------------------------------------------------------------- |
| `content` vide                    | La requête est rejetée. Incluez du texte non vide, une image ou une vidéo.        |
| Modèle indisponible               | Le `model` demandé n'est pas activé pour la route.                                |
| Solde insuffisant                 | La tâche n'est pas créée.                                                         |
| Défaillance temporaire du service | Réessayez plus tard en utilisant votre politique de délai exponentiel habituelle. |

## Exemple de bout en bout

Cet exemple crée une tâche, l'interroge toutes les cinq secondes et télécharge la vidéo terminée. Il nécessite [`jq`](https://jqlang.github.io/jq/).

```bash theme={"dark"}
#!/usr/bin/env bash
set -euo pipefail

BASE="https://router.flatkey.ai"
: "${FLATKEY_API_KEY:?Set FLATKEY_API_KEY before running this script}"

RESPONSE=$(curl -sS "$BASE/v1/videos" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "content": [
      { "type": "text", "text": "An astronaut walking on the moon, cinematic lighting" }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5
  }')

TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "task: $TASK_ID"

while true; do
  RESULT=$(curl -sS "$BASE/v1/videos/$TASK_ID" \
    -H "Authorization: Bearer $FLATKEY_API_KEY")
  STATUS=$(echo "$RESULT" | jq -r '.status')
  echo "status: $STATUS"

  [ "$STATUS" = "completed" ] && break
  if [ "$STATUS" = "failed" ]; then
    echo "failed: $(echo "$RESULT" | jq -r '.error.message')" >&2
    exit 1
  fi
  sleep 5
done

VIDEO_URL=$(echo "$RESULT" | jq -r '.metadata.url')
curl -L "$VIDEO_URL" -o output.mp4
echo "saved -> output.mp4"
```