how-tos

Seedance 2.5 API-Leitfaden: Seedance 2.5 Flash mit cURL und Python aufrufen

Poyo.ai Team
11 min read
Share:

Ein Fahrradkurier, der im Morgengrauen mit einer Turmuhr um die Wette fährt, eine redaktionelle Illustration für den Seedance 2.5 Flash API-Leitfaden

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

PunktWert
Submit-EndpunktPOST https://api.poyo.ai/api/generate/submit
Status-EndpunktGET https://api.poyo.ai/api/generate/status/{task_id}
Auth-HeaderAuthorization: Bearer $POYO_API_KEY
Modell-IDseedance-2.5-flash (der Seiten-Slug seedance-2-5-flash ist keine Modell-ID)
Pflichtfelderprompt, duration
DauerGanze Sekunden, 4–30
Auflösung480p oder 720p, Standard 720p
Seitenverhältnisauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, Standard auto
Audiogenerate_audio, Standard true
AuslieferungAsynchroner 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-Signature als base64(HMAC-SHA256(task_id + "." + timestamp, key)), mit timestamp aus X-Webhook-Timestamp und dem Schlüssel von GET /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.

ModusGewählt, wennSeitenverhältnis
Referenz-zu-VideoEines von reference_image_urls, reference_video_urls, reference_audio_urls nicht leer istJeder unterstützte Wert
Bild-zu-Video (erster/letzter Frame)image_urls nicht leer istauto oder weglassen; der Output folgt dem ersten Frame
Text-zu-VideoKeine MedienJeder 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.

FeldRegel
promptPflicht, nicht leerer String
durationPflicht, Ganzzahl, 4–30
resolutionNur 480p oder 720p; 1080p erfordert seedance-2.5
aspect_ratioEiner der sieben Werte; bei image_urls auto verwenden oder weglassen
image_urls1–2 URLs (erster, dann letzter Frame); JPEG, PNG oder WebP, je bis zu 30 MB; nicht mit Referenzfeldern kombinierbar
reference_image_urlsBis zu 10; JPEG, PNG oder WebP, je bis zu 30 MB
reference_video_urlsBis zu 5; MP4 oder MOV, je 2–30 s und bis zu 200 MB; Gesamtlänge höchstens 30 s
reference_audio_urlsBis 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:

CodeTypWas zu tun ist
400validation_error, file_format_error, content_moderation_errorAnfrage oder Medien korrigieren; nicht unverändert wiederholen
401authentication_errorBearer-Header prüfen und ob der Schlüssel noch existiert
402insufficient_credits_errorAufladen, dann erneut übermitteln
429RatenlimitWartezeit erhöhen (1 s, 2 s, 4 s...), bevor Sie erneut abfragen oder übermitteln
500, 502, 503Server oder UpstreamStatus-Aufruf mit Backoff wiederholen; vor einer erneuten Übermittlung den Status prüfen
Task failederror_message gesetztTask-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 obenAbgerechnete SekundenCreditsUSD
cURL-Test, 5 s 480p592.5$0.4625
Text-zu-Video, 30 s 720p301,230$6.15
Erster/letzter Frame, 5 s 720p5205$1.025
Referenzbilder + Audio, 6 s 480p6111$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.

Share: