# GPT Image 2.6 Flare · Token — /images/generations

GPT Image 2.6 Flare, cobrado por tokens: el mismo modelo que `gpt-image-2.6-flare`, cobrado según el uso de tokens que informa OpenAI, al 72% de las tarifas oficiales. Las calidades `xhigh` y `max` están disponibles y `moderation: low` surte efecto; 1K / 2K / 4K, 15 proporciones, la imagen original tal como se genera, sin cargo si falla. La salida GIF aún no está disponible.

**Endpoint:** `POST https://kovapi.com/v1/images/generations`

## Inicio rápido

Tres pasos: envía un trabajo, consúltalo y toma el enlace de la imagen. Sustituye YOUR_API_KEY por tu clave y los comandos de abajo funcionan tal cual.

**Paso 1 · Envía el trabajo (devuelve al momento un id de trabajo, HTTP 202)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "Una foto de producto minimalista de una taza de cerámica blanca sobre un fondo claro, luz lateral suave", "size": "16:9", "resolution": "2K"}'
```

Respuesta (HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare-token"
}
```

**Paso 2 · Consulta cada 2–3 segundos hasta que `status` sea `succeeded` o `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Respuesta cuando sale bien

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare-token",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-flare-token"}
}
```

**Paso 3 · `data[0].url` es la imagen (PNG). Se guarda 15 días; descárgala en tu propio almacenamiento para conservarla más tiempo.**

**Ejemplo completo (Python: enviar, esperar y guardar en disco)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. enviar el trabajo
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.6-flare-token",
    "prompt": "Una foto de producto minimalista de una taza de cerámica blanca sobre un fondo claro, luz lateral suave",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. consultar cada 3 segundos hasta que termine
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. descargar la imagen
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.6-flare-token.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## Autenticación
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Parámetros de la petición

El cuerpo JSON de `POST /v1/images/generations`:

| Parámetro | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| model | string | Sí | El ID del modelo: `gpt-image-2.6-flare-token`. |
| prompt | string | Sí | Qué dibujar. En imagen a imagen, indica qué cambiar. |
| size | string | No | Proporción, una de las 15 de la tabla, p. ej. `16:9`; o un tamaño en píxeles, o `auto` (con referencias, sigue la proporción de la primera). Sin ella la imagen es 1:1. |
| resolution | string | No | Nivel: `1K` (por defecto), `2K` o `4K`. |
| quality | string | No | Calidad: `low`, `medium` (por defecto), `high`, `xhigh`, `max` o `auto` (decide el modelo). Más calidad usa más tokens: al mismo tamaño, unas 0,57 / 1 / 1,21 / 2,1 / 4,8 veces medium. |
| image / images | string / array | No | Imágenes de referencia; con una ya es imagen a imagen: `image` para una, `images` para varias (hasta 16). Enlaces públicos, data: URI o base64. |
| n | integer | No | Número de imágenes. Mejor no enviarlo: si quieres varias imágenes, envía varios trabajos a la vez. Con `n`, se retiene de entrada el precio de n imágenes y se cobran las imágenes realmente entregadas. |
| callback_url | string | No | Adónde enviar el resultado cuando termine el trabajo; consulta la sección de webhooks más abajo. |
| complexity | string | No | Profundidad de planificación: `low`, `medium` o `high`. Aún no tiene efecto en la versión cobrada por tokens (enviarlo no da error) y no cambia el precio. |
| moderation | string | No | Rigor de la moderación: `auto` (por defecto) o `low` (menos estricto, siempre dentro de la política de contenido de OpenAI). |
| output_compression | integer | No | Compresión, un entero de 0 a 100, solo para salida `jpeg` / `webp`; cuanto menor, más pequeño el archivo. |
| mask_url | string | No | Máscara para una edición parcial: un PNG del mismo tamaño que la primera referencia, transparente donde va el cambio. Requiere referencia; no se combina con `markup_url`. El modelo usa la máscara como guía, no como límite estricto. |
| markup_url | string | No | Capa de marcas: un PNG transparente con círculos o marcas donde va el cambio, sobre la primera referencia; di en el prompt qué hacer, p. ej. «pon azul el jarrón del círculo rojo y quita el círculo». Requiere referencia; no se combina con `mask_url`; hasta 16,77 megapíxeles. |

`background` puede ser `transparent` (úsalo con salida PNG o WebP); `output_format` es `png` (por defecto), `jpeg` o `webp`. `n` debe ser 1. Un parámetro que no esté en la tabla devuelve 400 `unsupported_image_parameter` al enviar y no se cobra nada; el resultado llega como `url` y `usage` incluye los tokens y el cargo del trabajo.

## Cobro por tokens

Al enviar se retiene un máximo según el tamaño, la calidad y el número de referencias; al terminar, el trabajo se liquida con el uso que informa OpenAI y el resto de la retención se devuelve al momento; un fallo se reembolsa por completo. Precios por 1M tokens:

| Concepto | Nuestro precio | Precio oficial de OpenAI |
| --- | --- | --- |
| Salida de imagen | $21.6 | $30 |
| Entrada de imagen (referencias) | $5.76 | $8 |
| Entrada de texto | $3.6 | $5 |

**Tokens de salida medidos y coste (sin entrada)**

| size | quality | output tokens | USD |
| --- | --- | --- | --- |
| 1024x1024 | low | 824 | $0.018 |
| 1024x1024 | medium | 1,449 | $0.031 |
| 1024x1024 | high | 1,758 | $0.038 |
| 1024x1024 | xhigh | 3,122 | $0.067 |
| 1024x1024 | max | 7,024 | $0.152 |
| 2048x2048 | medium | 2,944 | $0.064 |
| 2048x2048 | max | 14,272 | $0.308 |
| 3840x2160 | medium | 2,855 | $0.062 |
| 3840x2160 | max | 13,342 | $0.288 |
| 3840x1280 | medium | 1,096 | $0.024 |

Con el mismo tamaño y calidad, los tokens de salida son siempre los mismos, sea cual sea el prompt; cada referencia añade unos 700-1.600 tokens de entrada de imagen.

## Proporción, resolución y tamaño de salida

Pon la relación de aspecto en `size` y el nivel en `resolution`. Recibes la imagen original tal como se genera, sin recortes ni redimensionado, en los tamaños de abajo: ambos lados son múltiplos de 16 y 4K no pasa de 3840 px por lado ni de unos 8,3 megapíxeles.

| Proporción | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:4 | 768x1024 | 1536x2048 | 2480x3312 |
| 4:3 | 1024x768 | 2048x1536 | 3312x2480 |
| 2:3 | 672x1024 | 1360x2048 | 2336x3520 |
| 3:2 | 1024x672 | 2048x1360 | 3520x2336 |
| 9:16 | 608x1088 | 1152x2048 | 2160x3840 |
| 16:9 | 1088x608 | 2048x1152 | 3840x2160 |
| 4:5 | 816x1024 | 1632x2048 | 2576x3216 |
| 5:4 | 1024x816 | 2048x1632 | 3216x2576 |
| 1:2 | 576x1152 | 1024x2048 | 1920x3840 |
| 2:1 | 1152x576 | 2048x1024 | 3840x1920 |
| 9:21 | 544x1264 | 880x2048 | 1648x3840 |
| 21:9 | 1264x544 | 2048x880 | 3840x1648 |
| 1:3 | 480x1440 | 672x2016 | 1280x3840 |
| 3:1 | 1440x480 | 2016x672 | 3840x1280 |

- Se admiten las 15 proporciones de la tabla; cualquier otra devuelve 400 al enviar y no se cobra nada. Con `size` en `auto` y una imagen de referencia, la imagen sigue la proporción más cercana a la primera referencia; sin referencia es 1:1. Algunas proporciones largas y estrechas en 1K quedan por debajo del mínimo de píxeles del modelo y se generan con los tamaños ampliados de la tabla (16:9 es 1088×608).

- `size` también puede ser un tamaño en píxeles (p. ej. `1536x1024`) en una de las 15 proporciones: ancho y alto se redondean hacia abajo a múltiplos de 16, se reducen si superan el límite del nivel y se amplían hasta el mínimo del modelo (unos 655.000 píxeles) si son demasiado pequeños. El nivel lo marca `resolution`; sin él, el lado largo: hasta 1536 es 1K, hasta 2048 es 2K, más es 4K. Rangos del lado largo: 1K 512-1536, 2K 2016-2304, 4K 2049-4096; fuera de ellos la solicitud devuelve 400 al enviar y no se cobra nada.

## Calidad y resolución nativa

- Sin `quality` la imagen se genera en medium. La calidad solo cambia los tokens y el precio, nunca el tamaño; con `auto` decide el modelo, la retención supone `max` y el trabajo se liquida con el uso real.

- Si `quality` contiene `1K`, `2K` o `4K` y no envías `resolution`, se toma como nivel de resolución (el tamaño y el precio siguen ese nivel).

- En horas de mucha demanda los trabajos esperan en cola en lugar de fallar al momento; si tras una espera larga (unos 15 minutos) no hay imagen, el trabajo falla y se reembolsa por completo, y puedes reenviarlo tal cual.

## Imagen a imagen e imágenes de referencia

- Envía `image` (una) o `images` (varias, hasta 16; las que pasen de ahí no se usan) para imagen a imagen, y di en el prompt qué cambiar. `POST /v1/images/edits` acepta los mismos parámetros.

- Los dos endpoints solo aceptan un cuerpo JSON, no la subida de archivos multipart, así que `images.edit()` del SDK de OpenAI no se puede usar tal cual: pasa enlaces o base64 como en el ejemplo de abajo.

- Cada referencia puede ser un enlace público (http / https), un data: URI o base64, de hasta 16 MB, en PNG, JPEG o WebP; una referencia en otro formato hace fallar el trabajo y la retención se reembolsa por completo.

- La URL tiene que descargar directamente la imagen: no puede ser una página web ni estar detrás de un inicio de sesión o de una protección contra hotlinking. Una referencia que no podemos leer se rechaza al enviar con un 400 que indica cuál es y por qué; no se crea ningún trabajo y no se cobra nada.

- La proporción de salida la marca `size`, no la referencia. Para mantener la proporción original, pon esa proporción en `size`.

- Alojamos las referencias por ti y las guardamos 7 días.

**Imagen a imagen con dos referencias**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "Mantén a las personas y cambia el fondo por una playa de noche con guirnaldas de luces cálidas", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## Estado y campos del trabajo

`GET /v1/images/jobs/{id}` devuelve estos estados; cada campo se describe en [Trabajos asíncronos](https://docs.kovapi.com/es/guide/async-jobs#fields). Consulta cada 2–3 segundos o usa un webhook.

| Estado | Significado |
| --- | --- |
| queued | En cola. Incluye `queue_position` (trabajos por delante del tuyo) y `eta_seconds` (espera estimada). |
| processing | Generándose. |
| succeeded | Terminado. El resultado está en `data[0].url` y el detalle del cobro en `usage`. |
| failed | Falló. El motivo está en `error`; los créditos reservados se devuelven íntegros. |

Cada cuenta ejecuta hasta 50 trabajos a la vez; los demás esperan en orden de envío, y un trabajo que no ha empezado a los 15 minutos falla y se reembolsa íntegro. Los registros de trabajos se guardan 3 días y los enlaces de las imágenes, 15 días.

## Cuánto tarda

Normalmente 20–60 segundos desde el envío hasta el resultado; 4K, las ediciones con varias referencias y los momentos de mucha carga tardan más, y algún trabajo puede tardar uno o dos minutos.

## Errores y reembolsos

Un error al enviar se devuelve al momento como HTTP 4xx / 5xx: no se crea ningún trabajo y no se cobra nada. Un fallo después de que el trabajo fue aceptado lo informa el endpoint del trabajo, y la retención se reembolsa íntegra. Todos los códigos están en [Códigos de error](https://docs.kovapi.com/es/guide/errors).

### Errores al enviar

| HTTP | code | Causa | Qué hacer |
| --- | --- | --- | --- |
| 400 | missing_prompt | La petición a `/v1/images/generations` no lleva `prompt`. | Añade un `prompt`. |
| 400 | invalid_request | No se puede leer una imagen de referencia (enlace roto, no es una imagen, supera 16MB...; `message` indica cuál y por qué), `/v1/images/edits` no lleva imagen de referencia, el cuerpo no es un objeto JSON o `n` no es un entero. | Corrige lo que indica `message` y vuelve a enviar la petición. |
| 400 | model_not_found | El ID del modelo está mal escrito, falta `model`, o el modelo no se puede usar en este endpoint (por ejemplo, un modelo de chat en el endpoint de imágenes). | Usa un ID de modelo de `GET /v1/models` o de la [referencia de la API](https://docs.kovapi.com/es/api). |
| 401 | invalid_api_key | La clave no existe, se eliminó o está desactivada, o la cuenta está desactivada. | Revisa la clave en la página API Keys de la consola. |
| 402 | insufficient_quota | No hay saldo suficiente para retener el importe de esta petición. La pasarela retiene primero el coste máximo posible de la petición, así que una ráfaga de llamadas simultáneas también puede provocarlo. | Si se debe a una ráfaga, espera unos segundos y reintenta; si no, recarga. |
| 429 | rate_limit_exceeded | Se superó el límite de peticiones por minuto configurado en esta clave (contado sobre los últimos 60 segundos). Sin cabecera `Retry-After`. | Espera unos segundos y reintenta, o sube el límite de la clave en la consola. |
| 503 | model_maintenance | El modelo está en mantenimiento y no acepta peticiones; mientras tanto, ningún otro modelo responde en su lugar. | Reintenta cuando termine el mantenimiento; consulta el [estado del servicio](https://kovapi.com/es/status). |
| 503 | service_unavailable | Un fallo temporal de nuestro lado, por ejemplo al guardar un archivo de referencia; `/v1/responses` también responde 503, con `Retry-After`, cuando no puede atender peticiones por un momento. | Reintenta en breve. |

### Trabajos fallidos (`status` `failed`)

| code | Cuándo aparece | Qué hacer |
| --- | --- | --- |
| moderation_blocked | Imagen: el sistema de seguridad del proveedor del modelo rechazó el prompt o una imagen de referencia (el código también puede ser `content_policy_violation`). | Reescribe el prompt o cambia la referencia; si se reenvía sin cambios, normalmente se vuelve a rechazar. |
| upstream_error | Cualquier otro fallo: los reintentos automáticos no bastaron, el trabajo esperó 15 minutos sin empezar, el proveedor lo rechazó sin dar motivo, etc.; `message` indica cuál. | Volver a enviarlo suele funcionar. |

## Webhooks en lugar de consultas

Añade `callback_url` al enviar y, en cuanto termine el trabajo, con éxito o con error, la pasarela enviará a esa URL exactamente lo mismo que devuelve el endpoint de consulta, firmado y con reintentos si la entrega falla. También puedes configurar una dirección para toda la cuenta en Configuración → Webhook, en la consola. [Documentación de webhooks →](https://docs.kovapi.com/es/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "Una foto de producto minimalista de una taza de cerámica blanca sobre un fondo claro, luz lateral suave", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```