Seedance 2.5

Seedance 2.5 è il modello di generazione video più recente di ByteDance (Dreamina Seedance 2.5). Invia il corpo dell'attività ufficiale ModelArk a POST /v1/videos/generations, conserva l'identificativo dell'attività restituito e leggi il video finito da GET /v1/tasks/{id}. Immagini, video e audio vanno in content come URL.

ID modello

Consulta la pagina del modello per i prezzi attuali.

Esempio rapido

curl https://api.seedrouter.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

Endpoint

POST https://api.seedrouter.ai/v1/videos/generations

Il corpo è il corpo della richiesta ufficiale ModelArk «crea un'attività di generazione video»; questo è lo stesso endpoint che usano tutti i modelli video di SeedRouter. La risposta è la nuova attività (id, status: "processing"), non il video finito. Tieni le chiavi API nel codice lato server.

Parametri

Elementi di content

I campi sconosciuti vengono rifiutati. Non supportati: seed, callback_url (interroga invece l'attività), tools e i parametri frames e camera_fixed esclusivi di 1.x. Le attività non possono essere annullate né eliminate.

Modalità

La modalità dipende dagli elementi di content; non esiste un parametro di modalità.

Le modalità con primo fotogramma non possono essere combinate con elementi di riferimento. Con più immagini o con altri media, ogni immagine richiede un role.

Esempio con riferimenti

curl https://api.seedrouter.ai/v1/videos/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

Sostituisci gli URL di esempio con file tuoi accessibili.

Input multimediali

Questa API accetta solo riferimenti tramite URL. Non sono accettati base64, URL data:, identificativi asset:// e caricamenti multipart. Il Playground carica i file selezionati nello storage prima di inviarne gli URL.

I media devono essere URL HTTP(S) pubblici e rispettare i limiti ufficiali del modello:

Il modello non supporta immagini e video di riferimento che contengono volti umani reali.

I media vengono controllati all'avvio dell'attività, prima di qualsiasi generazione. Un'attività i cui media violano uno di questi limiti termina come failed con invalid_request_error e un messaggio che indica la regola, ad esempio The request was rejected: content reference videos must total at most 15 seconds., e non viene addebitata. Un file che in quel momento non può essere letto viene passato al modello, che lo accetta o lo rifiuta; in entrambi i casi un'attività fallita non viene addebitata.

Fattori di costo

Consulta la sezione prezzi del modello per le tariffe correnti. Seedance 2.5 fattura i token video, l'unità ufficiale:

video tokens = (output seconds + reference video seconds) × width × height × 24 / 1024

La tariffa per milione di token dipende dalla risoluzione di output e dalla presenza di un video di riferimento nella richiesta; una richiesta con video di riferimento applica una tariffa più bassa a tutti i suoi token. Gli input di testo, immagine e audio non vengono fatturati. In 16:9, un secondo corrisponde a 9.607,5 token a 480p (854×480), 21.600 a 720p, 48.600 a 1080p.

Le richieste con video di riferimento hanno anche una soglia minima di token. Per le stime, usa nella formula almeno ceil(output seconds × 2 / 3) secondi di riferimento, anche quando i video di riferimento originali sono più brevi. Questo vale sia per le attività di bozza sia per quelle del video finale; la clip della bozza non diventa un video di riferimento. L’addebito effettivo si basa sull’utilizzo riportato dall’attività completata.

L'addebito segue i token dichiarati dal video finito (output.usage.completion_tokens), quindi duration: -1 viene fatturato sulla durata effettivamente generata. Le clip renderizzate durano leggermente più di quanto richiesto: una richiesta di 5 secondi a 720p in 16:9 renderizza 121 fotogrammi e dichiara 108.900 token anziché 108.000. Gli addebiti definitivi sono nello storico di utilizzo del tuo account. Le attività fallite non vengono addebitate.

Schema di output

L'invio restituisce la nuova attività:

{"id": "task_...", "model": "dreamina-seedance-2-5", "status": "processing", "created_at": 1790321515}

Recuperare l'attività

curl https://api.seedrouter.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Interroga ogni 10–20 secondi finché status non diventa completed o failed. Un timeout di rete durante il polling non significa che la generazione sia fallita: conserva l'identificativo dell'attività e riprendi il controllo. Non creare un'altra attività per verificare l'avanzamento.

Esempio di polling completo

Esegui questo dopo l'esempio di invio in Python qui sopra.

import time

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        print(task["output"]["video_url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Attività completata

{
  "id": "task_...",
  "model": "dreamina-seedance-2-5",
  "status": "completed",
  "created_at": 1790321515,
  "finished_at": 1790321652,
  "output": {
    "video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4",
    "last_frame_url": "https://static.seedrouter.ai/media/tasks/task_example/last_frame/0.jpg",
    "content": {
      "video_url": "https://static.seedrouter.ai/media/tasks/task_example/0.mp4",
      "last_frame_url": "https://static.seedrouter.ai/media/tasks/task_example/last_frame/0.jpg"
    },
    "usage": {"completion_tokens": 108900, "total_tokens": 108900},
    "seed": 42,
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "framespersecond": 24,
    "generate_audio": true,
    "draft": false,
    "output_format": "mp4",
    "service_tier": "default",
    "execution_expires_after": 172800,
    "priority": 0
  }
}

Gli URL dei video sono ospitati sul nostro storage. Salva il file nel tuo storage se ti serve una copia duratura.

Errori

Le richieste rifiutate prima della creazione di un'attività restituiscono un errore HTTP con un oggetto error e non vengono addebitate. Un'attività che fallisce dopo l'accettazione restituisce HTTP 200 all'interrogazione, con status: "failed" e un oggetto error. L'output bloccato dal filtro dei contenuti fallisce con content_policy_violation; un'attività che supera execution_expires_after fallisce con task_expired.

Vedi il catalogo errori comune per codici, stati HTTP e indicazioni sui tentativi.

{
  "id": "task_...",
  "model": "dreamina-seedance-2-5",
  "status": "failed",
  "error": {
    "code": 60001,
    "message": "The request was rejected by the content policy. Please revise the prompt or input images."
  }
}

Se è l'invio stesso ad andare in timeout, controlla il tuo storico delle attività prima di inviare di nuovo: la prima richiesta potrebbe essere già stata accettata.

Suggerimenti

• Descrivi il soggetto, l'azione, il movimento di camera e l'illuminazione con frasi complete.
• Fai le bozze a 480p con una duration breve, poi renderizza la versione scelta a una risoluzione più alta.
• Concatena le inquadrature con return_last_frame: usa il fotogramma restituito come first_frame dell'attività successiva.
• Per modificare un filmato, imposta omni_reference_task_type su edit e descrivi solo ciò che deve cambiare.

Correlati

• Playground e prezzi di Seedance 2.5
• Scarica l'OpenAPI
• Markdown copiabile

Anteprima in bozza e video finale

Imposta draft: true per generare un’anteprima a 480p. Le altre risoluzioni non sono valide in modalità bozza. Il calcolo dell’utilizzo dei token e il prezzo unitario sono gli stessi della generazione standard a 480p.

{
  "model": "dreamina-seedance-2-5",
  "content": [{ "type": "text", "text": "A fox walks through a sunny garden." }],
  "draft": true,
  "resolution": "480p",
  "duration": 4,
  "ratio": "16:9"
}

Interroga l’ID dell’attività SeedRouter restituito finché status non è completed e output.draft non è true. Entro 7 giorni dalla creazione della bozza, invia una richiesta separata con quell’ID:

{
  "model": "dreamina-seedance-2-5",
  "content": [{ "type": "draft_task", "draft_task": { "id": "task_YOUR_DRAFT_ID" } }],
  "resolution": "1080p"
}

La bozza deve appartenere al tuo account, essere completata e usare lo stesso modello. content deve contenere un solo elemento draft_task. Imposta esplicitamente resolution su 1080p; ometti draft oppure impostalo su false. Non inviare di nuovo duration, ratio, seed, generate_audio, omni_reference_task_type, testo o contenuti multimediali, nemmeno con gli stessi valori. Queste impostazioni vengono ereditate dalla bozza.

Per la nuova attività puoi impostare watermark, return_last_frame, output_format, execution_expires_after, priority, safety_identifier e service_tier: "default". Le opzioni di output omesse usano i rispettivi valori predefiniti. content_filter viene ereditato e non può essere modificato. Un video finale generato con successo restituisce un nuovo ID attività, output.draft: false e output.draft_task_id contenente l’ID della tua bozza SeedRouter originale. Prima della scadenza, una stessa bozza può essere usata per più generazioni finali separate.

La bozza e il video finale vengono addebitati indipendentemente. Il video finale usa la tariffa 1080p per la categoria di input della bozza originale: se la bozza usava un video di riferimento, anche il video finale usa la tariffa con video di riferimento e include la durata del video di riferimento originale nell’utilizzo dei token. La clip della bozza non viene conteggiata come video di input aggiuntivo. Ogni attività usa il prezzo in vigore al momento dell’invio. Le richieste non riuscite non vengono addebitate.