GPT Image 2.5 | Documentação de APIs

# GPT Image 2.5

Generate images with Flare or edit reference images with Sunburst.

POST https://api.apihop.ai/openai/v1/images/generations

Use `gpt-image-2.5-flare` for fast image generation or `gpt-image-2.5-sunburst` for precise editing. Check `GET https://api.apihop.ai/v1/models` for availability with your API key.

## Request

```http
POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}
```

| Parameter | Values |
| --- | --- |
| `model` | Required: `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst` |
| `prompt` | Required text describing the image or edit |
| `n` | Integer from 1 to 4; default 1 |
| `size` | `auto`, aspect ratio, or pixel dimensions such as `1600x1200` |
| `resolution` | `1k` (default), `2k`, `4k`; ignored for exact pixel sizes |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (default) |
| `image_urls` | Up to 16 publicly accessible HTTP(S) image URLs |
| `output_format` | `png` (default), `jpeg`, `webp` |
| `output_compression` | Integer from 0 to 100 for JPEG or WebP |
| `background` | `auto`, `opaque`, `transparent`; transparent requires PNG or WebP |
| `moderation` | `low` (default), `auto` |
| `stream` | `false` (default) for JSON, `true` for SSE completion events |

Supported aspect ratios: `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`. Exact pixel dimensions must be multiples of 16, have no side above 3840 pixels, an aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. For example, square `4k` output is 2880x2880, not 4096x4096.

## Reference Images

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

References use this JSON generation endpoint. Upload local images to your own storage first. Base64 data URIs, multipart uploads, masks, and a separate `/images/edits` endpoint are outside this model's public contract.

## Response

The HTTP connection waits for completion; clients do not poll an upstream task. JSON responses include final image URLs and available token usage:

```json
{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}
```

With `stream: true`, wait for `image_generation.completed` and `[DONE]` on the same connection. Partial image previews are not guaranteed.

## Pricing

Billing uses actual text input, cached text input, image input, cached image input, and image output tokens. Both variants have the same token prices. The model catalog shows your current price and the separate OpenAI reference price. An image is not a fixed-price unit: prompt length, references, size, quality, and count affect the total. A temporary reservation is reconciled after completion. Choosing an explicit quality makes expected usage clearer.

Invalid parameters return 400; authentication failures return 401; insufficient balance returns 402. An unavailable model returns 404, rate limits return 429, and generation failures return 5xx. Do not automatically resubmit a request whose completion status is unknown.

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for error codes, streaming failures, and retry boundaries.

Use gpt-image-2.5-flare para gerar imagens rapidamente ou gpt-image-2.5-sunburst para edições precisas. Verifique a disponibilidade para sua chave com GET https://api.apihop.ai/v1/models.

Requisição

http

POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}

Parâmetro	Valores
`model`	Obrigatório: `gpt-image-2.5-flare` ou `gpt-image-2.5-sunburst`
`prompt`	Texto obrigatório descrevendo a imagem ou edição
`n`	Inteiro de 1 a 4; padrão 1
`size`	`auto`, proporção ou dimensões em pixels como `1600x1200`
`resolution`	`1k` (padrão), `2k`, `4k`; ignorado com dimensões exatas em pixels
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (padrão)
`image_urls`	Até 16 URLs de imagens HTTP(S) acessíveis publicamente
`output_format`	`png` (padrão), `jpeg`, `webp`
`output_compression`	Inteiro de 0 a 100 para JPEG ou WebP
`background`	`auto`, `opaque`, `transparent`; transparência exige PNG ou WebP
`moderation`	`low` (padrão), `auto`
`stream`	`false` (padrão) para JSON, `true` para eventos de conclusão SSE

Proporções compatíveis: 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 em pixels devem ser múltiplos de 16, sem lado maior que 3840 pixels, proporção de no máximo 3:1 e total de 655,360 a 8,294,400 pixels. Por exemplo, a saída quadrada 4k é 2880x2880, não 4096x4096.

Imagens de referência

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Referências usam este mesmo endpoint de geração JSON. Envie imagens locais primeiro para seu próprio armazenamento. URIs de dados Base64, uploads multipart, máscaras e um endpoint separado /images/edits não fazem parte do contrato público deste modelo.

Resposta

A conexão HTTP aguarda a conclusão; os clientes não consultam uma tarefa do provedor. As respostas JSON contêm URLs finais das imagens e o uso de tokens disponível:

json

{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}

Com stream: true, aguarde image_generation.completed e [DONE] na mesma conexão. Prévias parciais das imagens não são garantidas.

Preços

A cobrança usa os tokens reais de entrada de texto, entrada de texto em cache, entrada de imagem, entrada de imagem em cache e saída de imagem. As duas variantes têm os mesmos preços por token. O catálogo mostra seu preço atual e, separadamente, o preço de referência da OpenAI. Uma imagem não é uma unidade de preço fixo: tamanho do prompt, referências, dimensões, qualidade e quantidade afetam o total. Uma reserva temporária é conciliada após a conclusão. Definir a qualidade explicitamente torna o consumo esperado mais claro.

Parâmetros inválidos retornam 400, falhas de autenticação 401 e saldo insuficiente 402. Um modelo indisponível retorna 404, limites de taxa 429 e falhas de geração 5xx. Não reenvie automaticamente uma requisição com conclusão desconhecida.

Para códigos de erro, falhas de streaming e limites para novas tentativas, consulte Códigos de erro e solução de problemas.