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

# Geração de imagens GPT-Image-2.5

>  - Escolha entre gpt-image-2.5-flare e gpt-image-2.5-sunburst
- Processamento assíncrono com task_id para consultar o resultado
- Texto para imagem e edição com até 16 imagens de referência
- Repintura local com máscaras PNG transparentes
- 15 proporções, dimensões exatas e resoluções 1K / 2K / 4K
- Qualidades low / medium / high / xhigh / max 

> [!NOTE]
>
> **Escolha do modelo:** `gpt-image-2.5-flare` é mais rápido e indicado para imagens cotidianas de alta qualidade, lotes e protótipos. `gpt-image-2.5-sunburst` prioriza a precisão da edição para imagens finais de produtos, anúncios e edições detalhadas em várias etapas. Os dois modelos têm o mesmo preço.

```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": "um canto de leitura aconchegante junto a uma janela chuvosa, luz quente",
    "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 solicitação inválidos",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={null}
{
  "error": {
    "code": 401,
    "message": "Falha na autenticação. Verifique sua chave de API.",
    "type": "authentication_error"
  }
}
```

```json 402 theme={null}
{
  "error": {
    "code": 402,
    "message": "Saldo insuficiente",
    "type": "payment_required"
  }
}
```

## Autenticação

**Authorization** `string` *required*

Todos os endpoints usam Bearer Token. Obtenha sua chave na [página de chaves de API](https://gccai.heqingsong.uk/keys).

```
Authorization: Bearer YOUR_API_KEY
```

## Escolher um modelo

| Modelo | Ponto forte | Uso recomendado |
| - | - | - |
| `gpt-image-2.5-flare` | Opção padrão mais rápida | Redes sociais, produtos, busca visual, protótipos e geração em lote |
| `gpt-image-2.5-sunburst` | Precisão de edição | Imagens finais de produtos, anúncios e edição detalhada em várias etapas |

Com os mesmos parâmetros, os dois modelos consomem os mesmos tokens e custam o mesmo. Em relação ao `gpt-image-2`, foram adicionados `xhigh` e `max`; `medium` e `high` usam aproximadamente um quarto dos tokens de saída dos níveis homônimos da geração anterior.

## Parâmetros da solicitação

**model** `string` *required*

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

**prompt** `string` *required*

Descrição da imagem a gerar ou editar. Informe tema, cena, composição, estilo, iluminação e o que deve ser preservado ou alterado.

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

Proporção ou dimensões exatas em pixels.

* `auto`: escolha automática pelo prompt ou referências
* Proporção: `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`
* Dimensões exatas, por exemplo `1600x1200`

> [!TIP]
>
> Na edição de imagens, omita `size` para calcular as dimensões usando a proporção da entrada e `resolution`.

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

Resolução: `1k`, `2k` ou `4k`. Ignorada quando `size` contém dimensões exatas.

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

Qualidade: `low`, `medium`, `high`, `xhigh`, `max` ou `auto`.

> [!WARNING]
>
> `xhigh` e `max` são exclusivos do GPT-Image-2.5. Enviá-los ao `gpt-image-2` retorna HTTP 400 sem redução automática.

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

Quantidade de imagens: `1` a `4`. Envie um número, não uma string.

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

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

**output\_compression** `integer`

Compressão de `0` a `100`, apenas para `jpeg` e `webp`.

**background** `string`

Fundo: `transparent`, `opaque` ou `auto`.

> [!WARNING]
>
> `transparent` requer `png` ou `webp`; JPEG não possui canal alfa.

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

Moderação: `auto` ou `low`. Se omitido, a GccAi envia `low`; um `auto` explícito é mantido.

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

URLs de referência para geração ou edição, no máximo `16`. A presença do campo ativa o modo de edição.

Apenas URLs HTTP(S) públicas são aceitas. Envie arquivos locais primeiro por `POST /v1/uploads/images` e use a `url` retornada.

**mask\_url** `string`

Máscara para repintura local. Só tem efeito quando `image_urls` também é enviado. Tanto `gpt-image-2.5-flare` quanto `gpt-image-2.5-sunburst` aceitam este parâmetro.

Envie uma única string em um dos formatos:

* URL HTTP(S) de imagem que o servidor possa baixar diretamente
* Data URL de PNG no formato `data:image/png;base64,...`

Requisitos da máscara:

* Use PNG com canal alfa transparente; PNG também é recomendado para a imagem original
* As dimensões em pixels devem ser exatamente iguais às de `image_urls[0]`. A referência é a primeira imagem de entrada, não o `size` da saída
* Pixels totalmente transparentes (`alpha=0`) indicam a área a editar; as demais áreas são usadas para preservação
* Envie uma máscara por solicitação. Com várias imagens de referência, ela se aplica apenas à primeira imagem de entrada
* O guia geral informa menos de `50 MB`, enquanto a descrição do parâmetro `mask` informa menos de `4 MB`. Até a verificação, use o limite mais rigoroso de `4 MB`

> [!WARNING]
>
> Uma imagem comum em preto e branco sem canal alfa não pode ser usada diretamente como máscara. A GccAi não adiciona o canal alfa e atualmente não valida previamente se a máscara e a imagem original têm as mesmas dimensões; o cliente deve garantir ambos os pontos.

> [!NOTE]
>
> A URL HTTP(S) deve funcionar sem Cookie ou cabeçalhos extras de autenticação. URLs assinadas devem permanecer válidas durante a fila e a execução. O limite padrão de download é `20 MB`, com timeout de `60` segundos; a implantação pode substituir esses padrões.
>
> A máscara orienta a edição, mas o modelo não garante que os pixels fora dos limites da máscara permaneçam totalmente inalterados.

## Regras de tamanho

* Largura e altura devem ser múltiplos de `16`
* Nenhum lado pode exceder `3840` pixels
* A proporção entre o lado maior e o menor deve ser no máximo `3:1`
* Total de pixels entre `655.360` e `8.294.400`

> [!WARNING]
>
> Resoluções acima de 2560×1440 são experimentais e podem ser menos estáveis.

### Mapeamento de proporção e resolução

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

Outras dimensões exatas são aceitas se cumprirem todas as regras.

## Exemplo de edição

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "preserve o produto e o texto da embalagem, troque o fundo por um estúdio branco suave e adicione uma sombra natural",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

### Repintura local com máscara

Este exemplo edita somente a área totalmente transparente da máscara. Suas dimensões devem ser iguais às de `product.png`.

```json theme={null}
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "substitua apenas a área coberta pela máscara transparente por uma fita dourada, preservando o produto e o restante do fundo",
  "image_urls": [
    "https://example.com/product.png"
  ],
  "mask_url": "https://example.com/product-mask.png",
  "quality": "xhigh"
}
```

## Envio e consulta da tarefa

Após o envio, o ID está em `data[0].task_id`. Consulte o [status da tarefa](https://gccai.heqingsong.uk/pt/api-reference/tasks/status.md) a cada 2–5 segundos até `completed` ou `failed`. Use `POST /v1/tasks/batch` para várias tarefas.

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

As URLs ficam em `data.result.images[].url[]`. Baixe e armazene os arquivos rapidamente.

| Status | Significado |
| - | - |
| `submitted` | Tarefa enviada |
| `processing` | Geração em andamento |
| `completed` | Sucesso; `result.images` disponível |
| `failed` | Falha; verifique `error.message`; a reserva é reembolsada |

## Cobrança

O GPT-Image-2.5 é cobrado pelo uso real de tokens. Consulte a [página de preços](https://gccai.heqingsong.uk/pricing) ou `/api/pricing` para o preço atual da conta.

| Item | Preço por 1 milhão de tokens |
| - | - |
| Saída de imagem | \$30.00 |
| Entrada de imagem | \$8.00 |
| Entrada de imagem em cache | \$2.00 |
| Entrada de texto | \$5.00 |
| Entrada de texto em cache | \$1.25 |

| `quality` em 1024×1024 | Tokens de saída | Custo oficial de saída |
| - | - | - |
| `low` | 196 | \$0.00588 |
| `medium` | 439 | \$0.01317 |
| `high` | 1756 | \$0.05268 |
| `xhigh` | 3122 | \$0.09366 |
| `max` | 7024 | \$0.21072 |

> [!WARNING]
>
> Com `quality: "auto"`, o serviço reserva primeiro o valor de `max` para o tamanho escolhido. Ao concluir, cobra o uso real e libera a diferença.

Para `n > 1`, a reserva aumenta linearmente. Tarefas com falha são reembolsadas automaticamente.

## Limites e erros comuns

| Item | Limite ou solução |
| - | - |
| Imagens por solicitação | 1–4 |
| Imagens de referência | Até 16 |
| Formato de saída | PNG / JPEG / WebP |
| Fundo transparente | Apenas PNG / WebP |
| Imagens parciais em streaming | Não suportado |
| Qualidade inválida | `xhigh` / `max` exigem GPT-Image-2.5 |
| Dimensões inválidas | Use múltiplos de 16 dentro dos limites de pixels e proporção |

## Response

**code** `integer`

Código de resposta; 200 quando o envio é bem-sucedido.

**data** `array`

Dados da resposta do envio.

**Item do array**

**status** `string`

Estado inicial: `submitted`.

**task\_id** `string`

ID exclusivo usado para consultar o status e o resultado.


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