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

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 sont seedance-2.0, seedance-2.0-fast, seedance-2.0-mini et seedance-2.5. La disponibilité dépend de votre compte ; utilisez GET /v1/models pour récupérer la liste des modèles actuels.

Point de terminaison

POST https://router.flatkey.ai/v1/videos

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.

Requête

En-têtes

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

Paramètres du corps

string

requis

Identifiant du modèle Seedance : "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini" ou "seedance-2.5".

array

requis

Éléments d’entrée multimodaux. Incluez au moins un élément non vide de type texte, image, vidéo ou audio. Consultez Éléments content.

string

Résolution de sortie. Par défaut : "720p".

Modèle	Valeurs prises en charge
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Format d’image de sortie : "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" ou "adaptive". Par défaut : "adaptive". Avec "adaptive", le modèle choisit le format à partir de vos images ou vidéos d’entrée. Pour seedance-2.5, les tâches avec première image et avec première et dernière images ne prennent en charge que "adaptive".

integer

Durée de la vidéo en secondes. Par défaut : 5. Les modèles Seedance 2.0 acceptent de 4 à 15 ; seedance-2.5 accepte de 4 à 30.

Envoyez toujours une valeur duration positive. Flatkey facture Seedance à la seconde : -1 (laisser le modèle choisir la durée) est donc rejeté avec video_price_not_configured. La seule exception est une édition vidéo seedance-2.5, qui exige -1.

boolean

Ajoute un filigrane « AI generated » dans le coin inférieur droit. Par défaut : false.

boolean

Génère une piste audio mono synchronisée. Par défaut : true. Définissez-le sur false si vous n’avez besoin que de la vidéo ; l’audio généré peut parfois échouer aux contrôles de droits d’auteur.

boolean

Renvoie la dernière image de la vidéo générée sous forme d’image. Par défaut : false. Avec true, la tâche terminée inclut metadata.last_frame_url, qui permet de télécharger un JPEG aux mêmes dimensions que la vidéo, sans filigrane. Utilisez-le comme first_frame de la tâche suivante pour enchaîner des clips. Comme metadata.url, il ne nécessite pas d’en-tête d’autorisation ; traitez-le comme confidentiel.

string

seedance-2.5 uniquement. Conteneur de la vidéo générée : "mp4" ou "mov". Par défaut : "mp4". Le MOV conserve une meilleure précision des couleurs pour l’étalonnage et la composition (H.264, YUV 4:4:4, audio PCM), mais certains lecteurs ne peuvent pas l’ouvrir. Le point de terminaison de contenu renvoie video/quicktime pour les résultats MOV.

string

seedance-2.5 uniquement, pour les tâches en mode référence. Indique au modèle le type de tâche souhaité : "auto" (par défaut), "reference", "edit" ou "extend". Le définir explicitement avance les vérifications du type de tâche au moment de la soumission : une combinaison non valide échoue donc immédiatement au lieu d’échouer après le démarrage de la tâche. "reference", "edit" et "extend" nécessitent tous des éléments de référence dans content ; une requête contenant uniquement du texte avec "reference" est rejetée. Consultez Édition et prolongation vidéo.

integer

Priorité dans la file d’attente, de 0 à 9. Par défaut : 0. Les valeurs plus élevées font passer la tâche devant les tâches de priorité inférieure en attente sur le même modèle. Pris en charge par tous les modèles Seedance 2.0 et par seedance-2.5. Les valeurs hors de la plage 0 à 9 sont rejetées avec 400.

integer

Nombre de secondes pendant lesquelles la tâche peut attendre et s’exécuter avant d’expirer. Par défaut : 172800 (48 heures). Utilisez une valeur plus courte si un résultat tardif ne vous est d’aucune utilité.

string

URL HTTPS publique qui reçoit un POST à chaque changement de statut de la tâche. Consultez Callbacks de tâche. Elle doit utiliser https, ne contenir aucun identifiant utilisateur, comporter au plus 2 048 caractères et se résoudre en une adresse publique ; sinon, la requête est rejetée avec 400.

Éléments `content`

`type`	Champ de valeur	`role` pris en charge	Limites
`text`	`text`	—	Texte de l’invite. Limitez-le à environ 1 000 mots en anglais.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Jusqu’à 9 images de référence (`seedance-2.5` : 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC ou HEIF ; moins de 30 Mo ; 300 à 6000 px par côté ; format de 0,4 à 2,5.
`video_url`	`video_url.url`	`reference_video`	Jusqu’à 3 vidéos, de 2 à 15 secondes chacune et 15 secondes au total (`seedance-2.5` : 10 vidéos, 30 secondes). MP4 ou MOV ; moins de 200 Mo ; au moins environ 409 600 pixels au total (par exemple 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Jusqu’à 3 extraits, de 2 à 15 secondes chacun et 15 secondes au total (`seedance-2.5` : 10 extraits, 30 secondes). WAV ou MP3 ; moins de 15 Mo. Les modèles Seedance 2.0 nécessitent au moins une image ou une vidéo en plus de l’audio.

Chaque URL peut être une URL HTTPS publique, un URI de données data:<mime>;base64, (images et audio uniquement) ou une référence asset:// issue de la bibliothèque de ressources. Le corps complet de la requête doit rester inférieur à 64 Mo. Choisissez un seul mode d’entrée par tâche. Ces modes ne peuvent pas être combinés :

Mode	Construction de `content`
Première image	Une image avec `role: "first_frame"`.
Première et dernière images	Deux images, l’une avec `role: "first_frame"` et l’autre avec `role: "last_frame"`. `last_frame` nécessite toujours un `first_frame`, et aucune des deux ne peut être combinée avec des éléments de référence.
Référence	Toute combinaison d’éléments `reference_image`, `reference_video` et `reference_audio`.

Édition vidéo

seedance-2.5 peut modifier ou prolonger une vidéo existante en mode référence. Décrivez la modification dans l’invite et désignez la vidéo par @Video1.

Tâche	Paramètres requis	Durée de sortie
Édition (remplacer un sujet, ajouter ou supprimer des objets, modifier l’audio)	Au moins un `reference_video` de 4 à 30 secondes, `ratio: "adaptive"`, `duration: -1`. Recommandé : `omni_reference_task_type: "edit"`.	Identique à celle de la vidéo d’entrée modifiée
Prolongation (poursuivre une vidéo vers l’avant ou vers l’arrière)	Au moins un `reference_video`, `ratio: "adaptive"`, une valeur `duration` positive. Recommandé : `omni_reference_task_type: "extend"`.	`duration`

{
  "model": "seedance-2.5",
  "resolution": "720p",
  "ratio": "adaptive",
  "duration": -1,
  "omni_reference_task_type": "edit",
  "content": [
    { "type": "text", "text": "Edit @Video1: make the ball bright green and keep everything else unchanged." },
    { "type": "video_url", "video_url": { "url": "https://example.com/input.mp4" }, "role": "reference_video" }
  ]
}

Comme toute requête seedance-2.5 comportant une vidéo de référence, une édition est facturée au tarif avec vidéo de la résolution choisie, pour une durée fixe de 30 secondes, quelle que soit la durée d’entrée ou de sortie.

Mode brouillon

seedance-2.5 peut d’abord générer un brouillon peu coûteux en 480p, afin que vous puissiez vérifier la scène, les plans et le mouvement avant de payer la vidéo finale. Deux requêtes sont nécessaires :

Créez le brouillon. Envoyez une requête normale avec "draft": true et "resolution": "480p". Elle est facturée comme une vidéo 480p ordinaire.
Générez la vidéo finale. Une fois le brouillon terminé, envoyez une requête dont le seul élément content est un draft_task pointant vers l’identifiant de tâche du brouillon, avec "resolution": "1080p".

{
  "model": "seedance-2.5",
  "resolution": "1080p",
  "content": [
    { "type": "draft_task", "draft_task": { "id": "task_3f9a00000000000000000000000000e2" } }
  ]
}

La vidéo finale reprend l’invite, les médias, la durée, le format, la graine, le réglage audio et le type de tâche du brouillon. N’envoyez pas duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft ni aucun autre élément content avec un draft_task ; la requête est rejetée avec 400. Vous pouvez toujours définir return_last_frame, output_format, watermark, priority, execution_expires_after et callback_url.

Règle	Détail
Modèle	`model` doit correspondre à celui du brouillon.
Identifiant de tâche du brouillon	Utilisez l’identifiant `task_…` renvoyé par Flatkey pour le brouillon. Il doit s’agir de votre propre tâche, et celle-ci doit être terminée.
Résolution	Brouillon : `480p` uniquement. Vidéo finale : `1080p` uniquement.
Expiration	Un brouillon peut être utilisé pendant 7 jours après sa création.
Facturation	La vidéo finale est facturée au tarif 1080p pour la durée du brouillon. Si le brouillon utilisait une vidéo de référence, le tarif avec vidéo s’applique pour une durée fixe de 30 secondes.

Seedance n’accepte pas directement les images ou vidéos montrant de vrais visages humains. Téléversez-les en tant que ressources de personne réelle et référencez-les avec asset://.

Exemples de requêtes

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())

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());

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
  }'

Entrée première et dernière image

{
  "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,
  "generate_audio": false
}

Référence multimodale

{
  "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
}

Réponse

{
  "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

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.

string

Statut de la tâche : queued, in_progress, completed ou failed.

integer

Progression de la génération de 0 à 100.

integer

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

Interroger le statut de la tâche

GET https://router.flatkey.ai/v1/videos/{task_id}

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 :

{
  "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 :

{
  "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",
    "last_frame_url": "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/last-frame"
  },
  "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 :

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "failed",
  "error": {
    "message": "The video generation task failed.",
    "code": ""
  }
}

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é.

Callbacks de tâche

Définissez callback_url pour recevoir les changements de statut au lieu d’interroger la tâche, ou en complément. Flatkey envoie un POST avec Content-Type: application/json lorsque la tâche passe à in_progress, completed ou failed. Le corps correspond exactement à ce que renvoie GET /v1/videos/{task_id} à ce moment-là, y compris metadata.url et metadata.last_frame_url pour les tâches terminées.

{
  "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
}

En-tête	Valeur
`X-Flatkey-Event-Id`	`<task_id>:<status>`, par exemple `task_3f9a…e2:completed`. Le même événement peut être livré plusieurs fois ; utilisez cet en-tête pour ignorer les doublons.

Répondez avec n’importe quel statut 2xx dans un délai de 5 secondes. Sinon, Flatkey réessaie deux fois, après 2 puis 8 secondes, puis abandonne. Les redirections ne sont pas suivies. Les callbacks ne sont pas signés : vérifiez donc un résultat en interrogeant la tâche avant d’agir, et continuez de considérer l’interrogation comme la source de vérité au cas où un callback serait perdu.

Télécharger la vidéo

GET https://router.flatkey.ai/v1/videos/{task_id}/content

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, ou video/quicktime si la tâche a utilisé output_format: "mov". Il ne nécessite pas de token Bearer et peut être utilisé directement comme source <video>.

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.

Erreurs

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

{
  "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.
`priority` hors de la plage 0 à 9	La requête renvoie `400` avec `invalid_request`.
`callback_url` non valide	La requête renvoie `400` avec `invalid_request` lorsque l’URL n’utilise pas HTTPS, contient des identifiants, dépasse 2 048 caractères ou pointe vers une adresse privée ou locale.
`duration: -1` en dehors d’une édition vidéo `seedance-2.5`	La requête renvoie `400` avec `video_price_not_configured`.
Entrée non valide pour le modèle	La requête renvoie `400` avec `fail_to_fetch_task` ou, pour les requêtes qui utilisent des références `asset://`, la tâche échoue avec `task preparation failed`. Vérifiez la résolution, la durée, les limites de contenu et les règles de mode d’entrée ci-dessus. Aucuns frais ne vous sont facturés.
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.

#!/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"

Vue d'ensemble

Endpoints

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

Point de terminaison

Requête

En-têtes

Paramètres du corps

Éléments `content`

Édition vidéo

Mode brouillon

Exemples de requêtes

Entrée première et dernière image

Référence multimodale

Réponse

Champs de la réponse

Interroger le statut de la tâche

Valeurs de statut

Callbacks de tâche

Télécharger la vidéo

Erreurs

Exemple de bout en bout

​Point de terminaison

​Requête

​En-têtes

​Paramètres du corps

​Éléments content

​Édition vidéo

​Mode brouillon

​Exemples de requêtes

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

​Référence multimodale

​Réponse

​Champs de la réponse

​Interroger le statut de la tâche

​Valeurs de statut

​Callbacks de tâche

​Télécharger la vidéo

​Erreurs

​Exemple de bout en bout

Point de terminaison

Requête

En-têtes

Paramètres du corps

Éléments `content`

Édition vidéo

Mode brouillon

Exemples de requêtes

Entrée première et dernière image

Référence multimodale

Réponse

Champs de la réponse

Interroger le statut de la tâche

Valeurs de statut

Callbacks de tâche

Télécharger la vidéo

Erreurs

Exemple de bout en bout