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.

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

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

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

​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

Envio e consulta da tarefa

Cobrança

Limites e erros comuns

Response