Generación de imágenes GPT-Image-2.5

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "un rincón de lectura acogedor junto a una ventana lluviosa, luz cálida",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Parámetros de solicitud no válidos",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Error de autenticación. Comprueba tu clave de API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Saldo de la cuenta insuficiente",
    "type": "payment_required"
  }
}

POST

images

generations

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "un rincón de lectura acogedor junto a una ventana lluviosa, luz cálida",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Parámetros de solicitud no válidos",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Error de autenticación. Comprueba tu clave de API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Saldo de la cuenta insuficiente",
    "type": "payment_required"
  }
}

Elección del modelo: gpt-image-2.5-flare es más rápido y adecuado para imágenes cotidianas de alta calidad, lotes y prototipos. gpt-image-2.5-sunburst prioriza la precisión de edición para imágenes finales de producto, anuncios y edición detallada en varias etapas. Ambos modelos tienen el mismo precio.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-image-2.5-flare",
    "prompt": "un rincón de lectura acogedor junto a una ventana lluviosa, luz cálida",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Parámetros de solicitud no válidos",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": 401,
    "message": "Error de autenticación. Comprueba tu clave de API.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": 402,
    "message": "Saldo de la cuenta insuficiente",
    "type": "payment_required"
  }
}

Autenticación

string

requerido

Todos los endpoints usan Bearer Token. Obtén tu clave en la página de claves de API.

Authorization: Bearer YOUR_API_KEY

Elegir un modelo

Modelo	Punto fuerte	Uso recomendado
`gpt-image-2.5-flare`	Opción predeterminada más rápida	Redes sociales, productos, búsqueda visual, prototipos y generación por lotes
`gpt-image-2.5-sunburst`	Precisión de edición	Imágenes finales de producto, anuncios y edición detallada en varias etapas

Con los mismos parámetros, ambos modelos consumen los mismos tokens y cuestan lo mismo. Frente a gpt-image-2, se añaden xhigh y max; los niveles medium y high usan aproximadamente una cuarta parte de los tokens de salida de los niveles homónimos de la generación anterior.

Parámetros de solicitud

string

requerido

gpt-image-2.5-flare o gpt-image-2.5-sunburst.

string

requerido

Descripción de la imagen que se generará o editará. Indica sujeto, escena, composición, estilo, iluminación y elementos que deben mantenerse o cambiarse.

string

predeterminado:"auto"

Relación de aspecto o dimensiones exactas en píxeles.

auto: selección automática a partir del prompt o las referencias
Relación: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3
Dimensiones exactas, por ejemplo 1600x1200

Al editar imágenes, omite size para calcular las dimensiones a partir de la relación de entrada y resolution.

string

predeterminado:"1k"

Nivel de resolución: 1k, 2k o 4k. Se ignora cuando size contiene dimensiones exactas.

string

predeterminado:"auto"

Calidad: low, medium, high, xhigh, max o auto.

xhigh y max son exclusivos de GPT-Image-2.5. Enviarlos a gpt-image-2 devuelve HTTP 400 sin reducir la calidad automáticamente.

integer

predeterminado:"1"

Número de imágenes: de 1 a 4. Envía un número, no una cadena.

string

predeterminado:"png"

Formato: png, jpeg o webp.

integer

Compresión de 0 a 100, solo para jpeg y webp.

string

Fondo: transparent, opaque o auto.

transparent requiere png o webp; JPEG no dispone de canal alfa.

string

predeterminado:"low"

Moderación: auto o low. Si se omite, APIMart envía explícitamente low; un auto explícito se conserva.

string[]

URL de referencia para generación o edición, hasta 16. La presencia de este campo activa el modo de edición.Solo se aceptan URL HTTP(S) públicas. Primero sube las imágenes locales con POST /v1/uploads/images y usa la url devuelta.

string

Máscara para repintado local. Solo tiene efecto si también se envía image_urls. Tanto gpt-image-2.5-flare como gpt-image-2.5-sunburst admiten este parámetro.Envía una única cadena en uno de estos formatos:

Una URL HTTP(S) de imagen que el servidor pueda descargar directamente
Una Data URL PNG con el formato data:image/png;base64,...

Requisitos de la máscara:

Usa un PNG con canal alfa transparente; también se recomienda PNG para la imagen original
Las dimensiones en píxeles deben coincidir exactamente con image_urls[0]. Deben corresponder a la primera imagen de entrada, no al size de salida
Los píxeles totalmente transparentes (alpha=0) marcan el área que se editará; las demás áreas se utilizan para conservar el contenido
Envía una máscara por solicitud. Si hay varias imágenes de referencia, solo se aplica a la primera imagen de entrada
La guía general indica menos de 50 MB, mientras que la documentación del parámetro mask indica menos de 4 MB. Hasta verificarlo, usa el límite más estricto de 4 MB

Una imagen normal en blanco y negro sin canal alfa no puede usarse directamente como máscara. APIMart no añade un canal alfa y actualmente no valida de antemano que las dimensiones de la máscara coincidan con la imagen original; el cliente debe garantizar ambos puntos.

La URL HTTP(S) debe funcionar sin Cookie ni cabeceras de autorización adicionales. Las URL firmadas deben seguir vigentes durante la cola y la ejecución. El límite de descarga predeterminado es de 20 MB, con un timeout de 60 segundos; el despliegue puede sustituir estos valores.La máscara guía la edición, pero el modelo no garantiza que los píxeles situados fuera de sus límites permanezcan totalmente inalterados.

Reglas de tamaño

Anchura y altura deben ser múltiplos de 16
Ningún lado puede superar 3840 píxeles
La relación entre el lado largo y el corto no puede superar 3:1
El total de píxeles debe estar entre 655.360 y 8.294.400

Las resoluciones superiores a 2560×1440 son experimentales y pueden ser menos estables.

Correspondencia de relación y resolución

`size`	`1k`	`2k`	`4k`
`1:1`	1024×1024	2048×2048	2880×2880
`3:2`	1536×1024	2048×1360	3520×2336
`2:3`	1024×1536	1360×2048	2336×3520
`4:3`	1024×768	2048×1536	3312×2480
`3:4`	768×1024	1536×2048	2480×3312
`5:4`	1280×1024	2560×2048	3216×2576
`4:5`	1024×1280	2048×2560	2576×3216
`16:9`	1536×864	2048×1152	3840×2160
`9:16`	864×1536	1152×2048	2160×3840
`2:1`	2048×1024	2688×1344	3840×1920
`1:2`	1024×2048	1344×2688	1920×3840
`21:9`	2016×864	2688×1152	3840×1648
`9:21`	864×2016	1152×2688	1648×3840
`3:1`	1536×512	3072×1024	3840×1280
`1:3`	512×1536	1024×3072	1280×3840

También se aceptan otras dimensiones exactas que cumplan todas las reglas.

Ejemplo de edición

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "mantén el producto y el texto del envase, sustituye el fondo por un estudio blanco suave y añade una sombra natural",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Repintado local con máscara

Este ejemplo solo edita la zona totalmente transparente de la máscara. Sus dimensiones deben coincidir con product.png.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "sustituye solo el área cubierta por la máscara transparente por una cinta dorada, conservando el producto y el resto del fondo",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}

Envío y consulta de tareas

Tras el envío, el ID está en data[0].task_id. Consulta el estado de la tarea cada 2–5 segundos hasta completed o failed. Usa POST /v1/tasks/batch para varias tareas.

{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "cost": 0.01325,
    "result": {
      "images": [{
        "url": ["https://upload.apimart.ai/f/image/example.png"],
        "expires_at": 1789000000
      }]
    },
    "usage": {
      "input_tokens": 16,
      "output_tokens": 439,
      "total_tokens": 455
    }
  }
}

Las URL están en data.result.images[].url[]. Descarga y almacena los archivos cuanto antes.

Estado	Significado
`submitted`	Tarea enviada
`processing`	Generación en curso
`completed`	Éxito; `result.images` disponible
`failed`	Error; revisa `error.message`; se devuelve la reserva

Facturación

GPT-Image-2.5 se factura por el consumo real de tokens. Consulta la página de precios o /api/pricing para conocer el precio actual de tu cuenta.

Elemento	Precio por millón de tokens
Salida de imagen	$30.00
Entrada de imagen	$8.00
Entrada de imagen en caché	$2.00
Entrada de texto	$5.00
Entrada de texto en caché	$1.25

`quality` a 1024×1024	Tokens de salida	Coste oficial de salida
`low`	196	$0.00588
`medium`	439	$0.01317
`high`	1756	$0.05268
`xhigh`	3122	$0.09366
`max`	7024	$0.21072

Con quality: "auto", el servicio reserva primero el importe del nivel max para el tamaño elegido. Al finalizar, factura el uso real y libera la diferencia.

Con n > 1, la reserva aumenta de forma lineal. Las tareas fallidas se reembolsan automáticamente.

Límites y errores frecuentes

Elemento	Límite o solución
Imágenes por solicitud	1–4
Imágenes de referencia	Hasta 16
Formato de salida	PNG / JPEG / WebP
Fondo transparente	Solo PNG / WebP
Imágenes parciales en streaming	No compatible
Calidad no válida	`xhigh` / `max` requieren GPT-Image-2.5
Dimensiones no válidas	Usa múltiplos de 16 dentro de los límites de píxeles y relación

Response

integer

Código de respuesta; 200 cuando el envío es correcto.

array

Datos de la respuesta del envío.

Mostrar Elemento del array

string

Estado inicial: submitted.

string

ID único para consultar el estado y el resultado.

Visión general

Modelos

Serie de texto

Serie de imágenes

Serie de video

Serie de audio

Serie de Moderación

Gestión de subidas

Gestión de tareas

Gestión de cuenta

Generación de imágenes GPT-Image-2.5

Autenticación

Elegir un modelo

Parámetros de solicitud

Reglas de tamaño

Correspondencia de relación y resolución

Ejemplo de edición

Repintado local con máscara

Envío y consulta de tareas

Facturación

Límites y errores frecuentes

Response

​Autenticación

​Elegir un modelo

​Parámetros de solicitud

​Reglas de tamaño

​Correspondencia de relación y resolución

​Ejemplo de edición

​Repintado local con máscara

​Envío y consulta de tareas

​Facturación

​Límites y errores frecuentes

​Response

Autenticación

Elegir un modelo

Parámetros de solicitud

Reglas de tamaño

Correspondencia de relación y resolución

Ejemplo de edición

Repintado local con máscara

Envío y consulta de tareas

Facturación

Límites y errores frecuentes

Response