> ## 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.

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

>  - Elige entre gpt-image-2.5-flare y gpt-image-2.5-sunburst
- Procesamiento asíncrono con task_id para consultar el resultado
- Texto a imagen y edición con hasta 16 imágenes de referencia
- 15 relaciones de aspecto, dimensiones exactas y resoluciones 1K / 2K / 4K
- Calidades low / medium / high / xhigh / max 

<Info>
  **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.
</Info>

<RequestExample>
  ```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.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
    }'
  ```
</RequestExample>

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

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "Parámetros de solicitud no válidos",
      "type": "invalid_request_error"
    }
  }
  ```

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

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "Saldo de la cuenta insuficiente",
      "type": "payment_required"
    }
  }
  ```
</ResponseExample>

## Autenticación

<ParamField header="Authorization" type="string" required>
  Todos los endpoints usan Bearer Token. Obtén tu clave en la [página de claves de API](https://apimart.ai/keys).

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

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

<ParamField body="model" type="string" required>
  `gpt-image-2.5-flare` o `gpt-image-2.5-sunburst`.
</ParamField>

<ParamField body="prompt" type="string" required>
  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.
</ParamField>

<ParamField body="size" type="string" default="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`

  <Tip>
    Al editar imágenes, omite `size` para calcular las dimensiones a partir de la relación de entrada y `resolution`.
  </Tip>
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  Nivel de resolución: `1k`, `2k` o `4k`. Se ignora cuando `size` contiene dimensiones exactas.
</ParamField>

<ParamField body="quality" type="string" default="auto">
  Calidad: `low`, `medium`, `high`, `xhigh`, `max` o `auto`.

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

<ParamField body="n" type="integer" default="1">
  Número de imágenes: de `1` a `4`. Envía un número, no una cadena.
</ParamField>

<ParamField body="output_format" type="string" default="png">
  Formato: `png`, `jpeg` o `webp`.
</ParamField>

<ParamField body="output_compression" type="integer">
  Compresión de `0` a `100`, solo para `jpeg` y `webp`.
</ParamField>

<ParamField body="background" type="string">
  Fondo: `transparent`, `opaque` o `auto`.

  <Warning>
    `transparent` requiere `png` o `webp`; JPEG no dispone de canal alfa.
  </Warning>
</ParamField>

<ParamField body="moderation" type="string" default="low">
  Moderación: `auto` o `low`. Si se omite, APIMart envía explícitamente `low`; un `auto` explícito se conserva.
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

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

<Warning>
  Las resoluciones superiores a 2560×1440 son experimentales y pueden ser menos estables.
</Warning>

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

```json theme={null}
{
  "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"
}
```

## Envío y consulta de tareas

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

```json theme={null}
{
  "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](https://apimart.ai/pricing) 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               |

<Warning>
  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.
</Warning>

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

<ResponseField name="code" type="integer">
  Código de respuesta; 200 cuando el envío es correcto.
</ResponseField>

<ResponseField name="data" type="array">
  Datos de la respuesta del envío.

  <Expandable title="Elemento del array">
    <ResponseField name="status" type="string">
      Estado inicial: `submitted`.
    </ResponseField>

    <ResponseField name="task_id" type="string">
      ID único para consultar el estado y el resultado.
    </ResponseField>
  </Expandable>
</ResponseField>