
De Seedance 2.5 Flash API is de snellere, goedkopere tier van de Seedance 2.5 API, en op PoYo is het één model-ID: seedance-2.5-flash. ByteDance bracht hem uit op 12 november 2026; de Seedance 2.5 Flash-modelpagina heeft de playground en de actuele prijzen. Deze gids brengt je van een eerste cURL-verzoek naar een productielus in Python, met het schema uit de Seedance 2.5 Flash API-documentatie zoals gecontroleerd op 16 november 2026.
De Seedance 2.5 Flash API in één oogopslag
| Onderdeel | Waarde |
|---|---|
| Submit-endpoint | POST https://api.poyo.ai/api/generate/submit |
| Status-endpoint | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Auth-header | Authorization: Bearer $POYO_API_KEY |
| Model-ID | seedance-2.5-flash (de paginaslug seedance-2-5-flash is geen model-ID) |
| Verplichte velden | prompt, duration |
| Duur | Hele seconden, 4–30 |
| Resolutie | 480p of 720p, standaard 720p |
| Beeldverhouding | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, standaard auto |
| Audio | generate_audio, standaard true |
| Levering | Asynchrone taak: status pollen of callback_url instellen |
Je eerste verzoek aan de Seedance 2.5 API met cURL
Exporteer je sleutel als POYO_API_KEY en houd hem op de server, nooit in browsercode. Dit is een tekst-naar-videoverzoek van 5 seconden in 480p, een goedkope eerste test voor 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"
}
}'
Een geslaagde indiening geeft code: 200 terug en een data-object met task_id, status (direct na indienen altijd not_started) en created_time. Het is een ontvangstbewijs, geen video. Bewaar de task_id en vraag die daarna op:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
De statussen gaan van not_started via running naar finished of failed. Is de taak finished, dan staat de video-URL in data.files[].file_url met file_type: "video"; bij failed lees je data.error_message. Gegenereerde bestanden blijven 3 dagen beschikbaar, dus kopieer ze naar je eigen opslag.
Python: indienen en pollen met een harde deadline
De statusdocumentatie raadt aan elke 2–5 seconden te pollen, bij 429 en 5xx de wachttijd op te voeren en altijd een timeout in te stellen. De lus hieronder doet alle drie en dient bij een timeout nooit opnieuw in, want een tweede indiening is een tweede betaalde taak.
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)
Ter referentie: in de test van PoYo op 16 november 2026 was een clip van 4 seconden in 480p na ongeveer twee minuten klaar en een clip van 30 seconden in 720p in minder dan drie minuten, van begin tot eind. De tijden variëren met de belasting, dus de deadline van 15 minuten is een veiligheidsgrens, geen schatting.
Sla pollen over: gebruik callback_url
Voeg naast model een callback_url op het hoogste niveau toe. Wanneer de taak finished of failed wordt, stuurt PoYo een POST waarvan de body het taakdata-object is (task_id, status, files, created_time, error_message), zonder de code/data-wrapper. Volgens de documentatie over videowebhooks:
- De URL moet publieke HTTPS zijn, maximaal 2048 tekens, zonder privé-IP's.
- Antwoord binnen 30 seconden met een 2xx; mislukte leveringen worden tot 5 keer opnieuw geprobeerd met exponentiële backoff.
- Verifieer
X-Webhook-Signaturealsbase64(HMAC-SHA256(task_id + "." + timestamp, key)), mettimestampuitX-Webhook-Timestampen de sleutel uitGET /api/api-keys/webhook-secret. - Maak de handler idempotent. Mislukken alle nieuwe pogingen, dan heeft het status-endpoint nog steeds het resultaat.
De drie inputmodi, met JSON-bodies
De API kiest de modus op basis van de media die je meestuurt. Er is geen mode-veld.
| Modus | Gekozen als | Beeldverhouding |
|---|---|---|
| Referentie naar video | Een van reference_image_urls, reference_video_urls, reference_audio_urls niet leeg is | Elke ondersteunde waarde |
| Afbeelding naar video (eerste/laatste frame) | image_urls niet leeg is | auto of weglaten; de output volgt het eerste frame |
| Tekst naar video | Geen media | Elke ondersteunde waarde |
image_urls en de referentievelden gaan in aparte verzoeken. Deze bodies zijn de gedocumenteerde voorbeelden.
Tekst naar video (30 seconden in 720p, met een getimede shotlijst in de 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
}
}
Eerste en laatste frame (één URL legt het begin vast; een tweede het einde):
{
"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"
}
}
Referentie naar video (verwijs naar bestanden in uploadvolgorde 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"
}
}
Validatieregels om vóór het indienen te controleren
Als je deze aan de clientkant controleert, bespaar je een roundtrip en geef je je gebruikers een duidelijkere melding dan een algemene 400.
| Veld | Regel |
|---|---|
prompt | Verplicht, niet-lege string |
duration | Verplicht geheel getal, 4–30 |
resolution | Alleen 480p of 720p; voor 1080p is seedance-2.5 nodig |
aspect_ratio | Een van de zeven waarden; gebruik auto of laat het weg bij image_urls |
image_urls | 1–2 URL's (eerste, dan laatste frame); JPEG, PNG of WebP, elk tot 30 MB; niet te combineren met referentievelden |
reference_image_urls | Maximaal 10; JPEG, PNG of WebP, elk tot 30 MB |
reference_video_urls | Maximaal 5; MP4 of MOV, elk 2–30 s en tot 200 MB; samen maximaal 30 s |
reference_audio_urls | Maximaal 5; MP3 of WAV, elk 2–30 s en tot 15 MB; samen maximaal 30 s; vereist een referentieafbeelding of -video |
| Alle media-URL's | Publieke HTTP of HTTPS, direct downloadbaar (geen loginpagina's of verlopende previews) |
De gezamenlijke duur van de referenties wordt gecontroleerd wanneer de taak wordt ingediend. Het schema zet bovendien additionalProperties: false op input, dus stuur geen velden uit de API's van andere leveranciers mee, zoals seed of negative_prompt.
Fouten die je moet afhandelen
Lees altijd het veld code in de body: sommige validatiefouten van het submit-endpoint komen terug met HTTP 200 en "code": 400. De foutcodereferentie noemt deze:
| Code | Type | Wat te doen |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Verzoek of media corrigeren; niet ongewijzigd opnieuw proberen |
401 | authentication_error | De Bearer-header controleren en of de sleutel nog bestaat |
402 | insufficient_credits_error | Opwaarderen en daarna opnieuw indienen |
429 | Rate limit | Wachttijd opvoeren (1 s, 2 s, 4 s...) voordat je opnieuw pollt of indient |
500, 502, 503 | Server of upstream | De statusaanroep opnieuw proberen met backoff; de status controleren voordat je opnieuw indient |
Taak failed | error_message ingevuld | De taak-ID loggen; mislukte taken melden credits_amount: 0 |
Hoe de eerste factuur wordt berekend
Zonder referentievideo's zijn de kosten het aantal outputseconden maal het tarief per seconde: 18,5 credits ($0.0925) bij 480p, 41 credits ($0.205) bij 720p, met 1 credit = $0.005. Gegenereerde audio kost niets extra.
| Verzoek hierboven | Gefactureerde seconden | Credits | USD |
|---|---|---|---|
| cURL-test, 5 s 480p | 5 | 92.5 | $0.4625 |
| Tekst naar video, 30 s 720p | 30 | 1,230 | $6.15 |
| Eerste/laatste frame, 5 s 720p | 5 | 205 | $1.025 |
| Referentieafbeeldingen + audio, 6 s 480p | 6 | 111 | $0.555 |
Voeg je reference_video_urls toe, dan geldt het lagere tarief met video (11,5 credits bij 480p, 25,5 bij 720p) voor de gefactureerde seconden: de outputduur plus de lengte van elke referentievideo, naar beneden afgerond op hele seconden. Het overzicht van de Seedance 2.5 API-prijzen rekent die gevallen door. De kosten van een voltooide taak verschijnen als credits_amount in het statusantwoord.
Overstappen naar Seedance 2.5 voor 1080p
De verzoekvelden zijn hetzelfde, dus een job van Flash naar het standaardmodel Seedance 2.5 verplaatsen is een kwestie van de model-ID wijzigen:
{
"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"
}
}
Twee details: de documentatie van seedance-2.5 noemt resolution als verplicht, dus stuur het altijd mee, en het standaardmodel staat tot 30 afbeeldings-, 10 video- en 10 audioreferenties toe. Bij 1080p kost het 114 credits ($0.57) per seconde. Voor de routingbeslissing, zie Seedance 2.5 Flash vs. Seedance 2.5; voor hoe Seedance 2.5 zich verhoudt tot een andere leverancier, zie Kling 4.0 vs. Seedance 2.5.
Veelgestelde vragen
Wat is de model-ID van de Seedance 2.5 Flash API? seedance-2.5-flash, met punten. De variant met streepjes, seedance-2-5-flash, is alleen de slug van de modelpagina.
Ondersteunt de Seedance 2.5 Flash API 1080p? Nee. Hij accepteert 480p en 720p. Stuur dezelfde body met "model": "seedance-2.5" en "resolution": "1080p" voor native 1080p.
Hoe zet ik audio uit in de Seedance 2.5 API? Zet "generate_audio": false voor een stille clip, of laat audio aan en schrap afzonderlijke lagen in de prompt, zoals "no background music".
Kan ik eerste frames en referentieafbeeldingen in één Seedance 2.5 Flash-verzoek gebruiken? Nee. image_urls en de reference_*-velden moeten in aparte verzoeken worden verstuurd.
Hoe lang duurt een taak van de Seedance 2.5 Flash API? In de test van PoYo op 16 november 2026 ongeveer twee minuten voor 4 seconden in 480p en minder dan drie minuten voor 30 seconden in 720p, van begin tot eind. Poll of gebruik een callback in plaats van een verzoek open te houden.
Betaal ik als een Seedance 2.5 Flash-taak mislukt? Nee. Mislukte taken worden niet in rekening gebracht, en hun status toont credits_amount: 0.