Seedance 2.0 API

L'API ti consente di inviare task di generazione video Seedance 2.0 in modo programmatico. La generazione è asincrona: crei un task, ricevi immediatamente un ID del task, quindi ottieni il video finito interrogando l'endpoint del task o ricevendo un webhook.

Crea una chiave API nella dashboard e inviala come token Bearer in ogni richiesta. La chiave completa viene mostrata solo una volta al momento della creazione.

Authorization: Bearer sk_live_xxxxxxxx

Invia prima un task. Dopo che il task è stato accettato, scegli un metodo di consegna del risultato: interroga l'endpoint del task o ricevi il risultato terminale tramite un webhook.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

Crea un task video con POST /v1/videos/generations. Il corpo della richiesta ha un modello di primo livello, un callback_url opzionale e un oggetto di input contenente le impostazioni di prompt e generazione.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cat surfing on a neon wave, cinematic lighting",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

generation_type controlla quali input multimediali sono accettati e come il modello li interpreta.

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "callback_url": "https://your-domain.com/api/seedance/webhook",
    "input": {
      "prompt": "a cinematic drone shot over a futuristic coastal city at sunrise",
      "generation_type": "text-to-video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false,
      "seed": -1
    }
  }'

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "the subject turns toward camera, soft studio motion",
      "generation_type": "image-to-video",
      "image_urls": ["https://your.cdn.com/first-frame.jpg"],
      "duration": 5,
      "resolution": "720p"
    }
  }'

curl https://api.seedance2.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-0",
    "input": {
      "prompt": "use the product from image 1 and the camera motion from the reference video",
      "generation_type": "reference-to-video",
      "image_urls": ["https://your.cdn.com/product.jpg"],
      "video_urls": ["https://your.cdn.com/camera-motion.mp4"],
      "audio_urls": [],
      "duration": 8,
      "resolution": "1080p"
    }
  }'

I nomi dei parametri, i valori delle enumerazioni, i percorsi degli endpoint e gli esempi fanno parte del contratto API. Le descrizioni seguenti spiegano come si comporta ogni campo.

Questa è la risposta di successo da POST /v1/videos/generations. Significa che il task è stato accettato e i crediti sono stati riservati. Usa il taskId restituito per interrogare GET /v1/tasks/:id o per associare un callback di completamento o fallimento.

{
  "taskId": "3f2aK9mR...",
  "credits": 60
}

Usa GET /v1/tasks/:id per recuperare lo stato corrente del task. Non effettuare polling più di una volta ogni 10 secondi. Per i sistemi di produzione, preferisci i webhook.

curl https://api.seedance2.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer sk_live_xxx"

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "charged",
  "credits": 60,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "billing_status": "refunded",
  "credits": 60,
  "failed_reason": "provider_failed"
}

Quando callback_url è presente, Seedance chiama il tuo endpoint quando il task è completato o fallito, e invia dati JSON che descrivono il risultato finale. Se il tuo endpoint restituisce una risposta non 2xx o non risponde entro 15 secondi, la consegna viene ritentata fino a 5 volte. I tentativi riutilizzano lo stesso ID del task, quindi deduplica per ID. Restituisci una risposta 200 non appena hai registrato in modo sicuro i dati del callback.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "results": ["https://cdn.seedance2.ai/.../x.mp4"],
    "video_expires_at": "2026-06-13T10:00:00Z",
    "last_frame_url": null,
    "processing_time": 48
  }
}

{
  "id": "3f2aK9mR...",
  "status": "failed",
  "created_at": 1781234567,
  "model": "seedance-2-0",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 60
  }
}

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const videoUrl = callbackData.data.results[0];
    // Save the video URL or update your own task record here.
  }

  if (callbackData.status === "failed") {
    const errorMessage = callbackData.data.failed_reason;
    // Mark your own task record as failed here.
  }

  return new Response(null, { status: 200 });
}

POST /v1/videos/generations e GET /v1/tasks/:id restituiscono questa forma di errore quando la richiesta API stessa fallisce, ad esempio parametri non validi, chiave API non valida, crediti insufficienti, limitazione della frequenza o task non trovato. Alcuni errori includono campi extra come required, available o retry_after a seconda della situazione.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this task.",
    "required": 60,
    "available": 12
  }
}

I limiti di frequenza vengono applicati per chiave API con una finestra scorrevole. La generazione di default è 60 richieste al minuto; le query di stato sono più permissive. Le risposte HTTP 429 includono Retry-After.

L'API utilizza la prenotazione all'invio, l'addebito al successo e il rimborso al fallimento. Le pagine di utilizzo della dashboard mostrano la cronologia dei crediti API, i log dei task e le statistiche di utilizzo basate sul tempo.