Seedream 5.0 Pro API

Capacidades

Precios y créditos

Los precios mostrados abajo son por imagen devuelta. Una generación común reserva una imagen. La descomposición en capas reserva 17 imágenes, liquida la cantidad real devuelta (incluyendo la imagen base) y devuelve los créditos no utilizados a su saldo original. Las tareas fallidas se reembolsan en su totalidad.

Con la resolución predeterminada de 2K, la descomposición en capas reserva 136 créditos. Si se devuelven cuatro imágenes, el cobro final es de 32 créditos y se devuelven 104 créditos.

No se admite la idempotencia de solicitudes. Cada POST válido crea una nueva tarea facturable. Si el resultado de un envío no es seguro, consulta el taskId devuelto; volver a intentar el POST puede crear otra tarea.

Autenticación

Crea una clave de API en el panel de control. La clave completa se mostrará una sola vez. Almacénala de forma segura en tu servidor y envíala como Bearer token en cada petición.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

Define la variable de entorno SEEVIO_API_KEY antes de ejecutar estos ejemplos. Los ejemplos en JavaScript se ejecutan en tu servidor con Node.js; los de Python usan el paquete requests.

Cuerpo de la petición

Parámetros de entrada

Cada solicitud crea una tarea. Las funciones de texto a imagen e imagen a imagen devuelven una sola imagen; la descomposición por capas (layer-decomposition) devuelve entre 1 y 17 imágenes, incluida la imagen base. No envíes aspect_ratio para la función layer-decomposition.

Inicio rápido

Envía esta petición mínima, guarda el taskId recibido y usa el ejemplo de consulta de tarea más abajo. El valor de créditos en la respuesta de creación es el monto reservado.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Ejemplo de respuesta de creación de tarea

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 8
}

Texto a imagen

Genera imágenes, edita referencias o descompón una imagen en capas con tu clave de API de Seevio. Las tareas se ejecutan de forma asíncrona; guarda el taskId y consulta el endpoint de la tarea o recibe un callback.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

Imagen a imagen

Para la edición de imágenes, establece generation_type como image-to-image y proporciona las image_urls. Todos los demás parámetros utilizan la misma especificación.

Reemplaza las URL de ejemplo de example.com con tus propios archivos públicos accesibles mediante HTTPS. Estas URL de ejemplo ilustran el formato de la petición y no son archivos descargables.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

Descomposición en capas

Establece generation_type en layer-decomposition y proporciona exactamente una URL de imagen. Omite aspect_ratio. output_format solo controla el formato de la imagen base. Las capas separadas siempre se devuelven en formato PNG conservando la transparencia. Guarda cada URL que se devuelve en data.results.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "generation_type": "layer-decomposition",
    "image_urls": [
      "https://example.com/teapot.png"
    ],
    "resolution": "2K",
    "output_format": "png"
  }
}'

La descomposición en capas puede devolver múltiples URL de imagen en data.results: la imagen base y las capas separadas. Cada URL apunta a una imagen independiente. El número de resultados varía según la tarea (de 1 a 17 imágenes en total); procesa el arreglo completo en lugar de leer únicamente data.results[0]. Tanto la consulta de la tarea completada como el webhook de finalización contienen este arreglo. La respuesta de creación inicial contiene el taskId y los créditos reservados, pero no las URL de las imágenes.

Ejemplo de respuesta de creación de tarea

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 136
}

Descomposición en capas completada: múltiples URL de imagen

Esta respuesta de ejemplo muestra cuatro imágenes de salida: una imagen base y tres capas. Tu tarea podría devolver un número diferente de imágenes. En la resolución de 2K solicitada, credits representa el cobro final por las cuatro imágenes; la parte no utilizada de la reserva inicial de 17 imágenes ya ha sido devuelta.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 32,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example/base.png",
      "https://cdn.seevio.ai/api/images/example/layer-1.png",
      "https://cdn.seevio.ai/api/images/example/layer-2.png",
      "https://cdn.seevio.ai/api/images/example/layer-3.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Procesar cada imagen devuelta

const response = await fetch(
  "https://api.seevio.ai/v1/tasks/TASK_ID",
  { headers: { Authorization: `Bearer ${process.env.SEEVIO_API_KEY}` } }
);
if (!response.ok) throw new Error(await response.text());
const task = await response.json();

if (task.status === "completed") {
  // Process every returned image, including the base image.
  // The number of URLs varies; do not read only results[0].
  for (const [index, imageUrl] of task.data.results.entries()) {
    console.log({ taskId: task.id, index, imageUrl });
    // Download or store this image in your application.
  }
} else if (task.status === "failed") {
  throw new Error(task.failed_reason || "Image generation failed.");
}
// If queued or generating, poll again after at least 5 seconds.

Consultar una tarea

Reemplaza el ID de ejemplo por el taskId obtenido al crear la tarea. Las consultas solo devuelven tareas que pertenecen al usuario de la clave API; los ID inaccesibles o desconocidos devuelven HTTP 404.

Realiza consultas cada 10 o 20 segundos como punto de partida, reduce la frecuencia si recibes un HTTP 429 y detente cuando el estado sea completed o failed. Para entornos de producción, se recomienda usar webhooks. Cada ejemplo de código abajo realiza una sola consulta.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

En cola

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

Completada

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

Fallida

Cuando la consulta devuelve status=failed, significa que el proceso de generación ha fallado. Consulte failed_reason para conocer el motivo del error y billing_status para saber si se ha realizado el reembolso. En este ejemplo, refunded indica que se han devuelto los créditos. El campo credits conserva el valor reservado originalmente y la respuesta no incluye data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs."
}

Los enlaces de los resultados están disponibles durante 30 días tras su almacenamiento. Una vez transcurrido este plazo, el campo results aparecerá vacío.

Webhooks

Configura callback_url en la petición de creación para recibir un POST con formato JSON cuando la tarea se complete o falle. Responde con un código 2xx en menos de 15 segundos. Los envíos fallidos se reintentan; procesa los envíos repetidos de forma idempotente usando el ID de la tarea.

Tu endpoint de callback debe aceptar solicitudes POST con un cuerpo en formato JSON (Content-Type: application/json).

Crear una tarea con callback

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "seedream-5-0-pro",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "resolution": "2K",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Las devoluciones de llamada (callbacks) utilizan la estructura de respuesta de consulta de tareas; las notificaciones de error con reembolso también incluyen credits_refunded en el nivel superior. Utiliza id para identificar la tarea y status para distinguir entre completadas y fallidas. Las notificaciones pueden repetirse: procésalas de forma idempotente por id y status. Las devoluciones de llamada no están firmadas; verifica la tarea mediante el endpoint de consulta autenticado. Los fallos en la entrega de la notificación de devolución no reembolsan una tarea que se haya completado correctamente.

Tarea completada: carga útil del callback exitosa

created_at es la fecha de creación del evento; task_created_at es la de la tarea, en segundos Unix. Los ejemplos muestran los campos recomendados; las respuestas pueden incluir campos adicionales.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": null,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

Tarea fallida: carga útil del callback con error

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "seedream-5-0-pro",
  "credits": 8,
  "failed_code": "400",
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "The input or output was flagged as sensitive. Please try again with different inputs.",
  "task_created_at": 1789171200,
  "credits_refunded": 8
}

Ejemplo de receptor

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

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

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

Este ejemplo de Next.js lee el cuerpo de la llamada JSON y procesa directamente las tareas completadas y fallidas. Te recomendamos implementar persistencia y deduplicación de ID de tareas en tu aplicación, así como encolar las tareas lentas antes de confirmar la recepción del callback.

Errores

Los errores HTTP contienen un objeto error con un código (code) y un mensaje (message). Una tarea aceptada con éxito puede fallar más tarde; consulta su estado o gestiona el callback de fallo.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Los errores utilizan error.code y error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. El error 402 insufficient_credits significa que tus créditos disponibles son insuficientes para procesar esta solicitud.

Límites de peticiones

Creación de tareas: cada clave de API permite de forma predeterminada un máximo de 100 solicitudes por minuto. Actualmente no están disponibles los límites de tarifa personalizados.

Consulta de tareas: cada clave de API permite de forma predeterminada un máximo de 120 solicitudes por minuto. Las solicitudes de consulta y las de creación de tareas se contabilizan de forma independiente.

Las solicitudes de creación de imágenes y vídeos comparten el mismo límite de velocidad (rate limit) de la clave API.

HTTP 429 incluye la cabecera Retry-After: 60 para creación y Retry-After: 5 para consultas. Usa un margen de espera y evita realizar consultas con demasiada frecuencia.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}