
Die Seedance 2.5 Flash API ist die schnellere, günstigere Stufe der Seedance 2.5 API und auf PoYo eine einzige Modell-ID: seedance-2.5-flash. ByteDance hat sie am 12. November 2026 veröffentlicht; die Seedance 2.5 Flash Modellseite bietet den Playground und die aktuellen Preise. Dieser Leitfaden führt Sie von einer ersten cURL-Anfrage zu einer produktionsreifen Schleife in Python und verwendet das Schema aus der Seedance 2.5 Flash API-Dokumentation, Stand 16. November 2026.
Die Seedance 2.5 Flash API im Überblick
| Punkt | Wert |
|---|---|
| Submit-Endpunkt | POST https://api.poyo.ai/api/generate/submit |
| Status-Endpunkt | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Auth-Header | Authorization: Bearer $POYO_API_KEY |
| Modell-ID | seedance-2.5-flash (der Seiten-Slug seedance-2-5-flash ist keine Modell-ID) |
| Pflichtfelder | prompt, duration |
| Dauer | Ganze Sekunden, 4–30 |
| Auflösung | 480p oder 720p, Standard 720p |
| Seitenverhältnis | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, Standard auto |
| Audio | generate_audio, Standard true |
| Auslieferung | Asynchroner Task: Status abfragen oder callback_url setzen |
Ihre erste Anfrage an die Seedance 2.5 API mit cURL
Exportieren Sie Ihren Schlüssel als POYO_API_KEY und bewahren Sie ihn auf dem Server auf, nie im Browser-Code. Dies ist eine fünfsekündige Text-zu-Video-Anfrage in 480p, ein günstiger erster Test für 92,5 Credits:
curl --fail-with-body https://api.poyo.ai/api/generate/submit \
-H "Authorization: Bearer $POYO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot, gentle water sounds, no speech, no subtitles.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}'
Eine erfolgreiche Übermittlung liefert code: 200 und ein data-Objekt mit task_id, status (direkt nach der Übermittlung immer not_started) und created_time. Das ist eine Empfangsbestätigung, kein Video. Speichern Sie die task_id und fragen Sie sie dann ab:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Die Status durchlaufen not_started, running, finished und failed. Ist der Task finished, steht die Video-URL in data.files[].file_url mit file_type: "video"; bei failed lesen Sie data.error_message. Generierte Dateien bleiben 3 Tage lang abrufbar, kopieren Sie sie also in Ihren eigenen Speicher.
Python: übermitteln und mit fester Deadline abfragen
Die Status-Dokumentation empfiehlt, alle 2–5 Sekunden abzufragen, bei 429 und 5xx die Wartezeit zu erhöhen und immer ein Timeout zu setzen. Die Schleife unten tut alle drei Dinge und übermittelt bei einem Timeout nie erneut, denn eine zweite Übermittlung ist ein zweiter kostenpflichtiger Task.
import os
import time
import requests
BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]
def checked(response):
try:
body = response.json()
except ValueError:
response.raise_for_status()
raise
if body.get("code") != 200:
err = body.get("error") or {}
raise RuntimeError(
f"PoYo {body.get('code')} {err.get('type')}: "
f"{err.get('message') or body.get('detail')}"
)
return body["data"]
task = checked(session.post(BASE + "/api/generate/submit", json={
"model": "seedance-2.5-flash",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "480p",
"aspect_ratio": "16:9",
},
}, timeout=60))
task_id = task["task_id"]
print("Saved task:", task_id, flush=True)
deadline = time.monotonic() + 15 * 60
backoff = 5
while time.monotonic() < deadline:
r = session.get(f"{BASE}/api/generate/status/{task_id}", timeout=60)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(backoff)
backoff = min(backoff * 2, 60)
continue
data = checked(r)
if data["status"] == "failed":
raise RuntimeError(data.get("error_message") or "Generation failed")
if data["status"] == "finished":
videos = [f["file_url"] for f in data.get("files", [])
if f.get("file_type") == "video"]
print(videos[0], "credits:", data.get("credits_amount"))
break
backoff = 5
time.sleep(5)
else:
raise TimeoutError("Still running; poll the saved task ID later: " + task_id)
Zur Orientierung: In PoYos Test am 16. November 2026 war ein viersekündiger Clip in 480p nach etwa zwei Minuten fertig und ein 30-sekündiger Clip in 720p nach weniger als drei Minuten, jeweils von Anfang bis Ende. Die Zeiten schwanken mit der Auslastung, die Deadline von 15 Minuten ist also eine Sicherheitsgrenze, keine Schätzung.
Polling überspringen: callback_url verwenden
Fügen Sie neben model ein callback_url auf oberster Ebene hinzu. Wenn der Task finished oder failed wird, sendet PoYo einen POST, dessen Body das Task-Datenobjekt ist (task_id, status, files, created_time, error_message), ohne den code/data-Wrapper. Laut der Dokumentation zu Video-Webhooks:
- Die URL muss öffentliches HTTPS sein, höchstens 2048 Zeichen lang, ohne private IPs.
- Antworten Sie innerhalb von 30 Sekunden mit einem 2xx; fehlgeschlagene Zustellungen werden bis zu 5-mal mit exponentiellem Backoff wiederholt.
- Prüfen Sie
X-Webhook-Signaturealsbase64(HMAC-SHA256(task_id + "." + timestamp, key)), mittimestampausX-Webhook-Timestampund dem Schlüssel vonGET /api/api-keys/webhook-secret. - Machen Sie den Handler idempotent. Schlagen alle Wiederholungen fehl, liefert der Status-Endpunkt weiterhin das Ergebnis.
Die drei Eingabemodi, mit JSON-Bodies
Die API wählt den Modus anhand der Medien, die Sie senden. Ein Feld mode gibt es nicht.
| Modus | Gewählt, wenn | Seitenverhältnis |
|---|---|---|
| Referenz-zu-Video | Eines von reference_image_urls, reference_video_urls, reference_audio_urls nicht leer ist | Jeder unterstützte Wert |
| Bild-zu-Video (erster/letzter Frame) | image_urls nicht leer ist | auto oder weglassen; der Output folgt dem ersten Frame |
| Text-zu-Video | Keine Medien | Jeder unterstützte Wert |
image_urls und die Referenzfelder gehören in getrennte Anfragen. Diese Bodies sind die dokumentierten Beispiele.
Text-zu-Video (30 Sekunden in 720p, mit einer zeitlich gegliederten Shot-Liste im Prompt):
{
"model": "seedance-2.5-flash",
"callback_url": "https://your-domain.com/callback",
"input": {
"prompt": "One continuous 30-second story of the same young woman in a yellow raincoat delivering a handwritten letter across a small seaside town at dawn. 0-6s: wide aerial shot of the sleepy harbor town, fishing boats rocking, soft morning light; she rides an old bicycle down a cobblestone hill. 6-12s: tracking shot beside her as she weaves past a fish market, seagulls lifting off, a vendor waves at her. 12-18s: low-angle shot as she climbs a steep stone staircase carrying the bicycle, breathing hard, the letter tucked in her pocket. 18-24s: she knocks on a blue door at the top; an elderly man opens it and she hands him the letter. 24-30s: close-up of the man reading, his eyes filling with tears; he smiles and says softly, \"She remembered.\" Camera slowly pulls back to reveal the sunrise over the sea. Natural ambient sound: waves, gulls, bicycle bell, footsteps, gentle piano music. No subtitles, no on-screen text.",
"duration": 30,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}
Erster und letzter Frame (eine URL legt den Anfang fest, eine zweite das Ende):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "Locked-off time-lapse of the red lakeside cabin: start from the summer evening in the first frame, let snow gradually cover the shore and the wooden dock as the sky darkens, and end exactly on the snowy night with the aurora in the last frame. Soft wind and crackling ice.",
"image_urls": [
"https://example.com/first-frame.jpg",
"https://example.com/last-frame.jpg"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "auto"
}
}
Referenz-zu-Video (verweisen Sie auf Dateien in der Upload-Reihenfolge als @Image1, @Video1, @Audio1):
{
"model": "seedance-2.5-flash",
"input": {
"prompt": "@Image1 is the ginger cat. It wears the yellow knitted scarf from @Image2 and is inside the bookstore from @Image3. On a rainy night the cat walks along a bookshelf, jumps down beside a reading lamp, and looks at the camera. Match the slow, cozy rhythm of @Audio1. No subtitles.",
"reference_image_urls": [
"https://example.com/cat.png",
"https://example.com/scarf.png",
"https://example.com/bookstore.png"
],
"reference_audio_urls": [
"https://example.com/rhythm.mp3"
],
"duration": 6,
"resolution": "480p",
"aspect_ratio": "16:9"
}
}
Validierungsregeln, die Sie vor dem Senden prüfen sollten
Wenn Sie diese Regeln clientseitig prüfen, sparen Sie einen Roundtrip und geben Ihren Nutzern eine klarere Meldung als ein generisches 400.
| Feld | Regel |
|---|---|
prompt | Pflicht, nicht leerer String |
duration | Pflicht, Ganzzahl, 4–30 |
resolution | Nur 480p oder 720p; 1080p erfordert seedance-2.5 |
aspect_ratio | Einer der sieben Werte; bei image_urls auto verwenden oder weglassen |
image_urls | 1–2 URLs (erster, dann letzter Frame); JPEG, PNG oder WebP, je bis zu 30 MB; nicht mit Referenzfeldern kombinierbar |
reference_image_urls | Bis zu 10; JPEG, PNG oder WebP, je bis zu 30 MB |
reference_video_urls | Bis zu 5; MP4 oder MOV, je 2–30 s und bis zu 200 MB; Gesamtlänge höchstens 30 s |
reference_audio_urls | Bis zu 5; MP3 oder WAV, je 2–30 s und bis zu 15 MB; Gesamtlänge höchstens 30 s; erfordert ein Referenzbild oder -video |
| Alle Medien-URLs | Öffentliches HTTP oder HTTPS, direkt herunterladbar (keine Login-Seiten oder ablaufenden Vorschauen) |
Die Gesamtdauer der Referenzen wird bei der Übermittlung des Tasks geprüft. Das Schema setzt außerdem additionalProperties: false auf input, senden Sie also keine Felder aus den APIs anderer Anbieter wie seed oder negative_prompt.
Fehler, die Sie behandeln sollten
Lesen Sie immer das Feld code im Body: Manche Validierungsfehler des Submit-Endpunkts kommen mit HTTP 200 und "code": 400 zurück. Die Fehlercode-Referenz listet diese auf:
| Code | Typ | Was zu tun ist |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Anfrage oder Medien korrigieren; nicht unverändert wiederholen |
401 | authentication_error | Bearer-Header prüfen und ob der Schlüssel noch existiert |
402 | insufficient_credits_error | Aufladen, dann erneut übermitteln |
429 | Ratenlimit | Wartezeit erhöhen (1 s, 2 s, 4 s...), bevor Sie erneut abfragen oder übermitteln |
500, 502, 503 | Server oder Upstream | Status-Aufruf mit Backoff wiederholen; vor einer erneuten Übermittlung den Status prüfen |
Task failed | error_message gesetzt | Task-ID loggen; fehlgeschlagene Tasks melden credits_amount: 0 |
So wird die erste Rechnung berechnet
Ohne Referenzvideos sind die Kosten die Output-Sekunden mal der Sekundentarif: 18,5 Credits ($0.0925) bei 480p und 41 Credits ($0.205) bei 720p, mit 1 Credit = $0.005. Generiertes Audio kostet nichts extra.
| Anfrage oben | Abgerechnete Sekunden | Credits | USD |
|---|---|---|---|
| cURL-Test, 5 s 480p | 5 | 92.5 | $0.4625 |
| Text-zu-Video, 30 s 720p | 30 | 1,230 | $6.15 |
| Erster/letzter Frame, 5 s 720p | 5 | 205 | $1.025 |
| Referenzbilder + Audio, 6 s 480p | 6 | 111 | $0.555 |
Sobald Sie reference_video_urls hinzufügen, gilt der niedrigere Tarif mit Video (11,5 Credits bei 480p, 25,5 bei 720p) für die abgerechneten Sekunden: Output-Dauer plus die Länge jedes Referenzvideos, abgerundet auf ganze Sekunden. Die Aufschlüsselung der Seedance 2.5 API Preise rechnet diese Fälle durch. Die Kosten eines abgeschlossenen Tasks erscheinen als credits_amount in der Status-Antwort.
Für 1080p zu Seedance 2.5 wechseln
Die Anfragefelder sind dieselben, ein Job lässt sich also durch Ändern der Modell-ID von Flash auf das Standardmodell Seedance 2.5 verlagern:
{
"model": "seedance-2.5",
"input": {
"prompt": "A paper boat drifts under a stone bridge at sunrise. Slow tracking shot.",
"duration": 5,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
Zwei Details: Die Dokumentation zu seedance-2.5 führt resolution als Pflichtfeld, senden Sie es also immer mit, und das Standardmodell erlaubt bis zu 30 Bild-, 10 Video- und 10 Audio-Referenzen. Bei 1080p kostet es 114 Credits ($0.57) pro Sekunde. Für die Routing-Entscheidung lesen Sie Seedance 2.5 Flash vs. Seedance 2.5; wie Seedance 2.5 im Vergleich zu einem anderen Anbieter abschneidet, zeigt Kling 4.0 vs. Seedance 2.5.
Häufig gestellte Fragen
Wie lautet die Modell-ID der Seedance 2.5 Flash API? seedance-2.5-flash, mit Punkten. Das mit Bindestrichen geschriebene seedance-2-5-flash ist nur der Slug der Modellseite.
Unterstützt die Seedance 2.5 Flash API 1080p? Nein. Sie akzeptiert 480p und 720p. Senden Sie für natives 1080p denselben Body mit "model": "seedance-2.5" und "resolution": "1080p".
Wie schalte ich das Audio in der Seedance 2.5 API ab? Setzen Sie "generate_audio": false für einen stummen Clip, oder lassen Sie Audio an und entfernen Sie einzelne Ebenen im Prompt, etwa „no background music“.
Kann ich erste Frames und Referenzbilder in einer einzigen Seedance 2.5 Flash-Anfrage verwenden? Nein. image_urls und die reference_*-Felder müssen in getrennten Anfragen gesendet werden.
Wie lange dauert ein Task der Seedance 2.5 Flash API? In PoYos Test vom 16. November 2026 etwa zwei Minuten für 4 Sekunden in 480p und unter drei Minuten für 30 Sekunden in 720p, von Anfang bis Ende. Fragen Sie den Status ab oder verwenden Sie einen Callback, statt eine Anfrage offen zu halten.
Wird mir ein fehlgeschlagener Seedance 2.5 Flash-Task berechnet? Nein. Fehlgeschlagene Tasks werden nicht berechnet, und ihr Status zeigt credits_amount: 0.