Seedance 2.0 MiniRiferimento API

Tutto quello che ti serve per chiamare Seedance 2.0 Mini dal codice: una guida rapida in tre passaggi, ogni campo con i suoi limiti, la formula dei prezzi, webhook e idempotenza. Gli strumenti MCP usano la stessa API /v1: con l'accesso via MCP spendi il saldo creativo, con una chiave API il saldo dell'account API sviluppatori.

EndpointPOST /v1/videos/generationsVersione del modellodreamina-seedance-2-0-mini-260615OpenAPI llms.txt Per gli agenti IA

Richiedi l'accesso all'API

L'accesso all'API per sviluppatori è su richiesta.

Guida rapidain tre chiamate

Imposta una chiave, invia il lavoro con un tetto di prezzo, poi leggi il risultato.

01
Imposta la chiave
L'accesso all'API per sviluppatori è su richiesta: chiedilo nello studio, in Chiavi API. La chiave viene mostrata una sola volta, quindi salvala in una variabile d'ambiente.
Shell
```
export API_KEY="sk_test_…"
```

Invia il lavoro

Invia la clip con POST, un Idempotency-Key e un tetto max_credits (o un quote_id). Ricevi subito un 202 e un lavoro in coda, e i crediti vengono riservati.

POST /videos/generations

curl https://api.pershot.app/v1/videos/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-mini",
    "prompt": "Creator holds the bottle to camera and explains one benefit, handheld, natural room light.",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true,
    "max_credits": 42
  }'

Dovresti vedere

{
  "id": "job_01J9ZK4T8W",
  "object": "job",
  "kind": "video",
  "status": "queued",
  "money_status": "reserved",
  "queue_position": 2,
  "requested_model": "seedance-2.0-mini",
  "credits_quoted": 42,
  "credits_charged": null
}

03
Leggi il risultato
Fai GET del lavoro finché lo stato non è succeeded. outputs[].url è firmato e scade dopo 24 ore, quindi scarica ciò che vuoi tenere.
GET /jobs/{id}
```
curl https://api.pershot.app/v1/jobs/job_01J9ZK4T8W \
  -H "Authorization: Bearer $API_KEY"
```

Parametrie limiti

Letti dal documento OpenAPI, generato dagli stessi schemi con cui l'API convalida le richieste. I campi sconosciuti vengono rifiutati.

Campi della richiesta di Seedance 2.0 Mini
Campo	Tipo	Valori ammessi	Note
`model`Obbligatorio	string	seedance-2.0-fast · seedance-2.0-mini · auto	L'id del modello.
`prompt`Obbligatorio	string	2–2000 caratteri	Cosa generare: il soggetto, la camera e la luce.
`duration`Predefinito: 5	integer	4–15	Durata del risultato in secondi interi, fino a 15.
`resolution`Predefinito: "720p"	string	480p · 720p	Risoluzione del risultato. 480p per le bozze, 720p per la consegna; ognuna è una generazione a sé.
`aspect_ratio`Predefinito: "16:9"	string	16:9 · 9:16 · 1:1	Forma del fotogramma.
`generate_audio`Predefinito: true	boolean	–	Audio nativo. Il prezzo è lo stesso, attivo o disattivato.
`image_url`Facoltativo	string	URL https	Primo fotogramma per il video; l'immagine di partenza per i modelli di modifica. Un URL https pubblico o un URL di caricamento.
`reference_image_urls`Facoltativo	string[]	Fino a 9 · URL https	Immagini di riferimento per soggetto e stile. Richiamale nel prompt come @image1, @image2.
`seed`Facoltativo	integer	0–2.147.483.647	Accettato e ignorato: Seedance 2.0 non accetta un seed.
`quote_id`Facoltativo	string	qt_…	Esegue al prezzo di un preventivo di POST /v1/quotes, valido per 10 minuti.
`max_credits`Facoltativo	number	> 0	Il massimo che questo lavoro può costare. Oltre questa cifra il lavoro viene rifiutato, mai addebitato.
`webhook_url`Facoltativo	string	URL https	Un URL https che riceve gli eventi del lavoro.
`end_user_id`Facoltativo	string	1–128 caratteri	Per gli account sviluppatore approvati (accesso su richiesta): il tuo ID utente per questa richiesta, mostrato nell'utilizzo.
`project_id`Facoltativo	string	prj_…
`shot_id`Facoltativo	string	sht_…
`routing_preference`Facoltativo	string	stability · speed
`enhance`Facoltativo	object	–

Invia esattamente uno tra quote_id e max_credits. Questo endpoint rifiuta model "auto": per i video, chiama prima POST /v1/auto/plan, poi invia il modello scelto con max_credits.

Frequenza e lavori simultanei: Per impostazione predefinita, 60 richieste al minuto per chiave e 3 lavori alla volta per account. Più chiavi non aumentano i lavori simultanei.

Limiti

Letti dalla stessa tabella su cui si basano i controlli dell'API. Ogni riga indica chi controlla il limite e cosa succede se lo superi.

ApplicatoLo controlliamo noi e rispondiamo 400 prima di qualsiasi preventivo o riserva.
FornitoreLo controlla il fornitore. Un lavoro che rifiuta non riesce, e non viene addebitato nulla.
ConsigliatoNessuno lo controlla. Restarci dentro dà risultati migliori.

Limiti per seedance-2.0-mini
Limite	Valore	Unità	Chi controlla	Oltre il limite
Richiesta
Lunghezza del prompt`prompt`	da 2 a 2000	caratteri	Applicato	400 invalid_request su prompt, prima di qualsiasi preventivo o riserva.
Prompt in inglese`prompt`	fino a 1000	parole	Consigliato	Accettato. Con un prompt più lungo il modello potrebbe seguirlo meno fedelmente.
Prompt in cinese`prompt`	fino a 500	caratteri cinesi	Consigliato	Accettato. Con un prompt più lungo il modello potrebbe seguirlo meno fedelmente.
Durata`duration`	da 4 a 15Predefinito 5	secondi	Applicato	400 invalid_request su duration. Solo secondi interi.
Risoluzione`resolution`	480p, 720pPredefinito 720p	–	Applicato	400 invalid_request su resolution.
Proporzioni`aspect_ratio`	16:9, 9:16, 1:1Predefinito 16:9	–	Applicato	400 invalid_request su aspect_ratio.
Seed`seed`	Ignorato	–	Fornitore	Accettato e non inviato: Seedance 2.0 non accetta un seed, quindi un seed non ripete un risultato.
Durata del video in ingresso`input_video_seconds`	da 2 a 15	secondi	Applicato	400 invalid_request su POST /v1/quotes. Le generazioni tramite API non accettano un video in ingresso.
Immagini che invii
Immagini di riferimento`reference_image_urls`	fino a 9	immagini	Applicato	400 invalid_request su reference_image_urls.
Primo fotogramma o riferimenti`reference_image_urls`	image_url o reference_image_urls, non entrambi	–	Applicato	400 invalid_request su reference_image_urls. Seedance 2.0 usa una sola delle due modalità per lavoro.
Lato dell'immagine`image_urlreference_image_urls`	da 300 a 6000	px per lato	Applicato ai caricamenti	Caricamenti: 400 invalid_request su image_url o reference_image_urls.N, prima di qualsiasi preventivo o riserva. Altri link: il fornitore rifiuta il lavoro, e non viene addebitato nulla.
Forma dell'immagine`image_urlreference_image_urls`	da 0,4 a 2,5	larghezza ÷ altezza	Applicato ai caricamenti	Caricamenti: 400 invalid_request su image_url o reference_image_urls.N, prima di qualsiasi preventivo o riserva. Altri link: il fornitore rifiuta il lavoro, e non viene addebitato nulla.
Dimensione del caricamento`file`	fino a 10	MB	Applicato	POST /v1/uploads risponde 400 invalid_request su file.
Formati di caricamento`file`	JPEG, PNG, WebP	–	Applicato	Letto dal file stesso, non dal suo nome. Qualsiasi altro formato: 400 invalid_request su file.
Dimensione dell'immagine collegata`image_urlreference_image_urls`	fino a 30	MB	Fornitore	Per le immagini collegate da altri host. Il fornitore rifiuta il lavoro, e non viene addebitato nulla.
Formati dell'immagine collegata`image_urlreference_image_urls`	JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF	–	Fornitore	Per le immagini collegate da altri host. Il fornitore rifiuta il lavoro, e non viene addebitato nulla.
Risultato
Pixel in uscita	480p16:9864×4969:16496×8641:1640×640720p16:91280×7209:16720×12801:1960×960	px	Fornitore	Stabiliti dal modello per ogni risoluzione e proporzione.
Frequenza dei fotogrammi	24	fps	Fornitore	Uguale per ogni video.
Formato di uscita	MP4	–	Fornitore	Ogni video è un MP4, con audio quando generate_audio è attivo.
Link
Link di caricamento	7	giorni	Applicato	Dopo, il link risponde 403. Carica di nuovo il file.
Link del risultato	24	ore	Applicato	Dopo, il link risponde 403. Richiedi di nuovo il lavoro con GET per avere un link nuovo. Il file resta conservato per 12 mesi (outputs_expire_at del lavoro indica la data), più a lungo se il risultato è salvato in Risorse o usato in un progetto.

Non scarichiamo mai immagini da altri host, quindi per quei link la dimensione la controlla il fornitore, e un lavoro che rifiuta non viene addebitato. Gli stessi limiti sono disponibili in JSON: GET /v1/models restituisce un oggetto limits per ogni modello.

Limiti per ogni modello

Prezzicalcolati in modo trasparente

Ogni lavoro ha un preventivo in crediti prima dell'esecuzione (1 US$ = 100 crediti). La tariffa al secondo serve per il budget; POST /v1/quotes restituisce la cifra esatta.

crediti = ceil(prezzo di listino BytePlus × 0,55 × 100), dove prezzo di listino = (s in ingresso + s in uscita) × larghezza × altezza × 24 ÷ 1024 × tariffa di listino

Prezzi di Seedance 2.0 Mini
Specifiche	Al secondo (API)	5 s	10 s	15 s
480pSenza video in ingresso	0,020 $Con un video in ingresso: 0,012 $/s≈ 500 s ogni 10 $	10 cr≈ 0,10 $	20 cr≈ 0,20 $	30 cr≈ 0,30 $
720pSenza video in ingresso	0,042 $Con un video in ingresso: 0,025 $/s≈ 238 s ogni 10 $	21 cr≈ 0,21 $	42 cr≈ 0,42 $	63 cr≈ 0,63 $

I lavori rifiutati o non riusciti non vengono addebitati.

Come si calcolano i prezzi Confronta con fal, Replicate e WaveSpeed

Webhooke idempotenza

I nuovi tentativi non addebitano mai due volte e non devi interrogare lo stato di continuo.

Idempotenza: Ogni POST di generazione richiede un Idempotency-Key (da 1 a 255 caratteri ASCII visibili). La stessa chiave entro 24 ore restituisce lo stesso lavoro con HTTP 200, quindi un nuovo tentativo dopo un timeout non crea né addebita mai un secondo lavoro.
Prompt rifiutati: Un prompt rifiutato dal controllo preliminare (422 content_rejected) non crea nulla, quindi puoi riusare la stessa chiave con un nuovo prompt.
Eventi: job.queuedjob.processingjob.succeededjob.failedjob.cancelled
Firma: X-Signature contiene t, l'ora unix, e v1, un HMAC-SHA256 di t, un punto e il corpo grezzo, con il tuo segreto whsec_ come chiave. Rifiuta i timestamp più vecchi di cinque minuti ed elimina i duplicati con X-Event-Id.
Consegna: Una risposta 2xx entro 10 secondi vale come consegnata. Le consegne non riuscite vengono ritentate dopo 1 min, 5 min, 30 min, 2 h e 6 h. I reindirizzamenti non vengono seguiti.

Corpo del webhook

{
  "id": "evt_01J9ZKB1QX",
  "type": "job.succeeded",
  "created_at": "2026-09-29T14:02:31Z",
  "data": {
    "job": {
      "id": "job_01J9ZK4T8W",
      "object": "job",
      "kind": "video",
      "status": "succeeded",
      "money_status": "settled",
      "requested_model": "seedance-2.0-mini",
      "credits_charged": 42,
      "outputs": [
        {
          "kind": "video",
          "url": "https://…/job_01J9ZK4T8W.mp4?sig=…"
        }
      ]
    }
  }
}

Verifica X-Signature

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as received, before any JSON parsing.
export function verifyWebhook(header, rawBody, secret, toleranceSec = 300) {
  let t = null;
  const signatures = [];
  for (const item of (header ?? "").split(",")) {
    const [key, value] = item.split("=", 2);
    if (key === "t") t = Number(value);
    if (key === "v1") signatures.push(Buffer.from(value, "hex"));
  }
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}

// verifyWebhook(req.headers["x-signature"], rawBody, process.env.WEBHOOK_SECRET)
// Answer 2xx quickly, and skip an X-Event-Id you have already handled.

Errorie cosa fare

Ogni errore ha la stessa forma: un oggetto error con code, message, param e request_id. Quelli che incontrerai più spesso:

Codice	HTTP	Cosa fare
`invalid_request`	400	Correggi il campo indicato in param.
`unauthorized`	401	Controlla la chiave e l'header Bearer.
`insufficient_credits`	402	Fai una ricarica, poi riprova con lo stesso Idempotency-Key.
`forbidden_model`	403	Aggiungi il modello o lo strumento all'elenco consentito della chiave nello studio, oppure usa un'altra chiave. Strumenti come Migliora hanno bisogno di una voce propria.
`quote_expired`	409	Chiedi un nuovo preventivo; i preventivi durano 10 minuti.
`price_changed`	409	Il prezzo ha superato il tuo tetto. Chiedi un nuovo preventivo o alza max_credits.
`content_rejected`	422	Non è stato addebitato nulla. Cambia il prompt o le immagini.
`rate_limited`	429	Aspetta il tempo indicato da Retry-After, poi riprova.
`upstream_unavailable`	503	Il modello non è disponibile. Riprova più tardi; un lavoro che non parte mai non viene addebitato.

Documento OpenAPI 3.1 llms.txt Documentazione completa Se arrivi da fal, Replicate o WaveSpeed

Imposta la chiave

Invia il lavoro

Leggi il risultato

Limiti