API de imágenes

Genere o edite imágenes con los modelos GPT Image y de imagen de Gemini disponibles para una clave de consumo de Essevin.

Essevin ofrece una única forma de solicitud compatible con OpenAI Images para los modelos de imagen habilitados en la clave actual. Descubra primero el ID exacto del modelo; no asuma que todos los modelos de imagen del catálogo completo están disponibles.

Elemento	Valor
URL base	`https://api.essevin.com/v1`
Generar	`POST /v1/images/generations`
Editar	`POST /v1/images/edits` cuando las capacidades del modelo devuelto incluyen edición
Estado asíncrono	`GET /v1/images/tasks?task_id=...` después de una respuesta `202 Accepted`
Autenticación	`Authorization: Bearer <clave del plan correspondiente>`

1. Busque un modelo de imagen habilitado

curl https://api.essevin.com/v1/models \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

Elija un ID exacto devuelto con capacidad de imagen. Entre los ID representativos están gpt-image-2, gemini-2.5-flash-image y gemini-3-pro-image; la disponibilidad depende del grupo de la clave.

2. Genere una imagen

curl https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Una foto de producto limpia de una taza de cerámica sobre una mesa blanca",
    "size": "1024x1024",
    "n": 1,
    "response_format": "url"
  }'

La URL de la respuesta es temporal. Descárguela en el almacenamiento existente de la aplicación cuando el resultado deba persistir.

Entrada de imagen y edición

Las capacidades de imagen varían según el modelo. Revise GET /v1/models y use solo los campos admitidos por la ruta seleccionada:

Entrada	Uso
URL o Data URL de `image` en el JSON de generación	Generación de imagen a imagen o con imagen de referencia cuando el modelo lo admite
Solicitud multipart a `/v1/images/edits`	Integraciones de edición de OpenAI existentes cuando el modelo lo admite
`prompt`	Describa el cambio solicitado y los detalles que deben permanecer sin cambios

Edite una imagen local con multipart

curl https://api.essevin.com/v1/images/edits \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=Mueva la taza hacia la derecha y mantenga la etiqueta sin cambios" \
  -F "[email protected]" \
  -F "size=1536x1024" \
  -F "quality=medium" \
  -F "output_format=png"

Compatibilidad de imágenes de Gemini

Los modelos de imagen de Gemini mantienen el mismo protocolo de OpenAI Images del lado del cliente, pero sus capacidades no son idénticas a las de GPT Image.

Capacidad	Comportamiento
Solicitud	Llame a `/v1/images/generations`; Essevin adapta la solicitud para el modelo Gemini seleccionado.
Respuesta	Lea el JSON estándar de OpenAI Images desde `data[].b64_json` o `data[].url`.
Edición	Los modelos con capacidad de edición aceptan una o más referencias a través de `/v1/images/edits`; Gemini no admite una `mask` de región fija.
Tamaño	El gateway valida `size` contra el modelo seleccionado antes de generar.
Campos opcionales	`quality`, `background`, `output_format`, `input_fidelity` y `n` dependen del modelo.
Streaming	Mantenga las solicitudes de imagen de Gemini de forma síncrona; no envíe `stream: true`.
Asíncrono	Algunos modelos respetan `Prefer: respond-async`; use el estado HTTP para distinguir `202 task_id` de un resultado síncrono.

Use ESSEVIN_GEMINI_API_KEY cuando el modelo de imagen seleccionado pertenezca al grupo del plan Gemini. Conserve el ID completo del modelo, incluido cualquier sufijo, exactamente como lo devuelve GET /v1/models.

Campos comunes de la solicitud

Campo	Obligatorio	Descripción
`model`	Sí	Un ID completo de GPT Image o de imagen de Gemini devuelto para la clave actual
`prompt`	Sí	Contenido de la imagen, composición, estilo, texto o instrucciones de edición
`size`	No	`auto` o `ANCHOxALTO`; la compatibilidad varía según el modelo
`quality`	No	`low`, `medium`, `high` o `auto` cuando el modelo lo admite
`n`	No	Cantidad de imágenes; algunos modelos solo admiten `1`
`background`	No	`opaque` o `transparent` cuando el modelo lo admite
`output_format`	No	`png`, `jpeg` o `webp` cuando el modelo lo admite
`image` / `mask`	Para edición	Se pueden aceptar una o más referencias; la compatibilidad de `mask` depende del modelo y no está disponible para Gemini

Los tamaños y campos no admitidos deben devolver un error de validación antes de generar. Ante un 400, compare la solicitud con las capacidades devueltas para el modelo seleccionado en lugar de reintentar a ciegas.

Modos de respuesta

Respuesta síncrona

Sin Prefer: respond-async, la solicitud espera hasta completarse y devuelve el JSON estándar de OpenAI Images. Algunos modelos devuelven datos en base64 y otros devuelven una URL temporal.

{
  "created": 1780000000,
  "data": [{
    "b64_json": "iVBORw0KGgoAAA...",
    "revised_prompt": "..."
  }],
  "usage": {
    "input_tokens": 18,
    "output_tokens": 1056,
    "total_tokens": 1074
  }
}

Un modelo de imagen que no sea Gemini puede exponer Images SSE cuando admite stream: true. El último evento data: contiene el JSON de Images y va seguido de [DONE]. Mantenga el SDK oficial y las solicitudes de imagen de Gemini en el modo síncrono predeterminado.

Respuesta de tarea asíncrona

Para un modelo que admita trabajo asíncrono, envíe Prefer: respond-async. Una respuesta 202 Accepted incluye task_id y status_url; sondee hasta que el estado sea completed o failed. Un modelo puede seguir devolviendo la respuesta de forma síncrona, así que decida según el estado HTTP real.

# Envíe la solicitud e inspeccione el estado HTTP y el task_id.
curl -i https://api.essevin.com/v1/images/generations \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Una ciudad nocturna con estética cinematográfica",
    "size": "2048x2048"
  }'

# Sondee solo después de que la primera respuesta devuelva 202 y un task_id.
curl "https://api.essevin.com/v1/images/tasks?task_id=your-task-id" \
  -H "Authorization: Bearer $ESSEVIN_OPENAI_API_KEY"

Mantenga pequeña la primera validación

Solicite una imagen con la resolución útil más baja. No registre la clave API, Data URLs completas, imágenes de origen privadas ni la salida completa en base64.

Antes de publicar los recursos de comercio generados, verifique etiquetas, logotipos, texto del empaque, proporciones del producto y cualquier persona que aparezca en el resultado.

En esta página