Seedance 2.5.
Nel tuo prodotto.

Il tuo primo video in poche richieste.

Salva la chiave come SEADANCE_API_KEY sul tuo server. Imposta SEADANCE_REQUEST_KEY su un valore univoco per questo video (ad esempio con uuidgen) e mantieni quel valore nei nuovi tentativi. Assicurati che il tuo account abbia abbastanza crediti. Questo esempio riserva 350 crediti per un video di 5 secondi a 720p. Copia l’id restituito per consultarne lo stato.

export SEADANCE_API_KEY="sd_live_your_key"
# Keep this value for retries; choose a new value for a new video.
export SEADANCE_REQUEST_KEY="${SEADANCE_REQUEST_KEY:-$(uuidgen)}"

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos" \
  -H "Authorization: Bearer $SEADANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SEADANCE_REQUEST_KEY" \
  --data '{
  "model": "seedance-2.5",
  "mode": "text-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5
}'

Questa documentazione non avvia mai una generazione automaticamente. L’invio di una richiesta di creazione utilizza i tuoi crediti.

Autenticati dal tuo server.

Ogni chiamata API usa Authorization: Bearer sd_live_…. Non inserire le chiavi in browser, app mobili, repository pubblici o codice lato client. La chiave completa viene mostrata una sola volta; puoi revocarla nella dashboard API.

Autorizzazioni predefinite delle chiavi: videos:write per caricamenti e generazione; videos:read per modelli e stato delle attività; account:read per i crediti. L’accesso e i limiti dell’account si applicano a tutte le chiavi.

Crea un’attività video.

Usa Content-Type: application/json e un Idempotency-Key univoco per ogni generazione prevista. Il server può impiegare del tempo per ottenere l’accettazione dell’attività da parte del fornitore. Se la connessione scade, ripeti lo stesso corpo con la stessa chiave. HTTP 202 significa che l’attività è stata accettata, non completata. Idempotency-Key accetta da 1 a 128 caratteri ASCII stampabili senza spazi.

Questi campi consentono a Seedance 2.5 di supportare testo, fotogrammi iniziali e finali, riferimenti multimodali, montaggio ed estensione video. GET /models è il riferimento aggiornato per le funzionalità e i prezzi disponibili.

{
  "model": "seedance-2.5",
  "mode": "image-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "firstFrameUrl": "YOUR_UPLOADED_PUBLIC_OBJECT_URL"
}

{
  "model": "seedance-2.5",
  "mode": "reference-to-video",
  "prompt": "A paper boat floating through a sunlit stream, gentle camera movement",
  "aspectRatio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "referenceImageUrls": [
    "YOUR_UPLOADED_IMAGE_URL"
  ],
  "referenceVideoUrls": [
    "YOUR_UPLOADED_VIDEO_URL"
  ]
}

Carica una volta. Usa l’URL come riferimento.

Invia POST /uploads con fileName, contentType, size (in byte) e kind (image, video o audio). Prima di expiresAt, invia i byte originali del file a uploadUrl tramite PUT e gli header requiredHeaders. Dopo il caricamento, usa publicObjectUrl nella richiesta di generazione. I riferimenti devono appartenere allo stesso account; non sono accettati URL esterni arbitrari o input in base64.

// Node.js 20+ · upload once, then use publicObjectUrl
import { readFile } from "node:fs/promises";

const bytes = await readFile("./first-frame.jpg");
const signed = await fetch("https://seedance3ai.dev/api/v1/uploads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SEADANCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fileName: "first-frame.jpg", contentType: "image/jpeg",
    size: bytes.length, kind: "image",
  }),
});
const upload = await signed.json();
if (!signed.ok) throw new Error(JSON.stringify(upload));
const stored = await fetch(upload.uploadUrl, {
  method: "PUT", headers: upload.requiredHeaders, body: bytes,
});
if (!stored.ok) throw new Error("Upload failed");
console.log(upload.publicObjectUrl);
// Use this URL as firstFrameUrl in an image-to-video request.

La dimensione e il tipo di contenuto dichiarati devono corrispondere al file caricato. Gli URL di caricamento scadono; richiedine un altro se necessario. Durata, dimensioni e formato dei file multimediali vengono verificati prima della generazione.

Segui l’attività fino al completamento.

GET /videos/:id restituisce l’attività attuale. Esegui una query ogni 5–10 secondi, interrompi quando ricevi succeeded o failed e rispetta l’attesa indicata da Retry-After, se presente. Le query sono limitate alle attività API del tuo account. L’integrazione attuale utilizza query periodiche.

curl --fail-with-body "https://seedance3ai.dev/api/v1/videos/TASK_ID" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

{
  "id": "a1b2c3d4-1234-4567-8901-abcdef123456",
  "status": "succeeded",
  "credits_reserved": 350,
  "created_at": "2026-10-27T00:00:00.000Z",
  "output": {
    "url": "https://your-result-host.example/video.mp4"
  },
  "error": null,
  "refund_status": "not_applicable"
}

output è null finché non è disponibile un video. Un’attività non riuscita include un errore; consulta refund_status per lo stato del rimborso dei crediti. Scarica tempestivamente i risultati completati. Eliminare un video non azzera la sua richiesta: ripetere quell’Idempotency-Key restituisce 410 video_deleted e non può crearlo di nuovo.

Conosci il costo in crediti prima di integrare.

La generazione tramite API usa gli stessi crediti dell’account e le stesse tariffe Seedance 2.5 del sito. I crediti vengono riservati quando una richiesta viene accettata. Le generazioni non riuscite restituiscono questi crediti al saldo dei crediti una tantum. Un errore di validazione prima della creazione dell’attività non produce un video a pagamento.

Costo = durata dell’output × tariffa di output, più la durata degli eventuali video di riferimento × tariffa di riferimento. La durata dei video di riferimento viene misurata sul server; il totale viene arrotondato per difetto ai secondi interi ai fini dell’addebito. L’audio nativo è incluso. Ad esempio, 5 secondi a 720p costano 350 crediti, oppure 600 crediti con un video di riferimento di 5 secondi.

curl --fail-with-body "https://seedance3ai.dev/api/v1/models" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

curl --fail-with-body "https://seedance3ai.dev/api/v1/credits" \
  -H "Authorization: Bearer $SEADANCE_API_KEY"

Consulta i crediti disponibili, la cronologia delle richieste e i limiti dell’account nella dashboard API. Aggiungi crediti dalla pagina dei prezzi del sito con lo stesso account; non esistono un saldo separato o un endpoint di ricarica per l’API. Non serve un abbonamento attivo se hai abbastanza crediti disponibili. Le regole sulla scadenza dell’abbonamento e sui crediti una tantum sono le stesse del sito.

Aggiungere crediti non aumenta i limiti di frequenza, simultaneità o uso giornaliero dell’API e non riattiva un account disattivato. Il limite giornaliero conteggia tutti i crediti riservati, inclusi quelli delle generazioni non riuscite e rimborsate, e si azzera alle 00:00 UTC. Contatta l’assistenza se la tua applicazione richiede limiti più elevati.

Riprova in sicurezza. Evita addebiti duplicati.

Usa un Idempotency-Key per ogni video previsto e conservalo insieme al corpo esatto della richiesta fino a conoscere il risultato. Nuove chiavi rappresentano nuove generazioni. Una risposta di errore contiene error.code, error.message e request_id; includi l’ID della richiesta quando contatti l’assistenza.