API di Seedance 2.5: come usarla, parametri, limiti e costi in crediti

In breve: puoi usare Seedance 2.5 tramite l'API di Yovid con una sola chiave. Invia POST https://yovid.ai/v1/videos/generations con "model": "seedance-2.5" e un prompt, poi interroga GET /v1/tasks/{task_id} finché lo stato non è completed e leggi output.video_url. Le clip durano da 4 a 30 secondi e una richiesta può includere fino a 30 immagini, 10 video e 10 file audio come riferimenti. La fatturazione usa gli stessi crediti Yovid del sito, e i crediti vengono scalati solo quando un task va a buon fine.

Indice

1. Da dove arriva l'accesso API a Seedance 2.5
2. Avvio rapido in quattro passaggi
3. Parametri della richiesta
4. Come l'API sceglie la modalità di generazione
5. Limiti per riferimenti e media
6. Quanto costa una richiesta
7. Errori, retry e limiti di frequenza
8. Un esempio completo in Python
9. Domande frequenti

Da dove arriva l'accesso API a Seedance 2.5

Seedance 2.5 è un modello di ByteDance Seed. Il canale ufficiale di ByteDance per gli sviluppatori passa dalle sue piattaforme cloud: il post di lancio del 31 luglio 2026 annunciava l'accesso API tramite BytePlus ModelArk, secondo la stampa Volcano Engine ha aperto l'accesso API in Cina il 7 agosto, e la pagina di Seedance 2.5 di ByteDance rimanda al playground di BytePlus.

Yovid è una piattaforma indipendente, non affiliata a ByteDance, e offre Seedance 2.5 tramite la propria API:

• Una chiave, una fattura. La stessa chiave e gli stessi crediti valgono per Seedance 2.5, 2.0, 2.0 Fast, 2.0 Mini, 1.5 Pro e 1.0 Pro Fast.
• ID pubblici stabili. Invii seedance-2.5; Yovid tiene interni i nomi dei modelli dei fornitori, così possono cambiare senza rompere il tuo codice.
• Lo stesso account del sito. Le clip generate tramite API usano il piano e i crediti che hai già.

Il riferimento completo è nella documentazione dell'API di Yovid (in inglese); questa guida si concentra su ciò che riguarda Seedance 2.5.

Avvio rapido in quattro passaggi

1. Crea una chiave API

Apri Impostazioni → Chiavi API, dai un nome alla chiave e creala. Il segreto completo viene mostrato una sola volta: salvalo in un secret manager e caricalo sul tuo server come YOVID_API_KEY. Non inserirlo mai nel codice del browser o di un'app mobile.

2. Crea un task

curl https://yovid.ai/v1/videos/generations \
  -H "Authorization: Bearer $YOVID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A lighthouse keeper climbs a spiral staircase with a lantern, reaches the lamp room as a storm rolls in, and lights the great lamp. Wind howling, boots on iron steps.",
    "duration": 10,
    "quality": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

{
  "task_id": "vid_01JZK7R7KCYQ3T9F33A7K0J6XB",
  "status": "pending",
  "created_at": "2026-10-22T08:30:00.000Z"
}

3. Controlla lo stato del task

curl https://yovid.ai/v1/tasks/vid_01JZK7R7KCYQ3T9F33A7K0J6XB \
  -H "Authorization: Bearer $YOVID_API_KEY"

Interroga il task ogni 5-10 secondi finché lo stato è pending o processing, aumentando gradualmente l'intervallo. Quando diventa completed, l'URL del video è in output.video_url; se diventa failed, smetti di interrogare e leggi error.

4. Controlla i tuoi crediti

curl https://yovid.ai/v1/credits \
  -H "Authorization: Bearer $YOVID_API_KEY"

available è ciò che un nuovo task può usare; reserved è trattenuto per i task ancora in corso.

Parametri della richiesta

Prima di creare un task, l'API verifica ogni valore rispetto al modello e al tuo piano, e se qualcosa non è consentito restituisce un 403 o un 422 con il campo problematico in param. Se parti da un fotogramma, l'output segue le proporzioni di quell'immagine.

Come l'API sceglie la modalità di generazione

Non invii mai una modalità del fornitore. Yovid la sceglie in base ai media che alleghi:

In modalità riferimenti, richiama i file nel prompt in base al loro ordine in ciascun array: @image1, @image2, @video1, @audio1. Una richiesta con riferimenti ha questo aspetto:

{
  "model": "seedance-2.5",
  "prompt": "@image1 is the main character. @image2 is the ceramic mug she holds; keep its shape and logo. @image3 is the kitchen. She walks into the kitchen, pours coffee into the mug and turns to the window. Use @audio1 as her voice: she says, \"Finally, Saturday.\"",
  "image_urls": [
    "https://example.com/character.jpg",
    "https://example.com/mug.jpg",
    "https://example.com/kitchen.jpg"
  ],
  "audio_urls": ["https://example.com/voice-sample.mp3"],
  "duration": 12,
  "quality": "720p"
}

I riferimenti audio sono una funzione dell'API: il composer del sito accetta immagini e video, mentre l'API aggiunge fino a 10 file audio per una voce, una traccia o un ritmo.

Limiti per riferimenti e media

Dalla pagina modelli e input (in inglese) della documentazione API:

Tutti i media devono essere URL HTTPS pubblici. Yovid rifiuta localhost, indirizzi di reti private, URL con credenziali incorporate e nomi host che non riesce a risolvere. Usa URL invece di Base64; il fornitore limita il corpo di ogni richiesta a 64 MB.

Quanto costa una richiesta

L'API fattura negli stessi crediti del sito, con le stesse tariffe. Alle tariffe base dei pacchetti, Seedance 2.5 costa circa 3 crediti al secondo a 480p e circa 6,1 a 720p, quindi una clip di 10 secondi a 720p costa circa 61 crediti e una di 30 secondi circa 183. Con un abbonamento paghi meno al secondo.

• I video di riferimento vengono addebitati in base alla durata della clip di riferimento più quella dell'output, a una tariffa più bassa: circa 2,1 crediti al secondo a 480p e 4,6 a 720p.
• Disattivare content_filter moltiplica il costo per 1,1.
• Prima la prenotazione, poi l'addebito. I crediti vengono prenotati quando il task viene creato e scalati solo se viene completato; un task fallito li restituisce.
• Accesso in base al piano. Seedance 2.5 richiede un piano a pagamento o un pacchetto di crediti una tantum. Un account gratuito riceve 403 plan_upgrade_required.

Il task completato riporta quanto ha consumato in credits_used. Consulta la pagina prezzi per piani e pacchetti, e Seedance 2.5 è gratis? per il modo più economico di iniziare.

Errori, retry e limiti di frequenza

Ogni chiave consente fino a 120 richieste al minuto, e anche le interrogazioni di stato contano. L'endpoint di creazione non supporta ancora le chiavi di idempotenza, quindi non ripetere automaticamente un POST se non sai se il primo è andato a buon fine: potresti creare un secondo task e prenotare i crediti due volte. Registra ogni task_id che ricevi.

Un esempio completo in Python

import os
import time

import requests

API = "https://yovid.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['YOVID_API_KEY']}"}

create = requests.post(
    f"{API}/v1/videos/generations",
    headers=HEADERS,
    json={
        "model": "seedance-2.5",
        "prompt": (
            "0-10s: a courier in a yellow rain jacket runs out of a subway exit into a night street. "
            "10-20s: she weaves between umbrellas as a taxi brakes. "
            "20-30s: she stops at a door and knocks twice. Rain and traffic, no music."
        ),
        "duration": 30,
        "quality": "720p",
        "aspect_ratio": "16:9",
    },
    timeout=30,
)
create.raise_for_status()
task_id = create.json()["task_id"]

delay = 5
while True:
    task = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
    task.raise_for_status()
    data = task.json()
    if data["status"] == "completed":
        print(data["output"]["video_url"], data["credits_used"])
        break
    if data["status"] == "failed":
        raise RuntimeError(data["error"])
    time.sleep(delay)
    delay = min(delay * 1.5, 30)

Il prompt usa beat temporizzati, il modo più affidabile per riempire una clip di 30 secondi. La guida ai prompt di Seedance 2.5 contiene 13 prompt che puoi inviare così come sono, e i confronti con Kling 3.0, Veo 3.1 e Seedance 2.0 ti aiutano a scegliere quale ID di modello chiamare.

Domande frequenti

Esiste un'API ufficiale di Seedance 2.5?

ByteDance offre Seedance 2.5 agli sviluppatori tramite le sue piattaforme cloud, Volcano Engine e BytePlus. L'API di Yovid è un'alternativa indipendente: una chiave e un saldo crediti per Seedance 2.5 e gli altri modelli Seedance.

Qual è l'ID del modello Seedance 2.5 su Yovid?

seedance-2.5. Gli altri ID pubblici sono seedance-2.0, seedance-2.0-fast, seedance-2.0-mini, seedance-1.5-pro e seedance-1.0-pro-fast.

Quanto può durare un video generato con l'API di Seedance 2.5?

Da 4 a 30 secondi per task, impostati con duration.

Quali risoluzioni supporta l'API di Seedance 2.5?

La documentazione API indica 480p e 720p per seedance-2.5. Anche il tuo piano imposta un limite massimo, e se la qualità lo supera l'API restituisce un 403 prima di creare il task.

Posso inviare audio come riferimento?

Sì, fino a 10 file MP3 o WAV in audio_urls, richiamati nel prompt come @audio1, @audio2 e così via. I riferimenti audio sono disponibili solo tramite API.

Un task fallito consuma crediti?

No. I crediti vengono prenotati quando il task viene creato e scalati solo quando viene completato con successo.

Quante richieste posso fare?

Fino a 120 richieste al minuto per chiave, interrogazioni di stato incluse, più un limite di task simultanei che dipende dal tuo piano. Una risposta 429 significa: attendi e riprova con backoff.

Pronto a sviluppare? Crea una chiave in Impostazioni → Chiavi API e segui l'avvio rapido dell'API (in inglese).