Seedance API nutzen: Anleitung zu Key, Anfrage, Polling und Referenzen

Um die Seedance API zu nutzen, erstellst du einen API-Key, sendest den offiziellen ModelArk-Body für Videoaufgaben an einen Endpunkt und fragst die zurückgegebene Aufgabe ab, bis die Video-URL bereitsteht. Dieselben Schritte funktionieren für Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini und Seedance 2.5; nur der Wert von model und einige modellspezifische Limits ändern sich.

Diese Anleitung geht jeden Schritt mit funktionierendem Code durch und zeigt dann, wie du Referenzen hinzufügst, einen Clip mit Seedance 2.5 bearbeiten und die Aufgabe an einen Coding-Agenten übergeben.

Was brauchst du vor der ersten Anfrage?

1. Einen API-Key. Erstelle ihn auf der Seite API-Keys und bewahre ihn auf deinem Server auf. Setze ihn niemals in Browser-Code ein.
2. Guthaben. Lade auf der Abrechnungsseite Guthaben auf. Guthaben verfällt nie, und fehlgeschlagene Aufgaben werden nicht berechnet.
3. Eine Modell-ID. Wähle eine aus der Tabelle unten.

Unsicher, welches? Der Leitfaden Seedance 2.0 vs Fast vs Mini und der Leitfaden Seedance 2.5 vs 2.0 vergleichen sie.

export SEEDROUTER_API_KEY="your-key"

Wie sendest du eine Seedance-Anfrage?

Sende die Aufgabe per POST an /v1/contents/generations/tasks. Der Body ist die offizielle ModelArk-Anfrage „Videogenerierungsaufgabe erstellen“:

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

Die Antwort ist eine Aufgaben-ID, kein Video:

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

Wenn du ModelArk bereits aufrufst, änderst du nur die Basis-URL auf https://api.seedrouter.ai/v1 und den API-Key. Unbekannte Felder werden abgelehnt, bevor etwas berechnet wird, ebenso eine Einstellung, die ein Modell nicht unterstützt, etwa 1080p auf Fast oder Mini.

Wie bekommst du das Video?

Frage die Aufgabe alle 10 bis 20 Sekunden ab, bis status den Wert succeeded, failed oder expired hat. Ein 5-Sekunden-Clip in 720p dauert meist zwei bis drei Minuten. In 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}.")

Eine erfolgreiche Aufgabe enthält das Video in content.video_url, die abgerechneten Video-Token in usage.completion_tokens und die tatsächlich gerenderten Einstellungen, einschließlich des seed, den das Modell gewählt hat. Das Video liegt auf unserem Speicher; lade es in deinen eigenen herunter, wenn du es langfristig brauchst.

Ein Timeout beim Abfragen bedeutet nicht, dass das Video fehlgeschlagen ist. Behalte die Aufgaben-ID und frage erneut ab; eine neue Aufgabe abzusenden bedeutet, ein zweites Video zu bezahlen. Es gibt keine Callback-URL, Polling ist also der Weg zum Ergebnis, und eine abgesendete Aufgabe lässt sich nicht abbrechen.

Wie fügst du Bilder, Videos und Audio hinzu?

Füge Einträge zu content hinzu, jeweils mit einer öffentlichen URL und einer 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 und seine Versionen Fast und Mini nehmen bis zu 9 Referenzbilder, 3 Videos und 3 Audiospuren an; Seedance 2.5 bis zu 30, 10 und 10. Medien müssen URLs sein: Base64 und Datei-Uploads werden nicht akzeptiert. Referenzbilder und -videos mit echten menschlichen Gesichtern werden vom Modell nicht unterstützt. Medien werden beim Start der Aufgabe geprüft, und eine Datei, die ein Limit verletzt, lässt die Aufgabe vor jeder Generierung fehlschlagen, ohne Berechnung.

Wie bearbeitest oder verlängerst du einen Clip mit Seedance 2.5?

Sende den Clip als reference_video und setze 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"
}

Nutze edit, um den Inhalt des Materials zu ändern, und extend, um es über seinen letzten Frame hinaus fortzusetzen. Lass bei edit die duration auf ihrem Standardwert -1; lass bei beiden ratio auf adaptive. Die Eingabesekunden werden zum Referenztarif berechnet, wie der Preisleitfaden erklärt.

Wie lässt du einen Coding-Agenten die Seedance API nutzen?

Ein Coding-Agent wie Claude Code, Codex oder Cursor kann die API mit einem Shell-Befehl oder einem kurzen Skript aufrufen. SeedRouter liefert keinen MCP-Server, keinen fertigen Skill und keinen ComfyUI-Node; dieser Prompt ist die gesamte Integration. Exportiere zuerst den Key und füge dann Folgendes ein:

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.

Der Freigabeschritt ist wichtig: Der Agent gibt dein Guthaben aus und sollte daher niemals selbstständig absenden.

Häufige Fragen

Wie bekomme ich einen API-Key für Seedance?

Melde dich an, öffne die Seite API-Keys und erstelle einen Key. Derselbe Key funktioniert für jedes Seedance-Modell und für die anderen Modelle bei SeedRouter.

Wo finde ich die Dokumentation zur Seedance API?

Die API-Referenzen zu Seedance 2.0 und Seedance 2.5 listen jedes Feld, jedes Limit und jeden Fehler, mit Beispielen in cURL, Python, Node.js und Go, dazu eine OpenAPI-Datei und eine kopierbare Markdown-Version.

Kann ich mehrere Videos gleichzeitig erzeugen?

Sende eine Aufgabe pro Video und frage die Aufgaben parallel ab. Jede Aufgabe liefert ein Video und wird einzeln abgerechnet. Um die letzten Aufgaben aufzulisten, rufst du GET /v1/contents/generations/tasks mit page_num, page_size und Filtern wie filter.status auf.

Welche Fehler sollte ich behandeln?

Ein 400 bedeutet, dass der Body gegen eine Regel verstoßen hat, etwa durch ein unbekanntes Feld oder eine nicht unterstützte Auflösung; berechnet wird nichts. Eine Aufgabe, die mit failed oder expired endet, enthält einen Fehlercode und eine Meldung und wird ebenfalls nicht berechnet. Der Leitfaden zu Fehlern listet jeden Code und wann sich ein erneuter Versuch lohnt.

Sende deine erste Anfrage

Erstelle einen Key, lade ein kleines Guthaben auf und führe das Python-Beispiel oben aus – oder probiere dieselbe Anfrage ohne Code im Seedance 2.0 Playground. Für längere Clips und Bearbeitung änderst du das Modell auf dreamina-seedance-2-5 und siehst dir die Seite zu Seedance 2.5 an.