how-tos

Seedance 2.5 API-gids: Seedance 2.5 Flash aanroepen met cURL en Python

Poyo.ai Team
11 min read
Share:

Een fietskoerier die bij dageraad tegen de klok van een klokkentoren racet, een redactionele illustratie voor de Seedance 2.5 Flash API-gids

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

OnderdeelWaarde
Submit-endpointPOST https://api.poyo.ai/api/generate/submit
Status-endpointGET https://api.poyo.ai/api/generate/status/{task_id}
Auth-headerAuthorization: Bearer $POYO_API_KEY
Model-IDseedance-2.5-flash (de paginaslug seedance-2-5-flash is geen model-ID)
Verplichte veldenprompt, duration
DuurHele seconden, 4–30
Resolutie480p of 720p, standaard 720p
Beeldverhoudingauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, standaard auto
Audiogenerate_audio, standaard true
LeveringAsynchrone 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-Signature als base64(HMAC-SHA256(task_id + "." + timestamp, key)), met timestamp uit X-Webhook-Timestamp en de sleutel uit GET /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.

ModusGekozen alsBeeldverhouding
Referentie naar videoEen van reference_image_urls, reference_video_urls, reference_audio_urls niet leeg isElke ondersteunde waarde
Afbeelding naar video (eerste/laatste frame)image_urls niet leeg isauto of weglaten; de output volgt het eerste frame
Tekst naar videoGeen mediaElke 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.

VeldRegel
promptVerplicht, niet-lege string
durationVerplicht geheel getal, 4–30
resolutionAlleen 480p of 720p; voor 1080p is seedance-2.5 nodig
aspect_ratioEen van de zeven waarden; gebruik auto of laat het weg bij image_urls
image_urls1–2 URL's (eerste, dan laatste frame); JPEG, PNG of WebP, elk tot 30 MB; niet te combineren met referentievelden
reference_image_urlsMaximaal 10; JPEG, PNG of WebP, elk tot 30 MB
reference_video_urlsMaximaal 5; MP4 of MOV, elk 2–30 s en tot 200 MB; samen maximaal 30 s
reference_audio_urlsMaximaal 5; MP3 of WAV, elk 2–30 s en tot 15 MB; samen maximaal 30 s; vereist een referentieafbeelding of -video
Alle media-URL'sPublieke 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:

CodeTypeWat te doen
400validation_error, file_format_error, content_moderation_errorVerzoek of media corrigeren; niet ongewijzigd opnieuw proberen
401authentication_errorDe Bearer-header controleren en of de sleutel nog bestaat
402insufficient_credits_errorOpwaarderen en daarna opnieuw indienen
429Rate limitWachttijd opvoeren (1 s, 2 s, 4 s...) voordat je opnieuw pollt of indient
500, 502, 503Server of upstreamDe statusaanroep opnieuw proberen met backoff; de status controleren voordat je opnieuw indient
Taak failederror_message ingevuldDe 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 hierbovenGefactureerde secondenCreditsUSD
cURL-test, 5 s 480p592.5$0.4625
Tekst naar video, 30 s 720p301,230$6.15
Eerste/laatste frame, 5 s 720p5205$1.025
Referentieafbeeldingen + audio, 6 s 480p6111$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.

Share: