API de Seedance 2.0

La API le permite enviar tareas de generación de video de Seedance 2.0 de forma programática. La generación es asincrónica: cree una tarea, reciba un ID de tarea inmediatamente y luego obtenga el video terminado sondeando el endpoint de la tarea o recibiendo un webhook.

Cree una clave de API en el panel de control y envíela como un token de portador en cada solicitud. La clave completa se muestra solo una vez en el momento de la creación.

Authorization: Bearer sk_live_xxxxxxxx

Primero, envíe una tarea. Una vez que la tarea sea aceptada, elija un método de entrega de resultados: sondeando el endpoint de la tarea o recibiendo el resultado terminal a través de 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 });
}

Cree una tarea de video con POST /v1/videos/generations. El cuerpo de la solicitud tiene un modelo de nivel superior, un callback_url opcional y un objeto de entrada que contiene la solicitud y la configuración de generación.

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 controla qué entradas de medios se aceptan y cómo las interpreta el modelo.

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"
    }
  }'

Los nombres de los parámetros, los valores de enumeración, las rutas de los endpoints y los ejemplos forman parte del contrato de la API. Las descripciones a continuación explican cómo se comporta cada campo.

Esta es la respuesta de éxito de POST /v1/videos/generations. Significa que la tarea ha sido aceptada y los créditos han sido reservados. Utilice el taskId devuelto para sondear GET /v1/tasks/:id o para coincidir con una devolución de llamada de finalización o fallo.

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

Utilice GET /v1/tasks/:id para recuperar el estado actual de la tarea. No sondee más de una vez cada 10 segundos. Para sistemas de producción, prefiera los webhooks.

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"
}

Cuando callback_url está presente, Seedance llama a su endpoint cuando la tarea se completa o falla, y envía datos JSON que describen el resultado final. Si su endpoint devuelve una respuesta que no es 2xx o no responde en 15 segundos, la entrega se reintenta hasta 5 veces. Los reintentos reutilizan el mismo ID de tarea, así que elimine duplicados por ID. Devuelva una respuesta 200 tan pronto como haya registrado de forma segura los datos de devolución de llamada.

{
  "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 y GET /v1/tasks/:id devuelven esta forma de error cuando la solicitud de la API en sí falla, como parámetros inválidos, clave de API inválida, créditos insuficientes, límite de tasa o tarea no encontrada. Algunos errores incluyen campos adicionales como required, available o retry_after, según la situación.

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

Los límites de tasa se aplican por clave de API con una ventana deslizante. La generación por defecto es de 60 solicitudes por minuto; las consultas de estado son más indulgentes. Las respuestas HTTP 429 incluyen Retry-After.

La API utiliza reserva al enviar, cobro al tener éxito y reembolso al fallar. Las páginas de uso del panel de control muestran el historial de créditos de la API, los registros de tareas y las estadísticas de uso basadas en el tiempo.