how-tos

Seedance 2.5 API: guida per chiamare Seedance 2.5 Flash con cURL e Python

Poyo.ai Team
11 min read
Share:

Un fattorino in bicicletta che gareggia con una torre dell'orologio all'alba, illustrazione editoriale per la guida alla Seedance 2.5 Flash API

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

VoceValore
Endpoint di invioPOST https://api.poyo.ai/api/generate/submit
Endpoint di statoGET https://api.poyo.ai/api/generate/status/{task_id}
Header di autenticazioneAuthorization: Bearer $POYO_API_KEY
ID modelloseedance-2.5-flash (lo slug della pagina seedance-2-5-flash non è un ID modello)
Campi obbligatoriprompt, duration
DurataSecondi interi, 4–30
Risoluzione480p o 720p, predefinita 720p
Rapporto d'aspettoauto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16, predefinito auto
Audiogenerate_audio, predefinito true
ConsegnaTask 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-Signature come base64(HMAC-SHA256(task_id + "." + timestamp, key)), con timestamp preso da X-Webhook-Timestamp e la chiave ottenuta da GET /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 quandoRapporto d'aspetto
Reference-to-videoAlmeno uno tra reference_image_urls, reference_video_urls, reference_audio_urls non è vuotoQualsiasi valore supportato
Image-to-video (primo/ultimo fotogramma)image_urls non è vuotoauto oppure omesso; l'output segue il primo fotogramma
Text-to-videoNessun contenuto multimedialeQualsiasi 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.

CampoRegola
promptObbligatorio, stringa non vuota
durationIntero obbligatorio, 4–30
resolutionSolo 480p o 720p; 1080p richiede seedance-2.5
aspect_ratioUno dei sette valori; con image_urls usa auto oppure omettilo
image_urls1–2 URL (primo, poi ultimo fotogramma); JPEG, PNG o WebP, fino a 30 MB ciascuno; non combinabile con i campi di riferimento
reference_image_urlsFino a 10; JPEG, PNG o WebP, fino a 30 MB ciascuno
reference_video_urlsFino a 5; MP4 o MOV, 2–30 s e fino a 200 MB ciascuno; durata complessiva al massimo 30 s
reference_audio_urlsFino 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 mediaHTTP 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:

CodiceTipoCosa fare
400validation_error, file_format_error, content_moderation_errorCorreggi la richiesta o i media; non riprovare senza modifiche
401authentication_errorControlla l'header Bearer e che la chiave esista ancora
402insufficient_credits_errorRicarica, poi invia di nuovo
429Limite di frequenzaApplica un backoff (1 s, 2 s, 4 s...) prima di un nuovo polling o invio
500, 502, 503Server o upstreamRiprova la chiamata di stato con backoff; controlla lo stato prima di reinviare
Task failederror_message valorizzatoRegistra 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 sopraSecondi fatturatiCreditiUSD
Test cURL, 5 s 480p592.5$0.4625
Text-to-video, 30 s 720p301,230$6.15
Primo/ultimo fotogramma, 5 s 720p5205$1.025
Immagini + audio di riferimento, 6 s 480p6111$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.

Share: