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 incluent seedance-2.0 et seedance-2.0-fast. 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. Utilisez "seedance-2.0" ou "seedance-2.0-fast".

array

requis

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

string

Résolution de sortie : "480p", "720p" ou "1080p".

string

Format d’image de sortie : "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" ou "adaptive".

integer

Durée de la vidéo de 4 à 15 secondes. Utilisez -1 pour laisser le modèle choisir.

integer

Graine aléatoire. Omettez-la pour utiliser une graine aléatoire.

boolean

Indique si un filigrane doit être ajouté. Par défaut : false.

boolean

Indique si un audio synchronisé doit être généré.

É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

string

Mode d’entrée explicite : "reference" ou "first_last_frame". Omettez-le pour déduire le mode depuis content.

boolean

Active l’augmentation par recherche web pour la tâche.

object

Agrandit la vidéo générée tout en conservant le même identifiant de tâche public.

Afficher Champs de super_resolution_config

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.

integer

Limite personnalisée en pixels pour le petit côté, de 64 à 2160. Ne peut pas être combinée avec resolution.

string

Scène d’agrandissement : "aigc", "short_series", "ugc" ou "old_film".

string

Mode d’agrandissement : "standard" (par défaut) ou "professional".

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.

camera_fixed, frames, callback_url et return_last_frame sont acceptés pour la compatibilité mais n’ont actuellement aucun effet.

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
}

Référence multimodale avec agrandissement

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

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

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

Paramètres avancés

Exemples de requêtes

Entrée première et dernière image

Référence multimodale avec agrandissement

Réponse

Champs de la réponse

Interroger le statut de la tâche

Valeurs de statut

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

​Paramètres avancés

​Exemples de requêtes

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

​Référence multimodale avec agrandissement

​Réponse

​Champs de la réponse

​Interroger le statut de la tâche

​Valeurs de statut

​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`

Paramètres avancés

Exemples de requêtes

Entrée première et dernière image

Référence multimodale avec agrandissement

Réponse

Champs de la réponse

Interroger le statut de la tâche

Valeurs de statut

Télécharger la vidéo

Erreurs

Exemple de bout en bout