En esta página
GPT Image 2 API
Genera una imagen de GPT Image 2 desde un prompt y referencias opcionales mediante una API asíncrona predecible. Imya gestiona el estado, el precio según el plan y los archivos.
REST API · v1 · Tareas asíncronas
Envía tu primera solicitud
Crea una tarea, guarda el task ID y consúltala hasta que el resultado esté listo.
- 1
Crear una API Key
Genera una clave en la configuración de tu cuenta Imya.
- 2
Crear una tarea
Envía el model ID, el prompt y las opciones de salida.
- 3
Obtener el resultado
Consulta la tarea hasta que termine o falle.
Autenticación e idempotencia
Envía la API Key como Bearer token. Cada POST de generación requiere una Idempotency-Key única para reintentar sin duplicar tareas ni cargos.
Authorization: Bearer YOUR_IMYA_API_KEY
Content-Type: application/json
Idempotency-Key: YOUR_UNIQUE_REQUEST_KEYCrear una generación de imagen
Crea una tarea asíncrona de GPT Image 2 y descuenta de forma atómica los créditos exactos devueltos en credits_reserved.
/v1/images/generationscurl https://imya.ai/v1/images/generations \
-H "Authorization: Bearer YOUR_IMYA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: gpt-image-order-001" \
-d '{
"model": "gpt-image-2",
"prompt": "A luxury perfume product photo on warm marble, soft studio light",
"aspect_ratio": "1:1",
"resolution": "1K",
"n": 1
}'Consultar una tarea
Devuelve el estado, el coste final, los archivos o un error estructurado. Consulta con al menos 5 segundos de intervalo; hacerlo más rápido consume límite pero no actualiza el proveedor.
/v1/tasks/{id}curl https://imya.ai/v1/tasks/task_0123456789abcdef0123456789abcdef \
-H "Authorization: Bearer YOUR_IMYA_API_KEY"Parámetros de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| model | string | Sí | Usa gpt-image-2. |
| prompt | string | Sí | Prompt de texto para la imagen, de 1 a 20.000 caracteres. |
| aspect_ratio | string | No | auto, 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 3:1, 1:3, 21:9 o 9:21. |
| resolution | string | No | 1K, 2K o 4K. Algunas relaciones solo admiten 1K. |
| n | number | No | Debe ser 1. Se genera exactamente una imagen. |
| image_urls | string[] | No | De 1 a 16 imágenes HTTPS públicas de referencia. |
Respuestas
{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "pending",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:00.000Z",
"credits_reserved": 13
}{
"id": "task_0123456789abcdef0123456789abcdef",
"status": "succeeded",
"model": "gpt-image-2",
"created_at": "2026-07-15T08:00:00.000Z",
"updated_at": "2026-07-15T08:00:42.000Z",
"credits_reserved": 13,
"credits_used": 13,
"data": [
{
"url": "https://cdn.imya.ai/generated/example.png"
}
]
}Facturación en créditos
El coste base es 10 créditos en 1K, 15 en 2K y 24 en 4K. El servidor aplica el coeficiente del plan del propietario y devuelve el cargo real en credits_reserved. El ejemplo cobra 13 créditos a una cuenta normal en 1K. Usa siempre el valor devuelto; n es 1.
Estado de la tarea
pendingLa tarea fue aceptada y espera para comenzar.
processingEl modelo está generando el resultado.
succeededLa generación terminó y data contiene los archivos.
failedLa generación falló. Consulta el objeto error estructurado.
Errores
400Falta Idempotency-Key o el JSON no es válido.
401Falta la API Key o no es válida.
402La cuenta no tiene créditos suficientes.
403La cuenta de API está desactivada.
404La tarea no existe o no pertenece a la cuenta.
409La clave de idempotencia se reutilizó con otro cuerpo.
413El cuerpo supera 64 KiB.
415Content-Type debe ser application/json.
422El modelo, prompt, relación, resolución, n o referencia no es válido.
429Se alcanzó el límite de velocidad o concurrencia.
5xxLa solicitud no pudo completarse o enviarse.
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 GPT Image 2 API
Diseña la integración de GPT Image 2 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.
¿Quieres probar el modelo antes de integrarlo?
Abre el generador de GPT Image 2 y compara prompts y opciones sin escribir código.
Probar GPT Image 2 en línea