> ## 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 Geração de imagens

> Gere e edite imagens de forma assíncrona com Flare e Sunburst, incluindo anotações, GIFs animados e saída SVG.

Geração, edição, GIF e SVG usam `POST /v1/images/generations`. Leia `data[0].task_id` na resposta e consulte a tarefa para obter as URLs dos arquivos.

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

## Autenticação

**Authorization** `string` *required*

Use autenticação Bearer Token. Obtenha uma chave na [página de chaves de API](https://apimart.ai/keys).

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

## Escolha do modelo

| Modelo | Uso |
| - | - |
| `gpt-image-2.6-flare` | Prioriza a velocidade para iterações rápidas; opção recomendada por padrão. |
| `gpt-image-2.6-sunburst` | Prioriza detalhes e consistência entre edições sucessivas, especialmente com qualidade `medium` / `high`. |

Os preços por token e o consumo com parâmetros idênticos são iguais. Escolha conforme a velocidade e o detalhamento necessários.

## Parâmetros da solicitação

**model** `string` *required*

Nome do modelo: `gpt-image-2.6-flare` ou `gpt-image-2.6-sunburst`.

**prompt** `string` *required*

Instruções de geração ou edição, até 32.000 caracteres. Descreva o assunto, a composição e o que deve ser alterado ou preservado.

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

Imagens estáticas e SVG aceitam 15 proporções, dimensões exatas como `1600x1200` ou `auto`. O valor explícito `auto` deixa a escolha para o provedor. Na edição, omitir o campo seleciona dimensões pela proporção da primeira imagem e por `resolution`. GIF segue as regras específicas abaixo.

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

`1k` / `2k` / `4k`, em minúsculas. Determina os pixels com um `size` de proporção; ignorado quando dimensões exatas são fornecidas.

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

`low` / `medium` / `high` / `xhigh` / `max` / `auto`. Outros valores retornam HTTP 400 no envio. Se o campo for omitido ou definido como `auto`, o modelo escolhe o nível de qualidade automaticamente. O nível pode variar e não é fixado em `low`. Especifique um nível explicitamente se precisar de uma configuração fixa.

Se o campo for omitido ou definido como `auto`, o valor do nível `max` será reservado, e a cobrança final será calculada pelo nível de qualidade efetivamente escolhido.

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

Inteiro de `1` a `4`; para GIF, indica o número de animações. SVG exige `1`. Valores explícitos como `0`, números negativos ou valores acima de `4` retornam HTTP 400 em vez de serem substituídos pelo padrão.

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

`png` / `jpeg` / `webp` / `gif` / `svg`. GIF e SVG aceitam apenas geração a partir de texto. Outros valores retornam HTTP 400 no envio.

**output\_compression** `integer`

Inteiro de `0` a `100`, apenas para `jpeg` / `webp`. Valores fora do intervalo ou o uso com `png` / `gif` / `svg` retornam HTTP 400 no envio.

**background** `string`

`transparent` / `opaque` / `auto`; se omitido, usa o padrão do provedor. `transparent` explícito exige `png` / `webp`. SVG tem fundo transparente por padrão; omita este campo para SVG.

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

Nível de moderação: `auto` / `low`. Outros valores retornam HTTP 400 no envio.

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

Até 16 imagens de referência; incluí-las ativa a edição. Use URLs HTTP(S) públicas. Envie arquivos locais primeiro pela [API de upload de imagens](https://docs.apimart.ai/pt/api-reference/uploads/images.md) e use a `url` retornada.

**mask\_url** `string`

Máscara para edição local; exige `image_urls`. Use PNG com canal alfa e as dimensões da primeira imagem; regiões totalmente transparentes indicam onde editar. Aceita URL de imagem ou Data URL PNG. Incompatível com anotações; a preservação exata dos pixels fora da máscara não é garantida.

**complexity** `string`

Intensidade de planejamento: `low` / `medium` / `high`, padrão do provedor `high`, independente de `quality`. Use `low` para alterações pontuais e `high` para texto denso, layouts ou relações complexas; pode aumentar o tempo ou introduzir alterações adicionais. Sem cobrança separada; disponível apenas em 2.6.

**safety\_identifier** `string`

Identificador estável opcional do usuário final, até 128 caracteres; recomenda-se o hash do nome ou e-mail. APIMart não o encaminha ao provedor por padrão, apenas quando o canal permite. Pode ser omitido.

## Dimensões de imagens estáticas e SVG

As dimensões exatas devem ser múltiplos de 16 nos dois eixos: lado máximo 3840, proporção entre o lado maior e menor de até 3:1 e 655.360–8.294.400 pixels no total. Resoluções acima de 2560×1440 são experimentais. A tabela é igual à do GPT-Image-2.5; não aplique esses limites diretamente a cada quadro 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 |

## Edição e máscaras

Esta solicitação edita uma área da primeira imagem. Omita `mask_url` para editar a imagem inteira conforme o prompt; omita `size` para escolher dimensões pela proporção da primeira imagem e por `resolution`. Substitua as URLs de exemplo por arquivos acessíveis.

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

## Edição guiada por anotações

Forneça `markup_url` como URL HTTPS ou Data URL Base64. O alias `markup` aceita uma string ou objeto `{"image_url":"..."}`. `file_id` não é aceito.

* Inclua `image_urls`. As anotações se aplicam à primeira imagem; as demais servem de referência.
* Use uma camada PNG transparente separada, com as mesmas dimensões da primeira imagem. Não mescle as anotações com o original.
* A primeira imagem e a camada devem ter no máximo 16.777.216 pixels cada; o arquivo da camada deve ter no máximo 50 MB.
* Não combine com `mask_url`. A camada não consome tokens de imagem, mas a solicitação pode consumir tokens de texto adicionais.

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

## GIFs animados

Defina `output_format: "gif"`. Apenas geração a partir de texto: não inclua `image_urls`, `mask_url`, `markup_url`, `markup` nem `output_compression`.

| Parâmetro | Padrão | Descrição |
| - | - | - |
| `frame_count` | `9` | Inteiro **2–16**. APIMart permite atualmente até 16 quadros, não os 64 do guia do provedor. |
| `frame_duration_ms` | `200` | Duração por quadro em milissegundos inteiros, mínimo 20, arredondada em intervalos de 10 ms. |
| `size` | `auto` | Dimensões em pixels de **cada quadro**, ambas múltiplos de 16. Omissão ou `auto` resulta atualmente em 512×512. Proporções como `1:1` não são aceitas. |

O provedor organiza os quadros em uma grade: 4×2 para 2–8 quadros, 3×3 para 9, 4×3 para 10–12 e 4×4 para 13–16. Linhas e colunas podem ser invertidas para aproximar a forma de um quadrado. A grade inteira deve ter lados de até 3840, até 8.294.400 pixels e proporção de até 3:1; caso contrário, a solicitação retorna 400.

> [!WARNING]
>
> `512x512` aceita todos os valores de 2–16 quadros; `768x768`, até 12. Mesmo 2 quadros de `1024x1024` excedem o limite lateral da grade. Cada animação é cobrada pela grade inteira; `n > 1` gera e cobra várias animações.

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

## Saída SVG

**svg** `object`

Defina `output_format: "svg"`. O modelo de imagem gera uma referência, e o modelo de texto em `svg.model` escreve o SVG.

**svg**

**model** `string` *required*

Obrigatório. Escolha um modelo com preço por tokens de texto na plataforma, como `gpt-5.4-mini` ou `gpt-5.6-sol`.

**reasoning** `object`

**reasoning**

**effort** `string`

Opcional: `none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`. Os valores aceitos dependem do modelo de texto. Recomenda-se omitir para usar o padrão do modelo.

* Somente geração por texto com `n` igual a 1. Não forneça referências, máscaras, anotações ou `output_compression`.
* `quality` e `complexity` se aplicam à imagem intermediária. A saída é um `.svg` estático sem scripts, recursos externos ou bitmaps incorporados.
* O uso de texto de `svg.model` é cobrado além da geração de imagem. Contas com contrato de preço fixo por imagem ainda não aceitam SVG; a solicitação retorna 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

Consulte a [API de status de tarefas](https://docs.apimart.ai/pt/api-reference/tasks/status.md) a cada 2–5 segundos até `completed` ou `failed`. Não reenvie a solicitação de geração durante a espera.

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

Ao concluir, leia as URLs em `data.result.images[].url[]` e baixe os arquivos prontamente. O exemplo mostra apenas os campos principais; em caso de `failed`, verifique `data.error.message`. Use `POST /v1/tasks/batch` para consultar várias tarefas.

```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 e exemplo de resposta

Na resposta de consulta da tarefa, `data.usage.svg_usage` informa o uso do modelo de texto que escreve o SVG. Os demais campos de tokens em `data.usage` pertencem ao modelo de imagem que gera a referência. Contabilize cada parte pelas regras de cobrança do modelo correspondente.

| Campo | Tipo | Descrição |
| - | - | - |
| `model` | string | Modelo de texto efetivamente usado para escrever o SVG. |
| `input_tokens` | integer | Tokens de entrada do modelo de texto. |
| `output_tokens` | integer | Tokens de saída do modelo de texto, incluindo tokens de raciocínio. |
| `reasoning_tokens` | integer | Parte dos tokens de saída usada em raciocínio; não a some novamente a `output_tokens`. |

O exemplo mostra os principais campos da resposta de uma tarefa SVG. Os números de tokens ilustram as relações entre campos e não representam um consumo fixo.

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

## Erros comuns de parâmetros

Os erros de validação abaixo retornam HTTP 400 de forma síncrona no envio. Nenhuma tarefa é criada e nenhuma cobrança é feita. Corrija os parâmetros antes de enviar novamente.

| Erro | Solução |
| - | - |
| `quality "ultra" is not supported by gpt-image-2.6-flare` | Use `low` / `medium` / `high` / `xhigh` / `max` / `auto`; outros valores, como `ultra`, não são aceitos. |
| `` `n` must be an integer from 1 to 4 `` | Defina `n` como inteiro de 1 a 4; `0`, valores negativos e acima de 4 são inválidos. |
| `output_compression must be an integer from 0 to 100` | Defina `output_compression` como inteiro de 0 a 100. |
| `output_compression is only supported with output_format jpeg or webp` | Use compressão somente com JPEG / WebP; remova o parâmetro para PNG / GIF / SVG. |
| `moderation "xxx" is not supported` | Defina `moderation` como `low` ou `auto`. |
| `markup requires image_urls` | Inclua `image_urls` e ajuste a camada à primeira imagem. |
| `markup cannot be combined with mask` | Escolha anotações ou máscara, não ambas. |
| `frame_count must be an integer from 2 to 16` | Defina `frame_count` como inteiro de 2 a 16. |
| `no supported sheet fits N GIF frames at size WxH` | Reduza o tamanho ou a quantidade de quadros; não use nomes de proporções. |
| `output_format=svg requires svg.model` | Inclua um objeto `svg` com um modelo de texto compatível. |
| `output_format=svg requires n=1` | Use `n: 1` para SVG. |
| `background=transparent requires an alpha-capable output_format` | Transparência explícita exige PNG / WebP; omita o campo para SVG. |

## Parâmetros não aceitos e cobrança

Não envie `stream`, `partial_images`, `input_fidelity`, `prompt_rewriter` nem `response_format`. O endpoint retorna tarefas assíncronas e URLs CDN, não imagens parciais em streaming ou respostas de imagem Base64. `frame_count` / `frame_duration_ms` são exclusivos de GIF; a configuração `svg`, de SVG.

Flare e Sunburst têm a mesma tabela de preços. GPT-Image-2.6 consome mais tokens em `low` / `medium` que 2.5; não reutilize estimativas antigas sem ajustes. Consulte os valores atuais na [página de preços APIMart](https://apimart.ai/pricing) ou em `/api/pricing`. Esta página não lista preços fixos.

Veja o [guia de geração de imagens da OpenAI](https://developers.openai.com/api/docs/guides/image-generation) para recursos do provedor. Para APIMart, siga os endpoints, respostas assíncronas e limites desta página.


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