how-tos

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

Poyo.ai Team
10 min read
Share:

Et bud på cykel, der kappes med et klokketårn ved daggry, en redaktionel illustration til Seedance 2.5 Flash API-guiden

Seedance 2.5 Flash API er det hurtigere og billigere niveau af Seedance 2.5 API, og på PoYo er det ét model-ID: seedance-2.5-flash. ByteDance udgav det den 12. november 2026; Seedance 2.5 Flash-modelsiden har playground og aktuelle priser. Denne guide fører dig fra en første cURL-anmodning til en produktionsløkke i Python med skemaet i Seedance 2.5 Flash API-dokumentationen, som kontrolleret den 16. november 2026.

Seedance 2.5 Flash API i overblik

PunktVærdi
Indsendelses-endpointPOST https://api.poyo.ai/api/generate/submit
Status-endpointGET https://api.poyo.ai/api/generate/status/{task_id}
GodkendelsesheaderAuthorization: Bearer $POYO_API_KEY
Model-IDseedance-2.5-flash (sidens slug seedance-2-5-flash er ikke et model-ID)
Påkrævede felterprompt, duration
VarighedHele sekunder, 4–30
Opløsning480p eller 720p, standard 720p
Billedformatauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, standard auto
Lydgenerate_audio, standard true
LeveringAsynkron opgave: poll status, eller sæt callback_url

Din første Seedance 2.5 API-anmodning med cURL

Eksportér din nøgle som POYO_API_KEY, og behold den på serveren, aldrig i browserkode. Dette er en tekst til video-anmodning på 5 sekunder i 480p, en billig 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 indsendelse returnerer code: 200 og et data-objekt med task_id, status (altid not_started lige efter indsendelse) og created_time. Det er en kvittering, ikke en video. Gem task_id, og forespørg den derefter:

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

Statusserne går gennem not_started, running, finished og failed. Når opgaven er finished, ligger video-URL'en i data.files[].file_url med file_type: "video"; ved failed skal du læse data.error_message. Genererede filer er tilgængelige i 3 dage, så kopiér dem til dit eget lager.

Python: indsend og poll med en fast deadline

Statusdokumentationen anbefaler at polle hvert 2.–5. sekund, at trappe ned ved 429 og 5xx og altid at sætte en timeout. Løkken nedenfor gør alle tre ting og sender aldrig igen ved timeout, fordi en anden indsendelse er en anden opgave, der skal betales for.

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 PoYo's test den 16. november 2026 blev et klip på 4 sekunder i 480p færdigt på omkring to minutter og et klip på 30 sekunder i 720p på under tre minutter, fra start til slut. Tiderne varierer med belastningen, så deadlinen på 15 minutter er en sikkerhedsgrænse, ikke et estimat.

Spring polling over: brug callback_url

Tilføj en callback_url på øverste niveau ved siden af model. Når opgaven bliver finished eller failed, sender PoYo en POST, hvis brødtekst er opgavens dataobjekt (task_id, status, files, created_time, error_message) uden code/data-indpakningen. Ifølge dokumentationen om video-webhooks:

  • URL'en skal være offentlig HTTPS, højst 2048 tegn, uden private IP-adresser.
  • Svar med en 2xx inden for 30 sekunder; mislykkede leveringer forsøges igen op til 5 gange med eksponentiel backoff.
  • Verificér X-Webhook-Signature som base64(HMAC-SHA256(task_id + "." + timestamp, key)), med timestamp fra X-Webhook-Timestamp og nøglen fra GET /api/api-keys/webhook-secret.
  • Gør handleren idempotent. Hvis alle genforsøg mislykkes, har status-endpointet stadig resultatet.

De tre inputtilstande med JSON-brødtekster

API'et vælger tilstanden ud fra de medier, du sender. Der er intet mode-felt.

TilstandVælges, nårBilledformat
Reference til videoEt af felterne reference_image_urls, reference_video_urls, reference_audio_urls ikke er tomtEnhver understøttet værdi
Billede til video (første/sidste billede)image_urls ikke er tomtauto eller udeladt; outputtet følger det første billede
Tekst til videoIngen medierEnhver understøttet værdi

image_urls og referencefelterne sendes i separate anmodninger. Disse brødtekster er de dokumenterede eksempler.

Tekst til video (30 sekunder i 720p med en tidsinddelt shotliste 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 sidste billede (én URL fastlægger starten; en anden fastlægger slutningen):

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

Reference til video (henvis til filer i uploadrækkefø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åndhæve før indsendelse

At tjekke disse på klientsiden sparer en rundtur og giver dine brugere en tydeligere besked end en generisk 400.

FeltRegel
promptPåkrævet, ikke-tom streng
durationPåkrævet heltal, 4–30
resolutionKun 480p eller 720p; 1080p kræver seedance-2.5
aspect_ratioEn af de syv værdier; brug auto, eller udelad det med image_urls
image_urls1–2 URL'er (første, derefter sidste billede); JPEG, PNG eller WebP, op til 30 MB hver; kombineres ikke med referencefelter
reference_image_urlsOp til 10; JPEG, PNG eller WebP, op til 30 MB hver
reference_video_urlsOp til 5; MP4 eller MOV, 2–30 s og op til 200 MB hver; samlet længde højst 30 s
reference_audio_urlsOp til 5; MP3 eller WAV, 2–30 s og op til 15 MB hver; samlet længde højst 30 s; kræver et referencebillede eller en referencevideo
Alle medie-URL'erOffentlig HTTP eller HTTPS, direkte downloadbar (ingen login-sider eller udløbende forhåndsvisninger)

De samlede referencevarigheder tjekkes, når opgaven indsendes. Skemaet sætter også additionalProperties: false på input, så send ikke felter fra andre leverandørers API'er, såsom seed eller negative_prompt.

Fejl, der er værd at håndtere

Læs altid feltet code i brødteksten: nogle valideringsfejl fra indsendelses-endpointet kommer tilbage med HTTP 200 og "code": 400. Fejlkodeoversigten oplister disse:

KodeTypeHvad du skal gøre
400validation_error, file_format_error, content_moderation_errorRet anmodningen eller mediet; prøv ikke igen uændret
401authentication_errorTjek Bearer-headeren, og at nøglen stadig findes
402insufficient_credits_errorFyld op, og indsend derefter igen
429Rate limitVent med stigende interval (1 s, 2 s, 4 s...), før du poller eller indsender igen
500, 502, 503Server eller upstreamPrøv statuskaldet igen med backoff; tjek status, før du indsender igen
Opgave failederror_message er satLog opgave-ID'et; mislykkede opgaver viser credits_amount: 0

Sådan beregnes den første regning

Uden referencevideoer er prisen outputsekunder gange taksten pr. sekund: 18,5 kreditter ($0.0925) i 480p, 41 kreditter ($0.205) i 720p, med 1 kredit = $0.005. Genereret lyd koster ikke ekstra.

Anmodning ovenforAfregnede sekunderKreditterUSD
cURL-test, 5 s 480p592.5$0.4625
Tekst til video, 30 s 720p301,230$6.15
Første/sidste billede, 5 s 720p5205$1.025
Referencebilleder + lyd, 6 s 480p6111$0.555

Tilføjer du nogen reference_video_urls, skiftes der til den lavere takst med video (11,5 kreditter i 480p, 25,5 i 720p), som anvendes på de afregnede sekunder: outputvarighed plus hver referencevideos længde rundet ned til hele sekunder. Prisoversigten for Seedance 2.5 API regner de tilfælde igennem. Prisen for en færdig opgave vises som credits_amount i statussvaret.

Skift til Seedance 2.5 for 1080p

Anmodningsfelterne er de samme, så at flytte et job fra Flash til standardmodellen Seedance 2.5 er en ændring af model-ID'et:

{
  "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: dokumentationen for seedance-2.5 angiver resolution som påkrævet, så send det altid, og standardmodellen tillader op til 30 billeder, 10 videoer og 10 lydreferencer. I 1080p koster den 114 kreditter ($0.57) pr. sekund. Til routingbeslutningen, se Seedance 2.5 Flash vs Seedance 2.5; for hvordan Seedance 2.5 klarer sig mod en anden leverandør, se Kling 4.0 vs Seedance 2.5.

Ofte stillede spørgsmål

Hvad er model-ID'et for Seedance 2.5 Flash API? seedance-2.5-flash, med punktummer. Varianten med bindestreger, seedance-2-5-flash, er kun modelsidens slug.

Understøtter Seedance 2.5 Flash API 1080p? Nej. Den accepterer 480p og 720p. Send den samme brødtekst med "model": "seedance-2.5" og "resolution": "1080p" for native 1080p.

Hvordan slår jeg lyd fra i Seedance 2.5 API? Sæt "generate_audio": false for et lydløst klip, eller behold lyden og fravælg enkelte lag i prompten, for eksempel "no background music".

Kan jeg bruge første billeder og referencebilleder i samme Seedance 2.5 Flash-anmodning? Nej. image_urls og reference_*-felterne skal sendes i separate anmodninger.

Hvor lang tid tager en opgave i Seedance 2.5 Flash API? I PoYo's test den 16. november 2026 omkring to minutter for 4 sekunder i 480p og under tre minutter for 30 sekunder i 720p, fra start til slut. Poll, eller brug et callback, i stedet for at holde en anmodning åben.

Betaler jeg, hvis en Seedance 2.5 Flash-opgave mislykkes? Nej. Mislykkede opgaver faktureres ikke, og deres status viser credits_amount: 0.

Share: