> ## Documentation Index
> Fetch the complete documentation index at: https://gccai.heqingsong.uk/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
- Repintado local con máscaras PNG transparentes
- 15 relaciones de aspecto, dimensiones exactas y resoluciones 1K / 2K / 4K
- Calidades low / medium / high / xhigh / max 

> [!NOTE]
>
> **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.

```bash cURL theme={null}
curl --request POST \
  --url https://gccai.heqingsong.uk/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
  }'
```

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

## Autenticación

**Authorization** `string` *required*

Todos los endpoints usan Bearer Token. Obtén tu clave en la [página de claves de API](https://gccai.heqingsong.uk/keys).

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

**model** `string` *required*

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

**prompt** `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.

**size** `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`.

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

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

**quality** `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.

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

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

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

Formato: `png`, `jpeg` o `webp`.

**output\_compression** `integer`

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

**background** `string`

Fondo: `transparent`, `opaque` o `auto`.

> [!WARNING]
>
> `transparent` requiere `png` o `webp`; JPEG no dispone de canal alfa.

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

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

**image\_urls** `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.

**mask\_url** `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`

> [!WARNING]
>
> Una imagen normal en blanco y negro sin canal alfa no puede usarse directamente como máscara. GccAi 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.

> [!NOTE]
>
> 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`

> [!WARNING]
>
> 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

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

### Repintado local con máscara

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

```json theme={null}
{
  "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](https://gccai.heqingsong.uk/es/api-reference/tasks/status.md) 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.gccai.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://gccai.heqingsong.uk/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.

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

**code** `integer`

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

**data** `array`

Datos de la respuesta del envío.

**Elemento del array**

**status** `string`

Estado inicial: `submitted`.

**task\_id** `string`

ID único para consultar el estado y el resultado.


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