
La Seedance 2.5 Flash API è il livello più veloce ed economico della Seedance 2.5 API, e su PoYo corrisponde a un unico ID modello: seedance-2.5-flash. ByteDance l'ha rilasciata il 12 novembre 2026; la pagina del modello Seedance 2.5 Flash ospita il playground e i prezzi aggiornati. Questa guida ti porta da una prima richiesta cURL a un loop di produzione in Python, usando lo schema della documentazione della Seedance 2.5 Flash API verificato il 16 novembre 2026.
Seedance 2.5 Flash API in sintesi
| Voce | Valore |
|---|---|
| Endpoint di invio | POST https://api.poyo.ai/api/generate/submit |
| Endpoint di stato | GET https://api.poyo.ai/api/generate/status/{task_id} |
| Header di autenticazione | Authorization: Bearer $POYO_API_KEY |
| ID modello | seedance-2.5-flash (lo slug della pagina seedance-2-5-flash non è un ID modello) |
| Campi obbligatori | prompt, duration |
| Durata | Secondi interi, 4–30 |
| Risoluzione | 480p o 720p, predefinita 720p |
| Rapporto d'aspetto | auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, predefinito auto |
| Audio | generate_audio, predefinito true |
| Consegna | Task asincrono: polling dello stato oppure callback_url |
La tua prima richiesta alla Seedance 2.5 API con cURL
Esporta la tua chiave come POYO_API_KEY e tienila sul server, mai nel codice del browser. Questa è una richiesta text-to-video da 5 secondi a 480p, un primo test economico da 92,5 crediti:
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"
}
}'
Un invio riuscito restituisce code: 200 e un oggetto data con task_id, status (sempre not_started subito dopo l'invio) e created_time. È una ricevuta, non un video. Salva il task_id, poi interrogalo:
curl --fail-with-body \
https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Gli stati passano per not_started, running, finished e failed. Quando il task è finished, l'URL del video si trova in data.files[].file_url con file_type: "video"; in caso di failed, leggi data.error_message. I file generati restano accessibili per 3 giorni, quindi copiali nel tuo storage.
Python: invio e polling con una scadenza rigida
La documentazione sullo stato consiglia di fare polling ogni 2–5 secondi, applicare un backoff su 429 e 5xx e impostare sempre un timeout. Il loop qui sotto fa tutte e tre le cose e non reinvia mai la richiesta in caso di timeout, perché un secondo invio è un secondo task fatturabile.
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)
Come riferimento, nei test di PoYo del 16 novembre 2026 una clip da 4 secondi a 480p è stata completata in circa due minuti e una clip da 30 secondi a 720p in meno di tre minuti, end to end. I tempi variano con il carico, quindi la scadenza di 15 minuti è un limite di sicurezza, non una stima.
Evita il polling: usa callback_url
Aggiungi un callback_url di primo livello accanto a model. Quando il task diventa finished o failed, PoYo invia una POST il cui body è l'oggetto dati del task (task_id, status, files, created_time, error_message) senza il wrapper code/data. Secondo la documentazione dei webhook video:
- L'URL deve essere HTTPS pubblico, di al massimo 2048 caratteri, senza IP privati.
- Rispondi con un 2xx entro 30 secondi; le consegne non riuscite vengono ritentate fino a 5 volte con backoff esponenziale.
- Verifica
X-Webhook-Signaturecomebase64(HMAC-SHA256(task_id + "." + timestamp, key)), contimestamppreso daX-Webhook-Timestampe la chiave ottenuta daGET /api/api-keys/webhook-secret. - Rendi l'handler idempotente. Se tutti i tentativi falliscono, l'endpoint di stato ha comunque il risultato.
Le tre modalità di input, con i body JSON
L'API sceglie la modalità in base ai contenuti multimediali che invii. Non esiste un campo mode.
| Modalità | Selezionata quando | Rapporto d'aspetto |
|---|---|---|
| Reference-to-video | Almeno uno tra reference_image_urls, reference_video_urls, reference_audio_urls non è vuoto | Qualsiasi valore supportato |
| Image-to-video (primo/ultimo fotogramma) | image_urls non è vuoto | auto oppure omesso; l'output segue il primo fotogramma |
| Text-to-video | Nessun contenuto multimediale | Qualsiasi valore supportato |
image_urls e i campi di riferimento vanno in richieste separate. Questi body sono gli esempi documentati.
Text-to-video (30 secondi a 720p, con una lista di inquadrature temporizzata nel 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
}
}
Primo e ultimo fotogramma (un URL fissa l'apertura; un secondo fissa il finale):
{
"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-to-video (fai riferimento ai file in base all'ordine di caricamento come @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"
}
}
Regole di validazione da applicare prima dell'invio
Verificarle lato client fa risparmiare un round trip e offre ai tuoi utenti un messaggio più chiaro di un generico 400.
| Campo | Regola |
|---|---|
prompt | Obbligatorio, stringa non vuota |
duration | Intero obbligatorio, 4–30 |
resolution | Solo 480p o 720p; 1080p richiede seedance-2.5 |
aspect_ratio | Uno dei sette valori; con image_urls usa auto oppure omettilo |
image_urls | 1–2 URL (primo, poi ultimo fotogramma); JPEG, PNG o WebP, fino a 30 MB ciascuno; non combinabile con i campi di riferimento |
reference_image_urls | Fino a 10; JPEG, PNG o WebP, fino a 30 MB ciascuno |
reference_video_urls | Fino a 5; MP4 o MOV, 2–30 s e fino a 200 MB ciascuno; durata complessiva al massimo 30 s |
reference_audio_urls | Fino a 5; MP3 o WAV, 2–30 s e fino a 15 MB ciascuno; durata complessiva al massimo 30 s; richiede un'immagine o un video di riferimento |
| Tutti gli URL dei media | HTTP o HTTPS pubblici, scaricabili direttamente (niente pagine di login o anteprime a scadenza) |
Le durate complessive dei riferimenti vengono verificate al momento dell'invio del task. Lo schema imposta anche additionalProperties: false su input, quindi non inviare campi delle API di altri fornitori come seed o negative_prompt.
Errori da gestire
Leggi sempre il campo code nel body: alcuni errori di validazione dell'endpoint di invio arrivano con HTTP 200 e "code": 400. Il riferimento dei codici di errore elenca questi:
| Codice | Tipo | Cosa fare |
|---|---|---|
400 | validation_error, file_format_error, content_moderation_error | Correggi la richiesta o i media; non riprovare senza modifiche |
401 | authentication_error | Controlla l'header Bearer e che la chiave esista ancora |
402 | insufficient_credits_error | Ricarica, poi invia di nuovo |
429 | Limite di frequenza | Applica un backoff (1 s, 2 s, 4 s...) prima di un nuovo polling o invio |
500, 502, 503 | Server o upstream | Riprova la chiamata di stato con backoff; controlla lo stato prima di reinviare |
Task failed | error_message valorizzato | Registra il task ID; i task falliti riportano credits_amount: 0 |
Come si calcola la prima fattura
Senza video di riferimento, il costo è dato dai secondi di output per la tariffa al secondo: 18,5 crediti ($0.0925) a 480p, 41 crediti ($0.205) a 720p, con 1 credito = $0.005. L'audio generato non aggiunge nulla.
| Richiesta sopra | Secondi fatturati | Crediti | USD |
|---|---|---|---|
| Test cURL, 5 s 480p | 5 | 92.5 | $0.4625 |
| Text-to-video, 30 s 720p | 30 | 1,230 | $6.15 |
| Primo/ultimo fotogramma, 5 s 720p | 5 | 205 | $1.025 |
| Immagini + audio di riferimento, 6 s 480p | 6 | 111 | $0.555 |
Aggiungere un qualsiasi reference_video_urls fa passare alla tariffa ridotta con video (11,5 crediti a 480p, 25,5 a 720p) applicata ai secondi fatturati: durata dell'output più la durata di ciascun video di riferimento arrotondata per difetto ai secondi interi. L'analisi dei prezzi della Seedance 2.5 API esamina questi casi. L'addebito di un task completato compare come credits_amount nella risposta di stato.
Passa a Seedance 2.5 per il 1080p
I campi della richiesta sono gli stessi, quindi spostare un job da Flash al modello Seedance 2.5 standard significa cambiare l'ID modello:
{
"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"
}
}
Due dettagli: la documentazione di seedance-2.5 indica resolution come obbligatorio, quindi invialo sempre, e il modello standard consente fino a 30 immagini, 10 video e 10 audio di riferimento. A 1080p costa 114 crediti ($0.57) al secondo. Per la scelta di instradamento, vedi Seedance 2.5 Flash vs Seedance 2.5; per il confronto di Seedance 2.5 con un altro fornitore, vedi Kling 4.0 vs Seedance 2.5.
Domande frequenti
Qual è l'ID modello della Seedance 2.5 Flash API? seedance-2.5-flash, con i punti. La forma con i trattini seedance-2-5-flash è solo lo slug della pagina del modello.
La Seedance 2.5 Flash API supporta il 1080p? No. Accetta 480p e 720p. Invia lo stesso body con "model": "seedance-2.5" e "resolution": "1080p" per il 1080p nativo.
Come disattivo l'audio nella Seedance 2.5 API? Imposta "generate_audio": false per una clip muta, oppure mantieni l'audio attivo ed elimina singoli livelli nel prompt, per esempio "no background music".
Posso usare primi fotogrammi e immagini di riferimento in un'unica richiesta Seedance 2.5 Flash? No. image_urls e i campi reference_* devono essere inviati in richieste separate.
Quanto dura un task della Seedance 2.5 Flash API? Nel test di PoYo del 16 novembre 2026, circa due minuti per 4 secondi a 480p e meno di tre minuti per 30 secondi a 720p, end to end. Usa il polling o un callback invece di tenere aperta una richiesta.
Mi viene addebitato un task Seedance 2.5 Flash fallito? No. I task falliti non vengono addebitati e il loro stato mostra credits_amount: 0.