Seedance Videogenerierung — POST /v1/videos

Verwende POST /v1/videos, um eine asynchrone Seedance-Videogenerierungsaufgabe zu erstellen. Rufe den Status der Aufgabe ab, bis sie abgeschlossen ist, und lade dann das Video von der zurückgegebenen Flatkey-URL herunter. Unterstützte Modelle sind seedance-2.0, seedance-2.0-fast, seedance-2.0-mini und seedance-2.5. Die Verfügbarkeit hängt von deinem Konto ab; verwende GET /v1/models, um die aktuelle Modellliste abzurufen.

Endpunkt

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

Flatkey akzeptiert auch POST /v1/video/generations und GET /v1/video/generations/{task_id}. Verwende /v1/videos für die standardisierte Antwortstruktur und native usage-Daten.

Anfrage

Header	Wert
`Authorization`	`Bearer $FLATKEY_API_KEY`
`Content-Type`	`application/json`

Body-Parameter

string

erforderlich

Seedance-Modell-ID: "seedance-2.0", "seedance-2.0-fast", "seedance-2.0-mini" oder "seedance-2.5".

array

erforderlich

Multimodale Eingabeelemente. Füge mindestens ein nicht leeres Text-, Bild-, Video- oder Audioelement ein. Siehe content-Elemente.

string

Ausgabeauflösung. Standard: "720p".

Modell	Unterstützte Werte
`seedance-2.0`	`"480p"`, `"720p"`, `"1080p"`, `"4k"`
`seedance-2.0-fast`, `seedance-2.0-mini`	`"480p"`, `"720p"`
`seedance-2.5`	`"480p"`, `"720p"`, `"1080p"`

string

Ausgabe-Seitenverhältnis: "16:9", "4:3", "1:1", "3:4", "9:16", "21:9" oder "adaptive". Standard: "adaptive". Bei "adaptive" wählt das Modell das Seitenverhältnis anhand deiner Eingabebilder oder -videos. Bei seedance-2.5 unterstützen Aufgaben mit erstem Frame sowie mit erstem und letztem Frame nur "adaptive".

integer

Videolänge in Sekunden. Standard: 5. Seedance-2.0-Modelle akzeptieren 4 bis 15; seedance-2.5 akzeptiert 4 bis 30.

Sende immer eine positive duration. Flatkey rechnet Seedance pro Sekunde ab, daher wird -1 (das Modell wählt die Länge) mit video_price_not_configured abgelehnt. Die einzige Ausnahme ist eine Videobearbeitung mit seedance-2.5, die -1 erfordert.

boolean

Fügt unten rechts ein „AI generated“-Wasserzeichen hinzu. Standard: false.

boolean

Generiert eine synchronisierte Mono-Audiospur. Standard: true. Setze den Wert auf false, wenn du nur das Video brauchst; generiertes Audio kann gelegentlich an Urheberrechtsprüfungen scheitern.

boolean

Gibt den letzten Frame des generierten Videos als Bild zurück. Standard: false. Bei true enthält die abgeschlossene Aufgabe metadata.last_frame_url, über die du ein JPEG in denselben Abmessungen wie das Video und ohne Wasserzeichen herunterlädst. Verwende es als first_frame der nächsten Aufgabe, um Clips aneinanderzureihen. Wie metadata.url benötigt es keinen Autorisierungsheader; behandle es als privat.

string

Nur seedance-2.5. Container des generierten Videos: "mp4" oder "mov". Standard: "mp4". MOV bewahrt mehr Farbpräzision für Color Grading und Compositing (H.264, YUV 4:4:4, PCM-Audio), lässt sich aber in manchen Playern nicht öffnen. Der Content-Endpunkt liefert für MOV-Ergebnisse video/quicktime.

string

Nur seedance-2.5, für Aufgaben im Referenzmodus. Teilt dem Modell mit, welche Aufgabe du beabsichtigst: "auto" (Standard), "reference", "edit" oder "extend". Wenn du den Wert explizit setzt, werden die Prüfungen des Aufgabentyps bereits beim Absenden ausgeführt, sodass eine ungültige Kombination sofort fehlschlägt statt erst nach dem Start der Aufgabe. "reference", "edit" und "extend" erfordern alle Referenzelemente in content; eine reine Textanfrage mit "reference" wird abgelehnt. Siehe Videobearbeitung und -verlängerung.

integer

Warteschlangenpriorität von 0 bis 9. Standard: 0. Höhere Werte ziehen die Aufgabe vor Aufgaben mit niedrigerer Priorität, die auf dasselbe Modell warten. Unterstützt von allen Seedance-2.0-Modellen und seedance-2.5. Werte außerhalb von 0–9 werden mit 400 abgelehnt.

integer

Sekunden, die die Aufgabe warten und laufen darf, bevor sie abläuft. Standard: 172800 (48 Stunden). Verwende einen kürzeren Wert, wenn dir ein verspätetes Ergebnis nichts nützt.

string

Öffentliche HTTPS-URL, die bei jeder Statusänderung der Aufgabe einen POST erhält. Siehe Aufgaben-Callbacks. Sie muss https verwenden, darf keine Benutzer-Anmeldedaten enthalten, darf höchstens 2.048 Zeichen lang sein und muss zu einer öffentlichen Adresse aufgelöst werden; andernfalls wird die Anfrage mit 400 abgelehnt.

`content`-Elemente

`type`	Wertfeld	Unterstützte `role`	Grenzen
`text`	`text`	—	Prompt-Text. Halte ihn unter etwa 1.000 englischen Wörtern.
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`	Bis zu 9 Referenzbilder (`seedance-2.5`: 30). JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC oder HEIF; unter 30 MB; 300–6000 px pro Seite; Seitenverhältnis 0,4–2,5.
`video_url`	`video_url.url`	`reference_video`	Bis zu 3 Videos, je 2–15 Sekunden und insgesamt 15 Sekunden (`seedance-2.5`: 10 Videos, 30 Sekunden). MP4 oder MOV; unter 200 MB; mindestens etwa 409.600 Pixel insgesamt (zum Beispiel 854×480).
`audio_url`	`audio_url.url`	`reference_audio`	Bis zu 3 Clips, je 2–15 Sekunden und insgesamt 15 Sekunden (`seedance-2.5`: 10 Clips, 30 Sekunden). WAV oder MP3; unter 15 MB. Seedance-2.0-Modelle benötigen neben Audio mindestens ein Bild oder Video.

Jede URL kann eine öffentliche HTTPS-URL, eine data:<mime>;base64,-Data-URI (nur Bilder und Audio) oder eine asset://-Referenz aus der Asset-Bibliothek sein. Der gesamte Anfrage-Body muss unter 64 MB bleiben. Wähle pro Aufgabe einen Eingabemodus. Diese Modi lassen sich nicht kombinieren:

Modus	So baust du `content` auf
Erster Frame	Ein Bild mit `role: "first_frame"`.
Erster und letzter Frame	Zwei Bilder, eines mit `role: "first_frame"` und eines mit `role: "last_frame"`. `last_frame` erfordert immer einen `first_frame`, und keines der beiden lässt sich mit Referenzelementen kombinieren.
Referenz	Eine beliebige Kombination aus `reference_image`-, `reference_video`- und `reference_audio`-Elementen.

Videobearbeitung

seedance-2.5 kann ein vorhandenes Video im Referenzmodus bearbeiten oder verlängern. Beschreibe die Änderung im Prompt und verweise auf das Video als @Video1.

Aufgabe	Erforderliche Einstellungen	Ausgabelänge
Bearbeitung (ein Motiv ersetzen, Objekte hinzufügen oder entfernen, Audio ändern)	Mindestens ein `reference_video` mit 4–30 Sekunden Länge, `ratio: "adaptive"`, `duration: -1`. Empfohlen: `omni_reference_task_type: "edit"`.	Wie das bearbeitete Eingabevideo
Verlängerung (ein Video vorwärts oder rückwärts fortsetzen)	Mindestens ein `reference_video`, `ratio: "adaptive"`, eine positive `duration`. Empfohlen: `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" }
  ]
}

Wie jede seedance-2.5-Anfrage mit Referenzvideo wird eine Bearbeitung zum Mit-Video-Tarif der jeweiligen Auflösung für pauschal 30 Sekunden abgerechnet, unabhängig von der Eingabe- oder Ausgabelänge.

Entwurfsmodus

seedance-2.5 kann zuerst einen günstigen Entwurf in 480p rendern, damit du Szene, Kameraeinstellungen und Bewegung prüfen kannst, bevor du für das finale Video bezahlst. Dafür sind zwei Anfragen nötig:

Entwurf erstellen. Sende eine normale Anfrage mit "draft": true und "resolution": "480p". Sie wird wie ein reguläres 480p-Video abgerechnet.
Finales Video rendern. Sobald der Entwurf abgeschlossen ist, sende eine Anfrage mit "resolution": "1080p", deren einziges content-Element ein draft_task ist, der auf die Aufgaben-ID des Entwurfs verweist.

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

Das finale Video übernimmt Prompt, Medien, Länge, Seitenverhältnis, Seed, Audioeinstellung und Aufgabentyp des Entwurfs. Sende zusammen mit einem draft_task weder duration, ratio, frames, seed, generate_audio, omni_reference_task_type, draft noch weitere content-Elemente; sonst wird die Anfrage mit 400 abgelehnt. return_last_frame, output_format, watermark, priority, execution_expires_after und callback_url kannst du weiterhin setzen.

Regel	Details
Modell	`model` muss mit dem Entwurf übereinstimmen.
Aufgaben-ID des Entwurfs	Verwende die `task_…`-ID, die Flatkey für den Entwurf zurückgegeben hat. Es muss deine eigene Aufgabe sein, und sie muss abgeschlossen sein.
Auflösung	Entwurf: nur `480p`. Finales Video: nur `1080p`.
Gültigkeit	Ein Entwurf kann bis zu 7 Tage nach seiner Erstellung verwendet werden.
Abrechnung	Das finale Video wird zum 1080p-Tarif für die Länge des Entwurfs abgerechnet. Hat der Entwurf ein Referenzvideo verwendet, gilt der Mit-Video-Tarif für pauschal 30 Sekunden.

Seedance akzeptiert keine Bilder oder Videos, die echte menschliche Gesichter direkt zeigen. Lade sie als personenbezogene Assets hoch und referenziere sie mit asset://.

Beispielanfragen

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

Eingabe mit erstem und letztem Frame

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

Multimodale Referenz

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

Antwort

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

Antwortfelder

string

Öffentliche Aufgaben-ID, die zum Abrufen des Status und zum Herunterladen des fertigen Videos verwendet wird. task_id enthält denselben Wert.

string

Aufgabenstatus: queued, in_progress, completed oder failed.

integer

Generierungsfortschritt von 0 bis 100.

integer

Unix-Zeitstempel für die Aufgabenerstellung.

Aufgabenstatus abrufen

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

curl https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2 \
  -H "Authorization: Bearer $FLATKEY_API_KEY"

Während die Generierung läuft, enthält die Antwort den aktuellen Fortschritt:

{
  "id": "task_3f9a00000000000000000000000000e2",
  "object": "video",
  "status": "in_progress",
  "progress": 50,
  "model": "seedance-2.0",
  "created_at": 1780306574
}

Wenn die Aufgabe abgeschlossen ist, enthält die Antwort die Video-URL und die Token-Nutzung:

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

Fehlgeschlagene Aufgaben geben die Fehlerdetails zusammen mit der Aufgabenantwort zurück:

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

Jedes vorab verbrauchte Guthaben wird automatisch erstattet.

Statuswerte

Status	Bedeutung
`queued`	Die Aufgabe wartet auf den Start.
`in_progress`	Das Video wird gerade generiert. `progress` reicht von 0 bis 100.
`completed`	Das Video ist unter `metadata.url` verfügbar, und die Token-Nutzung ist in `usage` einsehbar.
`failed`	Die Generierung ist fehlgeschlagen. Details sind in `error.message` verfügbar, und jedes vorab verbrauchte Guthaben wird erstattet.

Aufgaben-Callbacks

Setze callback_url, um Statusänderungen anstelle der Abfrage oder zusätzlich dazu zu empfangen. Flatkey sendet einen POST mit Content-Type: application/json, wenn die Aufgabe in in_progress, completed oder failed wechselt. Der Body entspricht genau dem, was GET /v1/videos/{task_id} in diesem Moment zurückgibt, einschließlich metadata.url und metadata.last_frame_url bei abgeschlossenen Aufgaben.

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

Header	Wert
`X-Flatkey-Event-Id`	`<task_id>:<status>`, zum Beispiel `task_3f9a…e2:completed`. Dasselbe Ereignis kann mehrfach zugestellt werden; verwende diesen Header, um Duplikate zu ignorieren.

Antworte innerhalb von 5 Sekunden mit einem beliebigen 2xx-Status. Andernfalls versucht Flatkey es noch zweimal, nach 2 und nach 8 Sekunden, und gibt dann auf. Weiterleitungen werden nicht verfolgt. Callbacks sind nicht signiert. Prüfe ein Ergebnis daher durch Abfragen der Aufgabe, bevor du darauf reagierst, und nutze die Abfrage weiterhin als maßgebliche Quelle, falls ein Callback verloren geht.

Video herunterladen

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

curl -L "https://router.flatkey.ai/v1/videos/task_3f9a00000000000000000000000000e2/content" \
  -o output.mp4

Der Content-Endpunkt streamt video/mp4-Daten oder video/quicktime, wenn die Aufgabe output_format: "mov" verwendet hat. Er erfordert kein Bearer-Token und kann direkt als <video>-Quelle verwendet werden.

Der Content-Endpunkt funktioniert nur nach Abschluss der Aufgabe und ist nach Client-IP ratenbegrenzt. Behandle die URL als vertraulich, da jeder mit Zugriff darauf das Video herunterladen kann.

Fehler

Fehler zur Anfragezeit verwenden den Standard-Fehlerrahmen von Flatkey:

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Szenario	Verhalten
Leerer `content`	Die Anfrage wird abgelehnt. Füge nicht leeren Text, ein Bild oder ein Video ein.
Nicht verfügbares Modell	Das angeforderte `model` ist für die Route nicht aktiviert.
Unzureichendes Guthaben	Die Aufgabe wird nicht erstellt.
`priority` außerhalb von 0–9	Die Anfrage gibt `400` mit `invalid_request` zurück.
Ungültige `callback_url`	Die Anfrage gibt `400` mit `invalid_request` zurück, wenn die URL kein HTTPS verwendet, Anmeldedaten enthält, länger als 2.048 Zeichen ist oder auf eine private oder lokale Adresse verweist.
`duration: -1` außerhalb einer Videobearbeitung mit `seedance-2.5`	Die Anfrage gibt `400` mit `video_price_not_configured` zurück.
Ungültige Eingabe für das Modell	Die Anfrage gibt `400` mit `fail_to_fetch_task` zurück, oder bei Anfragen mit `asset://`-Referenzen schlägt die Aufgabe mit `task preparation failed` fehl. Prüfe Auflösung, Dauer, Inhaltsgrenzen und die oben beschriebenen Regeln für Eingabemodi. Dir wird nichts berechnet.
Vorübergehender Dienstausfall	Wiederhole den Versuch später gemäß deiner normalen Backoff-Strategie.

End-to-End-Beispiel

Dieses Beispiel erstellt eine Aufgabe, ruft ihren Status alle fünf Sekunden ab und lädt das fertige Video herunter. Es erfordert 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"

Überblick

Endpunkte

Seedance Videogenerierung — POST /v1/videos

Endpunkt

Anfrage

Header

Body-Parameter

`content`-Elemente

Videobearbeitung

Entwurfsmodus

Beispielanfragen

Eingabe mit erstem und letztem Frame

Multimodale Referenz

Antwort

Antwortfelder

Aufgabenstatus abrufen

Statuswerte

Aufgaben-Callbacks

Video herunterladen

Fehler

End-to-End-Beispiel

​Endpunkt

​Anfrage

​Header

​Body-Parameter

​content-Elemente

​Videobearbeitung

​Entwurfsmodus

​Beispielanfragen

​Eingabe mit erstem und letztem Frame

​Multimodale Referenz

​Antwort

​Antwortfelder

​Aufgabenstatus abrufen

​Statuswerte

​Aufgaben-Callbacks

​Video herunterladen

​Fehler

​End-to-End-Beispiel

Endpunkt

Anfrage

Header

Body-Parameter

`content`-Elemente

Videobearbeitung

Entwurfsmodus

Beispielanfragen

Eingabe mit erstem und letztem Frame

Multimodale Referenz

Antwort

Antwortfelder

Aufgabenstatus abrufen

Statuswerte

Aufgaben-Callbacks

Video herunterladen

Fehler

End-to-End-Beispiel