> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GPT-Image-2.6 Generación de imágenes

> Genera y edita imágenes de forma asíncrona con Flare y Sunburst, con anotaciones, GIF animados y salida SVG.

La generación, la edición, los GIF y los SVG usan `POST /v1/images/generations`. Lee `data[0].task_id` en la respuesta y consulta la tarea para obtener las URL de los archivos.

```bash cURL theme={null}
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.6-flare",
  "prompt": "A cozy reading nook by a rainy window, warm lamp light",
  "size": "1:1",
  "resolution": "1k",
  "quality": "medium",
  "n": 1
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.apimart.ai/v1/images/generations",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "A cozy reading nook by a rainy window, warm lamp light",
        "size": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "n": 1
    },
)
response.raise_for_status()
print(response.json()["data"][0]["task_id"])
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "model": "gpt-image-2.6-flare",
    "prompt": "A cozy reading nook by a rainy window, warm lamp light",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result.data[0].task_id);
```

```json 200 theme={null}
{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01KXXXXXXXXXXXXXXX"
    }
  ]
}
```

## Autenticación

**Authorization** `string` *required*

Usa autenticación Bearer Token. Obtén una clave en la [página de claves API](https://apimart.ai/keys).

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Elegir un modelo

| Modelo | Uso |
| - | - |
| `gpt-image-2.6-flare` | Prioriza la velocidad para iterar rápidamente; opción recomendada por defecto. |
| `gpt-image-2.6-sunburst` | Prioriza el detalle y la coherencia entre ediciones sucesivas, especialmente con calidad `medium` / `high`. |

Ambos tienen los mismos precios por token y consumo con parámetros idénticos. Elige según la velocidad y el detalle que necesites.

## Parámetros de solicitud

**model** `string` *required*

Nombre del modelo: `gpt-image-2.6-flare` o `gpt-image-2.6-sunburst`.

**prompt** `string` *required*

Instrucciones de generación o edición, hasta 32 000 caracteres. Describe el sujeto, la composición y qué modificar o conservar.

**size** `string` (default: auto)

Las imágenes estáticas y SVG admiten 15 proporciones, dimensiones exactas como `1600x1200` o `auto`. El valor explícito `auto` deja la elección al proveedor. En edición, omitir el campo selecciona dimensiones según la proporción de la primera imagen y `resolution`. Los GIF siguen las reglas específicas indicadas abajo.

**resolution** `string` (default: 1k)

`1k` / `2k` / `4k`, en minúsculas. Determina los píxeles junto con un `size` de proporción; se ignora con dimensiones exactas.

**quality** `string` (default: auto)

`low` / `medium` / `high` / `xhigh` / `max` / `auto`. Otros valores devuelven HTTP 400 al enviar la solicitud. Si se omite el campo o se usa `auto`, el modelo elige automáticamente el nivel de calidad. El nivel puede variar y no está fijado en `low`. Especifica un nivel explícito si necesitas una configuración fija.

Si se omite el campo o se usa `auto`, se reserva el importe del nivel `max` y el cargo final se calcula según el nivel de calidad realmente elegido.

**n** `integer` (default: 1)

Entero de `1` a `4`; en GIF indica la cantidad de animaciones. SVG exige `1`. Los valores explícitos `0`, negativos o superiores a `4` devuelven HTTP 400 en lugar de sustituirse por el valor predeterminado.

**output\_format** `string` (default: png)

`png` / `jpeg` / `webp` / `gif` / `svg`. GIF y SVG solo admiten generación a partir de texto. Otros valores devuelven HTTP 400 al enviar la solicitud.

**output\_compression** `integer`

Entero de `0` a `100`, solo para `jpeg` / `webp`. Los valores fuera de rango o el uso con `png` / `gif` / `svg` devuelven HTTP 400 al enviar la solicitud.

**background** `string`

`transparent` / `opaque` / `auto`; si se omite, se usa el valor del proveedor. `transparent` explícito exige `png` / `webp`. SVG tiene fondo transparente por defecto; omite este campo para SVG.

**moderation** `string` (default: low)

Nivel de moderación: `auto` / `low`. Otros valores devuelven HTTP 400 al enviar la solicitud.

**image\_urls** `string[]`

Hasta 16 imágenes de referencia; incluirlas activa la edición. Usa URL HTTP(S) públicas. Sube primero los archivos locales mediante la [API de carga de imágenes](https://docs.apimart.ai/es/api-reference/uploads/images.md) y utiliza la `url` devuelta.

**mask\_url** `string`

Máscara de edición local; requiere `image_urls`. Usa un PNG con canal alfa y las dimensiones de la primera imagen; las zonas totalmente transparentes indican dónde editar. Acepta URL de imagen o Data URL PNG. No se combina con anotaciones; no se garantiza conservar exactamente los píxeles fuera de la máscara.

**complexity** `string`

Intensidad de planificación: `low` / `medium` / `high`, con valor predeterminado del proveedor `high`, independiente de `quality`. Usa `low` para cambios puntuales y `high` para texto denso, composiciones o relaciones complejas; puede tardar más o introducir cambios adicionales. No tiene cargo independiente; solo se admite en 2.6.

**safety\_identifier** `string`

Identificador estable opcional del usuario final, hasta 128 caracteres; se recomienda un hash del nombre o correo. APIMart no lo reenvía al proveedor por defecto, solo si el canal lo permite. Omitirlo no afecta al uso.

## Dimensiones de imágenes estáticas y SVG

Las dimensiones exactas deben ser múltiplos de 16 en ambos ejes: lado máximo 3840, proporción entre lado largo y corto de hasta 3:1 y 655 360–8 294 400 píxeles totales. Las resoluciones superiores a 2560×1440 son experimentales. La tabla coincide con GPT-Image-2.5; no apliques estas restricciones directamente a cada fotograma GIF.

| `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 |

## Edición y máscaras

Esta solicitud edita una zona de la primera imagen. Omite `mask_url` para editar toda la imagen según el prompt; omite `size` para elegir dimensiones según la proporción de la primera imagen y `resolution`. Sustituye las URL de ejemplo por archivos accesibles.

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "Replace the fully transparent masked area with a gold ribbon. Preserve the product and the rest of the background.",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "resolution": "2k",
  "quality": "high",
  "complexity": "low"
}
```

## Edición guiada por anotaciones

Proporciona `markup_url` como URL HTTPS o Data URL Base64. El alias `markup` acepta una cadena o un objeto `{"image_url":"..."}`. No se admite `file_id`.

* Incluye `image_urls`. Las anotaciones se aplican a la primera imagen; las demás sirven de referencia.
* Usa una capa PNG transparente independiente con las mismas dimensiones que la primera imagen. No combines las anotaciones con el original.
* La primera imagen y la capa deben tener como máximo 16 777 216 píxeles cada una; el archivo de la capa no debe superar 50 MB.
* No combines con `mask_url`. La capa no consume tokens de imagen, pero la solicitud puede consumir tokens de texto adicionales.

```json theme={null}
{
  "model": "gpt-image-2.6-flare",
  "prompt": "Recolor the striped vase inside the red circle to solid cobalt blue ceramic. Keep everything else unchanged. Remove the red circle.",
  "image_urls": [
    "https://example.com/kitchen.webp"
  ],
  "markup_url": "https://example.com/vase-circle-overlay.png",
  "quality": "medium"
}
```

## GIF animados

Establece `output_format: "gif"`. Solo generación desde texto: no incluyas `image_urls`, `mask_url`, `markup_url`, `markup` ni `output_compression`.

| Parámetro | Predeterminado | Descripción |
| - | - | - |
| `frame_count` | `9` | Entero **2–16**. APIMart admite actualmente hasta 16 fotogramas, no los 64 de la guía del proveedor. |
| `frame_duration_ms` | `200` | Duración por fotograma en milisegundos enteros, mínimo 20, redondeada a intervalos de 10 ms. |
| `size` | `auto` | Dimensiones en píxeles de **cada fotograma**, ambas múltiplos de 16. Omitirlo o usar `auto` da actualmente 512×512. No se permiten proporciones como `1:1`. |

El proveedor organiza los fotogramas en una lámina: 4×2 para 2–8, 3×3 para 9, 4×3 para 10–12 y 4×4 para 13–16. Puede intercambiar filas y columnas para acercarse a un cuadrado. La lámina completa debe tener lados de hasta 3840, hasta 8 294 400 píxeles y proporción de hasta 3:1; de lo contrario, la solicitud devuelve 400.

> [!WARNING]
>
> `512x512` admite todos los valores de 2–16 fotogramas; `768x768`, hasta 12. Incluso 2 fotogramas de `1024x1024` superan el límite lateral de la lámina. Cada animación se factura por la lámina completa; `n > 1` genera y factura varias animaciones.

```json theme={null}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "A paper lantern swaying gently in the night breeze, seamless loop",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "quality": "low"
}
```

## Salida SVG

**svg** `object`

Establece `output_format: "svg"`. El modelo de imagen genera una referencia y el modelo de texto de `svg.model` escribe el SVG.

**svg**

**model** `string` *required*

Obligatorio. Elige un modelo con precio por tokens de texto en la plataforma, como `gpt-5.4-mini` o `gpt-5.6-sol`.

**reasoning** `object`

**reasoning**

**effort** `string`

Opcional: `none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`. Los valores admitidos dependen del modelo de texto. Se recomienda omitirlo para usar el valor predeterminado del modelo.

* Solo generación desde texto y `n` igual a 1. No se admiten referencias, máscaras, anotaciones ni `output_compression`.
* `quality` y `complexity` se aplican a la imagen intermedia. El resultado es un `.svg` estático sin scripts, recursos externos ni mapas de bits incrustados.
* El uso de texto de `svg.model` se factura además de la generación de imagen. Las cuentas con tarifa fija por imagen aún no admiten SVG; la solicitud devuelve 400.

```json theme={null}
{
  "model": "gpt-image-2.6-flare",
  "prompt": "A minimalist bakery logo with a wheat stalk, flat colors",
  "output_format": "svg",
  "svg": {
    "model": "gpt-5.4-mini"
  },
  "size": "1:1",
  "quality": "low",
  "n": 1
}
```

## Consultar resultados

Consulta la [API de estado de tareas](https://docs.apimart.ai/es/api-reference/tasks/status.md) cada 2–5 segundos hasta `completed` o `failed`. No vuelvas a enviar la solicitud de generación mientras esperas.

```bash theme={null}
curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01KXXXXXXXXXXXXXXX \
  --header 'Authorization: Bearer <token>'
```

Al terminar, lee las URL de `data.result.images[].url[]` y descarga los archivos pronto. El ejemplo muestra solo los campos principales; si aparece `failed`, revisa `data.error.message`. Usa `POST /v1/tasks/batch` para consultar varias tareas.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.png"
          ]
        }
      ]
    }
  }
}
```

### Uso de tokens SVG y ejemplo de respuesta

En la respuesta de consulta de una tarea, `data.usage.svg_usage` informa del uso del modelo de texto que escribe el SVG. Los demás campos de tokens de `data.usage` corresponden al modelo de imagen que genera la referencia. Contabiliza cada parte según las reglas de facturación de su modelo.

| Campo | Tipo | Descripción |
| - | - | - |
| `model` | string | Modelo de texto realmente utilizado para escribir el SVG. |
| `input_tokens` | integer | Tokens de entrada del modelo de texto. |
| `output_tokens` | integer | Tokens de salida del modelo de texto, incluidos los de razonamiento. |
| `reasoning_tokens` | integer | Parte de los tokens de salida destinada al razonamiento; no la sumes de nuevo a `output_tokens`. |

El ejemplo muestra los campos principales de la respuesta de una tarea SVG. Los valores de tokens ilustran las relaciones entre campos y no representan un consumo fijo.

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "task_01KXXXXXXXXXXXXXXX",
    "status": "completed",
    "progress": 100,
    "result": {
      "images": [
        {
          "url": [
            "https://upload.apimart.ai/f/image/example.svg"
          ]
        }
      ]
    },
    "usage": {
      "input_tokens": 40,
      "output_tokens": 1800,
      "total_tokens": 1840,
      "svg_usage": {
        "model": "gpt-5.4-mini",
        "input_tokens": 1200,
        "output_tokens": 800,
        "reasoning_tokens": 200
      }
    }
  }
}
```

## Errores de parámetros frecuentes

Los siguientes errores de validación devuelven HTTP 400 de forma síncrona al enviar la solicitud. No se crea ninguna tarea ni se realiza ningún cargo. Corrige los parámetros antes de volver a enviarla.

| Error | Solución |
| - | - |
| `quality "ultra" is not supported by gpt-image-2.6-flare` | Usa `low` / `medium` / `high` / `xhigh` / `max` / `auto`; no se admiten otros valores como `ultra`. |
| `` `n` must be an integer from 1 to 4 `` | Define `n` como entero de 1 a 4; `0`, los valores negativos y los superiores a 4 no son válidos. |
| `output_compression must be an integer from 0 to 100` | Define `output_compression` como entero de 0 a 100. |
| `output_compression is only supported with output_format jpeg or webp` | Usa compresión solo con JPEG / WebP; elimina el parámetro para PNG / GIF / SVG. |
| `moderation "xxx" is not supported` | Define `moderation` como `low` o `auto`. |
| `markup requires image_urls` | Incluye `image_urls` y ajusta la capa a la primera imagen. |
| `markup cannot be combined with mask` | Elige anotaciones o máscara, no ambas. |
| `frame_count must be an integer from 2 to 16` | Define `frame_count` como entero de 2 a 16. |
| `no supported sheet fits N GIF frames at size WxH` | Reduce las dimensiones o el número de fotogramas; no uses proporciones nominales. |
| `output_format=svg requires svg.model` | Incluye un objeto `svg` con un modelo de texto compatible. |
| `output_format=svg requires n=1` | Para SVG usa `n: 1`. |
| `background=transparent requires an alpha-capable output_format` | La transparencia explícita requiere PNG / WebP; omite este campo para SVG. |

## Parámetros no admitidos y facturación

No envíes `stream`, `partial_images`, `input_fidelity`, `prompt_rewriter` ni `response_format`. El endpoint devuelve tareas asíncronas y URL CDN, no imágenes parciales en streaming ni respuestas de imagen Base64. `frame_count` / `frame_duration_ms` son exclusivos de GIF; la configuración `svg`, de SVG.

Flare y Sunburst comparten tarifas. GPT-Image-2.6 consume más tokens en `low` / `medium` que 2.5; no reutilices sin cambios las estimaciones anteriores. Consulta los precios actuales en la [página de precios APIMart](https://apimart.ai/pricing) o `/api/pricing`. Aquí no se indican precios fijos.

Consulta la [guía de generación de imágenes de OpenAI](https://developers.openai.com/api/docs/guides/image-generation) para las funciones del proveedor. Al usar APIMart, aplica los endpoints, respuestas asíncronas y límites de esta página.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.