En esta página
Seedream API para Seedream 5.0 Pro
Usa Seedream 5.0 Pro mediante Seedream API para generar una imagen desde texto o hasta diez referencias HTTPS públicas. Imya gestiona autenticación, tareas, créditos en tiempo real, errores seguros y resultados almacenados.
REST API · v1 · Tareas asíncronas
Qué puedes crear
Usa un solo flujo REST para crear desde texto, generar variaciones guiadas y automatizar imágenes.
Imágenes de producto y campaña
Genera escenas de producto, conceptos publicitarios y piezas de marca desde texto.
Variaciones con referencias
Usa de 1 a 10 imágenes para guiar sujeto, composición o dirección visual.
Flujos automatizados
Envía de forma asíncrona, consulta el task ID y recibe la imagen almacenada.
Primera solicitud a Seedream API
Crea una tarea, guarda su task ID público y consúltala hasta que termine o falle.
- 1
Crear una API Key
Genera una clave en tu cuenta Imya.
- 2
Elegir la entrada
Usa solo un prompt o añade de 1 a 10 referencias.
- 3
Obtener el resultado
Consulta el task ID cada 5 segundos como mínimo.
Autenticación e idempotencia
Envía la API Key como Bearer token. Cada POST necesita una Idempotency-Key única para que un reintento no duplique tareas ni cargos.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCrear una generación de imagen
Omite image_urls para texto a imagen. Añade de 1 a 10 URL HTTPS públicas para referencias. El servidor devuelve credits_reserved en tiempo real.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-product-shot-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "A premium skincare bottle on pale stone, soft morning light",
"aspect_ratio": "4:3",
"quality": "basic",
"output_format": "png",
"n": 1
}'curl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seedream-edit-001" \
-d '{
"model": "seedream-5-pro",
"prompt": "Keep the product shape and place it in a warm studio",
"image_urls": ["https://cdn.example.com/input/product.png"],
"aspect_ratio": "4:3",
"quality": "high",
"output_format": "jpeg",
"n": 1
}'Consultar una tarea
Devuelve estado, coste final, imagen almacenada o error seguro. Consulta con al menos 5 segundos de intervalo.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parámetros
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| model | string | Sí | Usa seedream-5-pro. |
| prompt | string | Sí | Instrucciones de 3 a 3.000 caracteres. |
| image_urls | string[] | No | De 1 a 10 referencias HTTPS públicas. Omite para texto a imagen. |
| aspect_ratio | string | No | 1:1, 4:3, 3:4, 16:9, 9:16, 2:3 o 3:2. Predeterminado: 1:1. |
| quality | string | No | basic o high. 16:9 y 9:16 solo admiten basic. |
| output_format | string | No | png o jpeg. Predeterminado: png. |
| n | number | No | Debe ser 1. Se genera una imagen. |
Respuestas
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 44
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "seedream-5-pro",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:38.000Z",
"credits_reserved": 44,
"credits_used": 44,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}Una tarea nueva devuelve HTTP 202. Un reintento idéntico devuelve HTTP 200 e Idempotent-Replayed: true. La imagen se copia al almacenamiento de Imya antes de succeeded.
Créditos en tiempo real
basic y high cuestan 35 créditos base. El servidor aplica el coeficiente del plan y devuelve credits_reserved. Si no termina en 30 minutos, la tarea falla y los créditos elegibles se devuelven una sola vez sin cambiar su caducidad.
Ver planes de créditosEstado de la tarea
pendingLa tarea fue aceptada y espera para comenzar.
processingEl modelo está generando la imagen.
succeededLa generación terminó y data contiene la imagen.
failedLa generación falló. Lee el objeto error seguro.
Errores
400Falta Idempotency-Key o el JSON es inválido.
401API Key ausente o inválida.
402Créditos insuficientes.
403Cuenta desactivada o solicitud no permitida.
404Tarea inexistente o de otra cuenta.
409Clave reutilizada con otro cuerpo.
413El cuerpo supera 64 KiB.
415Content-Type debe ser application/json.
422Parámetro, prompt o referencia inválida.
429Límite de velocidad o concurrencia alcanzado.
5xxNo se pudo completar. Comprueba la tarea antes de crear otra.
Contrato común de la API pública de Imya
Estas reglas se aplican a todos los endpoints públicos de generación. Los campos y precios específicos están en la tabla del modelo.
Facturación y reintentos seguros
Al aceptar una tarea nueva se descuentan de forma atómica los créditos exactos de credits_reserved. Repetir la misma Idempotency-Key y cuerpo devuelve la tarea original sin otro cargo.
Tiempo límite y reembolsos
Una tarea que no termina en 30 minutos falla. Los créditos elegibles se devuelven una sola vez y conservan su caducidad original.
Límites de velocidad y concurrencia
Cada API Key admite 120 solicitudes por 60 segundos; una cuenta puede ejecutar cinco tareas de imagen o tres de vídeo. Respeta Retry-After en 429.
Consulta y propiedad
Consulta GET /v1/tasks/{id} con el id devuelto y al menos 5 segundos de intervalo. Solo la cuenta creadora puede leer la tarea; no hay webhooks, SDK ni envíos batch.
Errores y seguridad
Los errores públicos eliminan credenciales, URL internas y detalles de infraestructura. Un prompt inseguro puede rechazarse con prompt_blocked.
Conservación de imágenes
Las cuentas gratis conservan imágenes 7 días y las activas de pago o Lifetime hasta 30. Después, status es failed y error.code es media_deleted.
Guía de integración en producción de Seedream API
Diseña la integración de Seedream 5.0 Pro como un sistema de tareas asíncronas recuperable, no como una solicitud HTTP larga. Guarda siempre el id de Imya y haz deterministas los reintentos.
Elegir parámetros del contrato
Valida cada solicitud con la tabla de esta página. Empieza con la configuración mínima y aumenta calidad, tamaño, duración o referencias solo cuando el producto lo necesite.
Conserva el orden de las referencias y confirma los derechos de uso.
Diseñar un flujo asíncrono recuperable
Envía la tarea de imagen, guarda id y consulta GET /v1/tasks/{id} con al menos 5 segundos de intervalo. Los status públicos son pending, processing, succeeded y failed y el límite es 30 minutos. No hay webhooks, SDK ni batch.
- 01Guarda id, status, credits_reserved e identidad de solicitud antes de actualizar la UI.
- 02Aplica backoff, respeta Retry-After en 429 y no conviertas un error de transporte en otra tarea de pago.
- 03Limita a cinco tareas de imagen por cuenta y 120 solicitudes por 60 segundos y API Key.
Facturación y reintentos deterministas
Al aceptar se descuenta credits_reserved. Guarda una Idempotency-Key por creación; repetirla con el mismo cuerpo devuelve la tarea original.
Los fallos elegibles se reembolsan una vez con su caducidad original. refund_pending indica liquidación y credits_refunded la confirma.
Proteger credenciales, propiedad y medios
Guarda las API Key en el servidor y asocia id al usuario autenticado. Registra identificadores de soporte sin exponer prompts, URL privadas ni credenciales.
Las imágenes duran 7 días en gratis y hasta 30 en pago activo o Lifetime. Después status es failed y error.code media_deleted.
Lista de producción
- Valida campos del modelo.
- Guarda Idempotency-Key y cuerpo.
- Persiste estado y consulta cada 5 segundos o más.
- Aplica concurrencia y velocidad.
- Trata los cuatro status y los códigos de liquidación.
- Mantén credenciales en el servidor y define retención.
Preguntas frecuentes
¿Cada cuánto consulto?
Espera al menos 5 segundos y usa backoff.
¿Cuándo se cobran créditos?
Al aceptar se descuenta credits_reserved.
¿Un reintento cobra dos veces?
No con la misma Idempotency-Key y cuerpo.
¿Cómo trato un fallo final?
Muestra un error seguro, conserva id y comprueba credits_refunded.
¿Listo para desarrollar?
Crea una API Key o prueba prompts, referencias y calidad en el generador antes de integrar.