how-tos

Seedance 2.5 API-guide: kall Seedance 2.5 Flash med cURL og Python

Poyo.ai Team
10 min read
Share:

Et sykkelbud som kappløper med et klokketårn ved daggry, en redaksjonell illustrasjon for Seedance 2.5 Flash API-guiden

Seedance 2.5 Flash API er det raskere og rimeligere nivået av Seedance 2.5 API, og på PoYo er det én modell-ID: seedance-2.5-flash. ByteDance lanserte det 12. november 2026; Seedance 2.5 Flash-modellsiden har playground og gjeldende priser. Denne guiden tar deg fra en første cURL-forespørsel til en produksjonsløkke i Python, med skjemaet i Seedance 2.5 Flash API-dokumentasjonen slik det var 16. november 2026.

Seedance 2.5 Flash API i korte trekk

PunktVerdi
InnsendingsendepunktPOST https://api.poyo.ai/api/generate/submit
StatusendepunktGET https://api.poyo.ai/api/generate/status/{task_id}
AutentiseringsheaderAuthorization: Bearer $POYO_API_KEY
Modell-IDseedance-2.5-flash (sidens slug seedance-2-5-flash er ikke en modell-ID)
Påkrevde feltprompt, duration
VarighetHele sekunder, 4–30
Oppløsning480p eller 720p, standard 720p
Sideforholdauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, standard auto
Lydgenerate_audio, standard true
LeveringAsynkron oppgave: poll status eller sett callback_url

Din første Seedance 2.5 API-forespørsel med cURL

Eksporter nøkkelen din som POYO_API_KEY, og hold den på serveren, aldri i nettleserkode. Dette er en tekst-til-video-forespørsel på 5 sekunder i 480p, en rimelig første test til 92,5 kreditter:

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

En vellykket innsending returnerer code: 200 og et data-objekt med task_id, status (alltid not_started rett etter innsending) og created_time. Det er en kvittering, ikke en video. Ta vare på task_id, og spør deretter etter den:

curl --fail-with-body \
  https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Statusene går gjennom not_started, running, finished og failed. Når oppgaven er finished, ligger video-URL-en i data.files[].file_url med file_type: "video"; ved failed leser du data.error_message. Genererte filer er tilgjengelige i 3 dager, så kopier dem til din egen lagring.

Python: send inn og poll med en fast frist

Statusdokumentasjonen anbefaler å polle hvert 2.–5. sekund, trappe ned ved 429 og 5xx og alltid sette en timeout. Løkken nedenfor gjør alle tre og sender aldri inn på nytt ved timeout, fordi en ny innsending er en ny oppgave som faktureres.

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)

Til orientering: i PoYos test 16. november 2026 ble et klipp på 4 sekunder i 480p ferdig på omtrent to minutter og et klipp på 30 sekunder i 720p på under tre minutter, fra start til slutt. Tidene varierer med belastningen, så fristen på 15 minutter er en sikkerhetsgrense, ikke et anslag.

Hopp over polling: bruk callback_url

Legg til en callback_url på toppnivå ved siden av model. Når oppgaven blir finished eller failed, sender PoYo en POST der brødteksten er oppgavens dataobjekt (task_id, status, files, created_time, error_message) uten code/data-innpakningen. Ifølge dokumentasjonen for video-webhooks:

  • URL-en må være offentlig HTTPS, maks. 2048 tegn, uten private IP-adresser.
  • Svar med en 2xx innen 30 sekunder; mislykkede leveringer forsøkes på nytt opptil 5 ganger med eksponentiell backoff.
  • Verifiser X-Webhook-Signature som base64(HMAC-SHA256(task_id + "." + timestamp, key)), med timestamp fra X-Webhook-Timestamp og nøkkelen fra GET /api/api-keys/webhook-secret.
  • Gjør handleren idempotent. Hvis alle nye forsøk feiler, har statusendepunktet fortsatt resultatet.

De tre inputmodusene, med JSON-brødtekster

API-et velger modus ut fra mediene du sender. Det finnes ikke noe mode-felt.

ModusVelges nårSideforhold
Referanse-til-videoEtt av reference_image_urls, reference_video_urls, reference_audio_urls ikke er tomtAlle støttede verdier
Bilde-til-video (første/siste bilderute)image_urls ikke er tomtauto eller utelatt; outputen følger første bilderute
Tekst-til-videoIngen medierAlle støttede verdier

image_urls og referansefeltene sendes i separate forespørsler. Disse brødtekstene er de dokumenterte eksemplene.

Tekst-til-video (30 sekunder i 720p, med en tidsinndelt opptaksliste i prompten):

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

Første og siste bilderute (én URL låser åpningen; en annen låser slutten):

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

Referanse-til-video (henvis til filer i opplastingsrekkefølge som @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"
  }
}

Valideringsregler du bør håndheve før innsending

Å sjekke disse på klientsiden sparer en rundtur og gir brukerne dine en tydeligere melding enn en generisk 400.

FeltRegel
promptPåkrevd, ikke-tom streng
durationPåkrevd heltall, 4–30
resolutionBare 480p eller 720p; 1080p krever seedance-2.5
aspect_ratioEn av de sju verdiene; bruk auto eller utelat det med image_urls
image_urls1–2 URL-er (første, deretter siste bilderute); JPEG, PNG eller WebP, opptil 30 MB hver; kombineres ikke med referansefelt
reference_image_urlsOpptil 10; JPEG, PNG eller WebP, opptil 30 MB hver
reference_video_urlsOpptil 5; MP4 eller MOV, 2–30 s og opptil 200 MB hver; samlet lengde maks. 30 s
reference_audio_urlsOpptil 5; MP3 eller WAV, 2–30 s og opptil 15 MB hver; samlet lengde maks. 30 s; krever et referansebilde eller en referansevideo
Alle medie-URL-erOffentlig HTTP eller HTTPS, direkte nedlastbar (ingen innloggingssider eller forhåndsvisninger som utløper)

De samlede referansevarighetene sjekkes når oppgaven sendes inn. Skjemaet setter også additionalProperties: false på input, så ikke send felt fra andre leverandørers API-er, som seed eller negative_prompt.

Feil som er verdt å håndtere

Les alltid feltet code i brødteksten: noen valideringsfeil fra innsendingsendepunktet kommer tilbake med HTTP 200 og "code": 400. Oversikten over feilkoder lister opp disse:

KodeTypeHva du gjør
400validation_error, file_format_error, content_moderation_errorRett forespørselen eller mediet; ikke prøv igjen uendret
401authentication_errorSjekk Bearer-headeren og at nøkkelen fortsatt finnes
402insufficient_credits_errorFyll på, og send deretter inn på nytt
429Rate limitVent med økende intervall (1 s, 2 s, 4 s...) før du poller eller sender inn igjen
500, 502, 503Server eller upstreamPrøv statuskallet igjen med backoff; sjekk status før du sender inn på nytt
Oppgave failederror_message er sattLogg oppgave-ID-en; mislykkede oppgaver viser credits_amount: 0

Slik beregnes den første regningen

Uten referansevideoer er kostnaden outputsekunder ganger satsen per sekund: 18,5 kreditter ($0.0925) i 480p, 41 kreditter ($0.205) i 720p, med 1 kreditt = $0.005. Generert lyd koster ikke noe ekstra.

Forespørsel overFakturerte sekunderKreditterUSD
cURL-test, 5 s 480p592.5$0.4625
Tekst-til-video, 30 s 720p301,230$6.15
Første/siste bilderute, 5 s 720p5205$1.025
Referansebilder + lyd, 6 s 480p6111$0.555

Legger du til reference_video_urls, går prisen over til den lavere satsen med video (11,5 kreditter i 480p, 25,5 i 720p), som brukes på fakturerte sekunder: outputvarighet pluss lengden på hver referansevideo rundet ned til hele sekunder. Prisoversikten for Seedance 2.5 API regner gjennom disse tilfellene. Belastningen for en ferdig oppgave vises som credits_amount i statussvaret.

Bytt til Seedance 2.5 for 1080p

Forespørselsfeltene er de samme, så å flytte en jobb fra Flash til standardmodellen Seedance 2.5 er en endring av modell-ID-en:

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

To detaljer: dokumentasjonen for seedance-2.5 oppgir resolution som påkrevd, så send det alltid, og standardmodellen tillater opptil 30 bilder, 10 videoer og 10 lydreferanser. I 1080p koster den 114 kreditter ($0.57) per sekund. For rutingbeslutningen, se Seedance 2.5 Flash vs Seedance 2.5; for hvordan Seedance 2.5 står seg mot en annen leverandør, se Kling 4.0 vs Seedance 2.5.

Ofte stilte spørsmål

Hva er modell-ID-en for Seedance 2.5 Flash API? seedance-2.5-flash, med punktum. Varianten med bindestreker, seedance-2-5-flash, er bare modellsidens slug.

Støtter Seedance 2.5 Flash API 1080p? Nei. Den godtar 480p og 720p. Send samme brødtekst med "model": "seedance-2.5" og "resolution": "1080p" for native 1080p.

Hvordan slår jeg av lyd i Seedance 2.5 API? Sett "generate_audio": false for et klipp uten lyd, eller behold lyden og fjern enkeltlag i prompten, for eksempel "no background music".

Kan jeg bruke første bilderuter og referansebilder i samme Seedance 2.5 Flash-forespørsel? Nei. image_urls og reference_*-feltene må sendes i separate forespørsler.

Hvor lang tid tar en oppgave i Seedance 2.5 Flash API? I PoYos test 16. november 2026 omtrent to minutter for 4 sekunder i 480p og under tre minutter for 30 sekunder i 720p, fra start til slutt. Poll eller bruk en callback i stedet for å holde en forespørsel åpen.

Blir jeg belastet hvis en Seedance 2.5 Flash-oppgave feiler? Nei. Mislykkede oppgaver faktureres ikke, og statusen deres viser credits_amount: 0.

Share: