API di Seedance

L'API ti consente di inviare attività di generazione video con Seedance 2.5 e Seedance 2.0 in modo programmatico. Seedance 2.5 è il modello consigliato e supporta text-to-video, image-to-video (da primo fotogramma o da primo e ultimo fotogramma) e reference-to-video multimodale. La generazione è asincrona: crei un'attività, ricevi immediatamente un ID attività e poi ottieni il video finale interrogando l'endpoint dell'attività (polling) o tramite 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'attività. Una volta accettata, scegli come ricevere il risultato: interroga l'endpoint dell'attività (polling) o ricevi il risultato finale tramite un webhook.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

curl https://api.seevio.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'attività di generazione video con una richiesta POST a /v1/videos/generations. Il corpo della richiesta deve contenere il parametro model a livello principale, un callback_url opzionale e un oggetto input contenente il prompt e i parametri di generazione.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

Il parametro generation_type controlla quali file multimediali sono accettati in input e come vengono interpretati dal modello.

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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
    }
  }'

curl https://api.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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.seevio.ai/v1/videos/generations \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2-5",
    "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": "720p"
    }
  }'

I nomi dei parametri, i valori enum, i percorsi degli endpoint e gli esempi fanno parte del contratto dell'API. Le descrizioni seguenti illustrano il comportamento di ciascun campo.

Questa è la risposta corretta restituita da POST /v1/videos/generations. Conferma che l'attività è stata accettata e che i relativi crediti sono stati prenotati. Usa il taskId restituito per interrogare l'endpoint GET /v1/tasks/:id (polling) o per associarlo a una callback di completamento o fallimento.

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

Usa GET /v1/tasks/:id per recuperare lo stato corrente dell'attività. Consigliamo di effettuare l'interrogazione non più di una volta ogni 10 secondi. Per i sistemi in produzione, è preferibile utilizzare i webhook.

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

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "billing_status": "charged",
  "credits": 100,
  "failed_reason": null,
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "billing_status": "refunded",
  "credits": 100,
  "failed_reason": "provider_failed"
}

Se viene specificato un callback_url, Seedance invierà una richiesta JSON al tuo endpoint non appena l'attività viene completata o fallisce, contenente i dettagli del risultato finale. Se il tuo endpoint risponde con uno stato diverso da 2xx o non risponde entro 15 secondi, verranno effettuati fino a 5 tentativi di invio successivi. I tentativi riutilizzano lo stesso task id, consentendoti di evitare duplicati. Rispondi con uno stato HTTP 200 non appena i dati della callback sono stati registrati in sicurezza nei tuoi sistemi.

{
  "id": "3f2aK9mR...",
  "status": "completed",
  "created_at": 1781234567,
  "model": "seedance-2-5",
  "data": {
    "results": ["https://cdn.seevio.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-5",
  "data": {
    "failed_reason": "provider_failed",
    "credits_refunded": 100
  }
}

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 questo formato di errore quando la richiesta API fallisce (ad esempio in caso di parametri non validi, chiave API non valida, crediti insufficienti, superamento dei limiti di frequenza o attività non trovata). Alcuni errori includono campi aggiuntivi come required, available o retry_after a seconda del contesto.

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

I limiti di frequenza sono applicati per singola chiave API con un meccanismo a finestra mobile. La generazione di video prevede un limite predefinito di 100 richieste al minuto, mentre le interrogazioni sullo stato delle attività sono regolate da limiti più flessibili. Le risposte HTTP 429 includono l'intestazione Retry-After.

Il sistema di fatturazione dell'API prevede la prenotazione dei crediti all'invio, l'addebito effettivo al completamento e il rimborso automatico in caso di errore. Le pagine dei consumi nella dashboard mostrano lo storico dei crediti API, i log delle attività e le statistiche di utilizzo nel tempo.