Geração de imagens GPT-Image-2.5

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": "um canto de leitura aconchegante junto a uma janela chuvosa, luz quente",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Parâmetros de solicitação inválidos",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": 402,
    "message": "Saldo insuficiente",
    "type": "payment_required"
  }
}

POST

images

generations

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": "um canto de leitura aconchegante junto a uma janela chuvosa, luz quente",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Parâmetros de solicitação inválidos",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": 402,
    "message": "Saldo insuficiente",
    "type": "payment_required"
  }
}

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.

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": "um canto de leitura aconchegante junto a uma janela chuvosa, luz quente",
    "size": "1:1",
    "resolution": "1k",
    "quality": "medium",
    "n": 1
  }'

{
  "code": 200,
  "data": [{
    "status": "submitted",
    "task_id": "task_01KXXXXXXXXXXXXXXX"
  }]
}

{
  "error": {
    "code": 400,
    "message": "Parâmetros de solicitação inválidos",
    "type": "invalid_request_error"
  }
}

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

{
  "error": {
    "code": 402,
    "message": "Saldo insuficiente",
    "type": "payment_required"
  }
}

Autenticação

string

obrigatório

Todos os endpoints usam Bearer Token. Obtenha sua chave na página de chaves de API.

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

string

obrigatório

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

string

obrigatório

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

string

padrão:"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

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

string

padrão:"1k"

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

string

padrão:"auto"

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

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.

integer

padrão:"1"

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

string

padrão:"png"

Formato: png, jpeg ou webp.

integer

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

string

Fundo: transparent, opaque ou auto.

transparent requer png ou webp; JPEG não possui canal alfa.

string

padrão:"low"

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

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.

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

Uma imagem comum em preto e branco sem canal alfa não pode ser usada diretamente como máscara. A APIMart 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.

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

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

{
  "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.

{
  "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 a cada 2–5 segundos até completed ou failed. Use POST /v1/tasks/batch para várias tarefas.

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

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

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

integer

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

array

Dados da resposta do envio.

Mostrar Item do array

string

Estado inicial: submitted.

string

ID exclusivo usado para consultar o status e o resultado.

Visão Geral

Modelos

Série de Texto

Série de Imagem

Série de Vídeo

Série de Áudio

Série de Moderação

Gerenciamento de Upload

Gerenciamento de Tarefas

Gerenciamento de Conta

Geração de imagens GPT-Image-2.5

Autenticação

Escolher um modelo

Parâmetros da solicitação

Regras de tamanho

Mapeamento de proporção e resolução

Exemplo de edição

Repintura local com máscara

Envio e consulta da tarefa

Cobrança

Limites e erros comuns

Response

​Autenticação

​Escolher um modelo

​Parâmetros da solicitação

​Regras de tamanho

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

​Exemplo de edição

​Repintura local com máscara

​Envio e consulta da tarefa

​Cobrança

​Limites e erros comuns

​Response

Autenticação

Escolher um modelo

Parâmetros da solicitação

Regras de tamanho

Mapeamento de proporção e resolução

Exemplo de edição

Repintura local com máscara

Envio e consulta da tarefa

Cobrança

Limites e erros comuns

Response