Come usare l'API Seedance: chiave, richiesta, polling e riferimenti

Per usare l'API Seedance, crea una chiave API, invia a un unico endpoint il corpo ufficiale dell'attività video di ModelArk e interroga l'attività restituita finché l'URL del video non è pronto. Gli stessi passaggi valgono per Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini e Seedance 2.5; cambiano solo il valore di model e alcuni limiti specifici del modello.

Questa guida percorre ogni passaggio con codice funzionante, poi mostra come aggiungere riferimenti, modificare una clip con Seedance 2.5 e affidare il lavoro a un agente di programmazione.

Cosa ti serve prima della prima richiesta?

1. Una chiave API. Creala nella pagina chiavi API e tienila sul tuo server. Non inserirla mai nel codice del browser.
2. Crediti. Aggiungi un saldo nella pagina di fatturazione. I crediti non scadono mai e le attività non riuscite non vengono addebitate.
3. Un ID modello. Scegline uno dalla tabella qui sotto.

Non sai quale scegliere? La guida Seedance 2.0 vs Fast vs Mini e la guida Seedance 2.5 vs 2.0 li confrontano.

export SEEDROUTER_API_KEY="your-key"

Come si invia una richiesta a Seedance?

Invia l'attività in POST a /v1/contents/generations/tasks. Il corpo è la richiesta ufficiale di ModelArk «create a video generation task» (crea un'attività di generazione video):

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "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
  }'

La risposta è un ID attività, non un video:

{"id": "task_..."}

Se chiami già ModelArk, cambia solo l'URL di base in https://api.seedrouter.ai/v1 e la chiave API. I campi sconosciuti vengono rifiutati prima di qualsiasi addebito, e lo stesso vale per un'impostazione che un modello non supporta, come 1080p su Fast o Mini.

Come si ottiene il video?

Interroga l'attività ogni 10–20 secondi finché status non diventa succeeded, failed o expired. Una clip da 5 secondi a 720p richiede di solito due o tre minuti. In Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/contents/generations/tasks",
    headers=headers,
    json={
        "model": "dreamina-seedance-2-0",
        "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,
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Un'attività riuscita contiene il video in content.video_url, i token video addebitati in usage.completion_tokens e le impostazioni effettivamente usate per il rendering, incluso il seed scelto dal modello. Il video è ospitato sul nostro storage; scaricalo nel tuo se ti serve a lungo termine.

Un timeout durante il polling non significa che il video sia fallito. Conserva l'ID dell'attività e interrogala di nuovo; inviare una nuova attività significa pagare un secondo video. Non esiste un URL di callback, quindi il polling è il modo per ottenere il risultato, e un'attività inviata non può essere annullata.

Come si aggiungono immagini, video e audio?

Aggiungi elementi a content, ciascuno con un URL pubblico e un role:

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "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
  }'

Seedance 2.0 e le sue versioni Fast e Mini accettano fino a 9 immagini di riferimento, 3 video e 3 tracce audio; Seedance 2.5 fino a 30, 10 e 10. I file multimediali devono essere URL: base64 e caricamenti di file non sono accettati. Le immagini e i video di riferimento con volti umani reali non sono supportati dal modello. I file multimediali vengono controllati all'avvio dell'attività, e un file che viola un limite fa fallire l'attività prima di qualsiasi generazione, senza addebito.

Come si modifica o si estende una clip con Seedance 2.5?

Invia la clip come reference_video e imposta omni_reference_task_type:

{
  "model": "dreamina-seedance-2-5",
  "content": [
    {"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
    {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit"
}

Usa edit per cambiare ciò che c'è nel filmato ed extend per proseguirlo oltre il suo ultimo fotogramma. Per edit, lascia duration al valore predefinito -1; in entrambi i casi, lascia ratio su adaptive. I secondi di input vengono addebitati alla tariffa di riferimento, come spiega la guida ai prezzi.

Come far usare l'API Seedance a un agente di programmazione?

Un agente di programmazione come Claude Code, Codex o Cursor può chiamare l'API con un comando shell o un breve script. SeedRouter non fornisce un server MCP, una skill pronta né un nodo ComfyUI; questo prompt è l'intera integrazione. Esporta prima la chiave, poi incolla:

Use the SeedRouter API to generate a Seedance video for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k]    Ratio: [16:9 | 9:16 | 1:1 | adaptive]    Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]

Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
 "content": [{"type": "text", "text": "..."}],
 "resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.

Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.

Il passaggio di approvazione è importante: l'agente spende il tuo saldo, quindi non dovrebbe mai inviare attività di propria iniziativa.

Domande frequenti

Come ottengo una chiave API per Seedance?

Accedi, apri la pagina chiavi API e crea una chiave. La stessa chiave funziona per tutti i modelli Seedance e per gli altri modelli su SeedRouter.

Dove si trova la documentazione dell'API Seedance?

I riferimenti API di Seedance 2.0 e Seedance 2.5 elencano ogni campo, limite ed errore, con esempi in cURL, Python, Node.js e Go, più un file OpenAPI e una versione Markdown copiabile.

Posso generare più video contemporaneamente?

Invia un'attività per ogni video e interroga le attività in parallelo. Ogni attività restituisce un video e viene addebitata separatamente. Per elencare le attività recenti, chiama GET /v1/contents/generations/tasks con page_num, page_size e filtri come filter.status.

Quali errori devo gestire?

Un 400 significa che il corpo ha violato una regola, ad esempio un campo sconosciuto o una risoluzione non supportata, e non viene addebitato nulla. Anche un'attività che termina failed o expired riporta un codice e un messaggio di errore e non viene addebitata. La guida agli errori elenca ogni codice e quando ritentare.

Invia la tua prima richiesta

Crea una chiave, aggiungi un piccolo saldo ed esegui l'esempio Python qui sopra, oppure prova la stessa richiesta senza codice nel playground di Seedance 2.0. Per clip più lunghe e per l'editing, cambia il modello in dreamina-seedance-2-5 e consulta la pagina di Seedance 2.5.