Utiliser l’API Seedance : clé, requête, interrogation et références

Pour utiliser l’API Seedance, créez une clé API, envoyez le corps de tâche vidéo officiel de ModelArk à un point de terminaison unique, puis interrogez la tâche renvoyée jusqu’à ce que l’URL de la vidéo soit prête. Les mêmes étapes valent pour Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini et Seedance 2.5 ; seuls la valeur de model et quelques limites propres à chaque modèle changent.

Ce guide détaille chaque étape avec du code fonctionnel, puis montre comment ajouter des références, éditer un clip avec Seedance 2.5 et confier le travail à un agent de code.

De quoi avez-vous besoin avant la première requête ?

1. Une clé API. Créez-en une sur la page Clés API et conservez-la sur votre serveur. Ne la placez jamais dans du code navigateur.
2. Des crédits. Ajoutez un solde sur la page de facturation. Les crédits n’expirent jamais, et les tâches échouées ne sont pas facturées.
3. Un ID de modèle. Choisissez-en un dans le tableau ci-dessous.

Vous hésitez ? Le guide Seedance 2.0 vs Fast vs Mini et le guide Seedance 2.5 vs 2.0 les comparent.

export SEEDROUTER_API_KEY="your-key"

Comment envoyer une requête Seedance ?

Envoyez la tâche en POST à /v1/contents/generations/tasks. Le corps est la requête officielle ModelArk « create a video generation task » (créer une tâche de génération vidéo) :

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

La réponse est un identifiant de tâche, pas une vidéo :

{"id": "task_..."}

Si vous appelez déjà ModelArk, changez seulement l’URL de base en https://api.seedrouter.ai/v1 ainsi que la clé API. Les champs inconnus sont rejetés avant toute facturation, tout comme un réglage qu’un modèle ne prend pas en charge, par exemple 1080p sur Fast ou Mini.

Comment récupérer la vidéo ?

Interrogez la tâche toutes les 10 à 20 secondes jusqu’à ce que status vaille succeeded, failed ou expired. Un clip de 5 secondes en 720p prend généralement deux à trois minutes. En Python :

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/contents/generations/tasks",
    headers=headers,
    json={
        "model": "dreamina-seedance-2-0",
        "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Une tâche réussie contient la vidéo dans content.video_url, les tokens vidéo facturés dans usage.completion_tokens, et les réglages réellement utilisés pour le rendu, y compris le seed choisi par le modèle. La vidéo est hébergée sur notre stockage ; téléchargez-la dans le vôtre si vous en avez besoin sur le long terme.

Un dépassement de délai pendant l’interrogation ne signifie pas que la vidéo a échoué. Conservez l’identifiant de tâche et vérifiez-la à nouveau ; soumettre une nouvelle tâche revient à payer une seconde vidéo. Il n’y a pas d’URL de callback : l’interrogation est le moyen d’obtenir le résultat, et une tâche soumise ne peut pas être annulée.

Comment ajouter des images, des vidéos et de l’audio ?

Ajoutez des éléments à content, chacun avec une URL publique et un role :

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

Seedance 2.0 et ses versions Fast et Mini acceptent jusqu’à 9 images de référence, 3 vidéos et 3 pistes audio ; Seedance 2.5 accepte jusqu’à 30, 10 et 10. Les médias doivent être des URL : le base64 et les téléversements de fichiers ne sont pas acceptés. Le modèle ne prend pas en charge les images et vidéos de référence montrant de vrais visages humains. Les médias sont vérifiés au démarrage de la tâche, et un fichier qui dépasse une limite fait échouer la tâche avant toute génération, sans facturation.

Comment éditer ou prolonger un clip avec Seedance 2.5 ?

Envoyez le clip comme reference_video et définissez omni_reference_task_type :

{
  "model": "dreamina-seedance-2-5",
  "content": [
    {"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
    {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit"
}

Utilisez edit pour modifier le contenu de la vidéo et extend pour la prolonger au-delà de sa dernière image. Pour edit, laissez duration à sa valeur par défaut de -1 ; dans les deux cas, laissez ratio sur adaptive. Les secondes d’entrée sont facturées au tarif de référence, comme l’explique le guide des prix.

Comment laisser un agent de code utiliser l’API Seedance ?

Un agent de code comme Claude Code, Codex ou Cursor peut appeler l’API avec une commande shell ou un court script. SeedRouter ne fournit ni serveur MCP, ni skill packagé, ni nœud ComfyUI ; ce prompt constitue toute l’intégration. Exportez d’abord la clé, puis collez :

Use the SeedRouter API to generate a Seedance video for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k]    Ratio: [16:9 | 9:16 | 1:1 | adaptive]    Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]

Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
 "content": [{"type": "text", "text": "..."}],
 "resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.

Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.

L’étape d’approbation est importante : l’agent dépense votre solde, il ne doit donc jamais soumettre de lui-même.

Questions fréquentes

Comment obtenir une clé API Seedance ?

Connectez-vous, ouvrez la page Clés API et créez une clé. La même clé fonctionne pour tous les modèles Seedance et pour les autres modèles de SeedRouter.

Où trouver la documentation de l’API Seedance ?

Les références de l’API Seedance 2.0 et Seedance 2.5 listent chaque champ, chaque limite et chaque erreur, avec des exemples en cURL, Python, Node.js et Go, ainsi qu’un fichier OpenAPI et une version Markdown à copier.

Puis-je générer plusieurs vidéos à la fois ?

Envoyez une tâche par vidéo et interrogez les tâches en parallèle. Chaque tâche renvoie une vidéo et est facturée séparément. Pour lister les tâches récentes, appelez GET /v1/contents/generations/tasks avec page_num, page_size et des filtres comme filter.status.

Quelles erreurs dois-je gérer ?

Un 400 signifie que le corps enfreint une règle, comme un champ inconnu ou une résolution non prise en charge, et rien n’est facturé. Une tâche qui se termine en failed ou expired contient un code et un message d’erreur, et n’est pas facturée non plus. Le guide des erreurs liste chaque code et indique quand réessayer.

Envoyez votre première requête

Créez une clé, ajoutez un petit solde et exécutez l’exemple Python ci-dessus, ou essayez la même requête sans code dans le playground Seedance 2.0. Pour des clips plus longs et l’édition, remplacez le modèle par dreamina-seedance-2-5 et consultez la page Seedance 2.5.