API de Seedance

La API te permite enviar tareas de generación de video con Seedance 2.5 y Seedance 2.0 mediante código. Seedance 2.5 es el modelo recomendado y admite texto a video, imagen a video (con primer fotograma o con primer y último fotograma) y referencia multimodal a video. La generación es asíncrona: creas una tarea, recibes un ID de tarea al instante y luego obtienes el video finalizado consultando el endpoint de la tarea (polling) o mediante un webhook.

Crea una clave de API en el panel de control y envíala como un token Bearer en cada solicitud. La clave completa se muestra solo una vez al momento de crearla.

Authorization: Bearer sk_live_xxxxxxxx

Primero, envía una tarea. Una vez aceptada, elige un método para recibir el resultado: consulta el endpoint de la tarea o recibe el resultado final a través de 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": "1080p",
      "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 una tarea de video mediante una solicitud POST a /v1/videos/generations. El cuerpo de la solicitud incluye el modelo en el nivel superior, un callback_url opcional y un objeto input con el prompt y la configuración de generación.

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": "1080p",
      "generate_audio": true,
      "watermark": false,
      "web_search": false,
      "return_last_frame": false
    }
  }'

generation_type define qué archivos multimedia se aceptan y cómo los interpreta el modelo.

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": "1080p",
      "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"
    }
  }'

Los nombres de parámetros, valores de enum, rutas de endpoints y ejemplos forman parte del contrato de la API. Las siguientes descripciones detallan el comportamiento de cada campo.

Esta es la respuesta correcta de una solicitud POST a /v1/videos/generations. Significa que la tarea se ha aceptado y que se han reservado los créditos correspondientes. Utiliza el taskId devuelto para consultar el estado mediante GET /v1/tasks/:id o para identificar la tarea en un webhook de finalización o fallo.

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

Usa GET /v1/tasks/:id para consultar el estado actual de una tarea. No realices consultas con una frecuencia menor a 10 segundos. Para sistemas en producción, se recomienda el uso de webhooks.

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

Si incluyes callback_url, Seedance llamará a tu endpoint cuando la tarea se complete o falle, enviando la información del resultado en formato JSON. Si tu endpoint devuelve un código de estado que no sea 2xx o no responde en 15 segundos, se reintentará el envío hasta 5 veces. Los reintentos mantienen el mismo ID de tarea, por lo que se recomienda eliminar duplicados usando este ID. Devuelve una respuesta 200 en cuanto hayas registrado correctamente los datos del callback.

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

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

Los límites de frecuencia se aplican por clave de API mediante una ventana deslizante. Por defecto, el límite para generación es de 100 solicitudes por minuto; las consultas de estado son más flexibles. Las respuestas HTTP 429 incluyen la cabecera Retry-After.

La API funciona mediante reserva al enviar, cobro al completarse con éxito y reembolso en caso de fallo. Las páginas de consumo del panel muestran el historial de créditos de la API, los registros de tareas y estadísticas de uso por periodo.