Integração da API do GPT Image 2.5: geração, edição e migração do Image 2

Para integrar o GPT Image 2.5 na HiAPI, primeiro escolha gpt-image-2.5-flare ou gpt-image-2.5-sunburst e depois envie a tarefa via POST /v1/tasks. Ambos os modelos oferecem geração e edição; a presença ou ausência de image_urls determina se a requisição tem imagem de referência.

Ao migrar do Image 2, é preciso alterar tanto o nome do modelo quanto os parâmetros de entrada. A versão antiga usa convenções diferentes para resolution, size, campos de imagem de referência e configuração de rota; substituir apenas a string do modelo tende a deixar parâmetros incompatíveis.

O código abaixo foi escrito com base na documentação online da HiAPI em 9 de setembro de 2026, para ilustrar a requisição e o fluxo de processamento assíncrono; os resultados e os custos reais devem ser consultados no registro da tarefa. Atualizações de parâmetros devem seguir a documentação do Flare e a documentação do Sunburst.

Um único ID de modelo cobre geração e edição

Flare e Sunburst têm os mesmos campos de requisição na HiAPI. Após escolher um modelo, na geração apenas por texto omita image_urls; na edição, inclua de 1 a 16 imagens de referência e indique no prompt o que deve ser alterado e o que deve ser preservado. Não envie um array vazio para geração apenas por texto, nem acrescente sufixos /edit ou /text-to-image por conta própria. Cada tarefa gera uma imagem.

Se você já tem um fluxo de trabalho de imagens estável, pode começar migrando um tipo de tarefa, mantendo as entradas e os critérios de aceitação originais. Para entender o posicionamento dos dois modelos, consulte primeiro as diferenças entre Image 2 e 2.5; este artigo concentra-se em como implementar a requisição.

Enviar uma requisição de geração

O exemplo abaixo gera uma foto quadrada de produto de uma caneca. Salve o JSON como request.json. O quality é definido explicitamente como medium, para facilitar a reprodução posterior dos parâmetros; aspect_ratio é definido com a dimensão em pixels listada na documentação, 1024x1024.

{
  "model": "gpt-image-2.5-flare/text-to-image",
  "input": {
    "prompt": "A studio product photograph of a matte cobalt blue ceramic mug on a warm gray seamless background. Front three-quarter view, soft light from the left, subtle contact shadow, no text, no logo.",
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

A API Key fica na variável de ambiente do servidor HIAPI_API_KEY. O comando abaixo lê o arquivo, envia a requisição e salva a resposta de criação da tarefa. O HIAPI_REQUEST_ID é gerado pela sua aplicação para esta requisição lógica; reutilize-o ao repetir a mesma requisição por problemas de rede e use um novo valor ao alterar a entrada ou criar outra imagem.

: "${HIAPI_API_KEY:?Set HIAPI_API_KEY on your server}"
: "${HIAPI_REQUEST_ID:?Set a unique ID for this logical request}"
curl --fail-with-body --silent --show-error \
  https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer ${HIAPI_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${HIAPI_REQUEST_ID}" \
  --data-binary @request.json \
  --output created.json

Após a criação bem-sucedida, leia o ID da tarefa em data.taskId de created.json. Nesse momento, a imagem ainda está sendo gerada de forma assíncrona. O Idempotency-Key serve para evitar que a mesma requisição lógica crie várias tarefas por envios repetidos; a convenção completa está na documentação de criação de tarefas. Não trate o envio bem-sucedido como imagem já concluída.

Editar imagens com a mesma interface

Abaixo há uma requisição de edição independente com o Sunburst. Substitua o endereço provisório em image_urls pela URL real de uma imagem de referência acessível pelo serviço, salve como request.json e envie com um novo ID de requisição. O endereço example.com apenas ilustra a estrutura do campo e não pode ser usado diretamente para gerar.

{
  "model": "gpt-image-2.5-sunburst/image-to-image",
  "input": {
    "prompt": "Change only the background behind the mug to pale peach. Preserve the mug shape, cobalt blue color, handle, camera angle, lighting direction, and contact shadow. Do not add text or objects.",
    "image_urls": ["https://example.com/your-mug-reference.webp"],
    "aspect_ratio": "1024x1024",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp"
  }
}

Com várias imagens de referência, indique a finalidade de cada uma na ordem do array, por exemplo, a primeira fornece o produto e a segunda fornece o fundo. Em edições encadeadas, use a saída salva na etapa anterior como imagem de referência da próxima requisição; cada etapa continua sendo uma nova tarefa, com uma nova exigência de alteração explícita. Não presuma que a interface preserve automaticamente a conversa ou a imagem da rodada anterior.

Para fundo transparente, defina background como transparent e escolha PNG ou WebP. JPEG não oferece suporte a canal de transparência. Mesmo após a saída do modelo, é preciso verificar bordas e o assunto principal; a configuração dos campos não substitui a validação da imagem.

Consultar o status e depois salvar o arquivo

GET /v1/tasks/:id retorna os detalhes da tarefa. queued, handling e archiving são estados não finais; somente success indica saída disponível, enquanto fail fornece informações de falha em data.error. O code: 200 externo indica apenas que a consulta foi bem-sucedida; é preciso continuar verificando data.status. Documentação de detalhes da tarefa

O exemplo Python abaixo usa requests, lê o created.json gerado anteriormente, espera 3 segundos e depois consulta a cada 4 segundos. Ele salva o JSON de detalhes e a primeira imagem. Os 10 minutos são o limite local de espera do exemplo; não representam SLA do serviço nem cancelam a tarefa no servidor. Após o timeout, mantenha o taskId e continue consultando a mesma tarefa mais tarde.

import json
import os
import time
from pathlib import Path

import requests

created = json.loads(Path("created.json").read_text())
if created.get("code") != 200:
    raise RuntimeError(created)
task_id = created["data"]["taskId"]
headers = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"}
deadline = time.monotonic() + 600
delay = 3

while time.monotonic() < deadline:
    time.sleep(delay)
    response = requests.get(
        f"https://api.hiapi.ai/v1/tasks/{task_id}",
        headers=headers, timeout=30,
    )
    if response.status_code == 503:
        delay = min(delay * 2, 30)
        continue
    response.raise_for_status()
    envelope = response.json()
    if envelope.get("code") != 200:
        raise RuntimeError(envelope)
    task = envelope["data"]
    Path("task-detail.json").write_text(json.dumps(envelope, indent=2))
    status = task["status"]
    if status == "fail":
        raise RuntimeError(task.get("error"))
    if status == "success":
        image = next(x for x in task["output"] if x["type"] == "image")
        # This example requested WebP. Do not forward the API key to the CDN.
        with requests.get(image["url"], stream=True, timeout=60) as result:
            result.raise_for_status()
            with Path("result.webp").open("wb") as output:
                for chunk in result.iter_content(1024 * 1024):
                    output.write(chunk)
        print("Saved result.webp", task_id)
        break
    if status not in {"queued", "handling", "archiving"}:
        raise RuntimeError(f"Unexpected status: {status}")
    delay = 4
else:
    raise TimeoutError(f"Resume polling this task later: {task_id}")

Saídas temporárias precisam ser baixadas ou transferidas antes de output[].expireAt. Serviços em produção podem configurar callback no nível superior da requisição para receber notificações de estado final, mantendo o polling como alternativa; não coloque campos de callback dentro de input. A verificação de assinatura do callback e o tratamento de notificações repetidas devem seguir a API assíncrona unificada. O exemplo não inclui fila de negócio, serviço de callback ou estratégia completa de repetição de rede.

Migrar do Image 2 verificando a entrada item a item

A versão antiga do Image 2 usa rotas diferentes; ao migrar, primeiro confirme qual delas está sendo usada atualmente. A tabela abaixo lista diferenças de parâmetros entre as documentações da HiAPI e não se aplica a converter diretamente requisições de SDK de outros provedores sem adaptação.

Fluxo antigo	Ajuste no Image 2.5
Geração e edição usam IDs de modelo Image 2 diferentes	Use o ID completo do Flare ou do Sunburst; diferencie pela presença ou ausência de image_urls
Edição Standard usa input_urls	Mude para image_urls; a antiga edição ext já usava este campo
Standard / ext usam resolution	Escolha novamente em aspect_ratio a proporção ou enumeração em pixels conforme o tamanho desejado; não mantenha resolution
Geração Beta usa size	Mude para a enumeração em pixels de aspect_ratio suportada pela documentação; não copie dimensões arbitrárias
route: "beta" / "ext" explícito, ou nome do modelo com sufixo de rota	Reconstrua a requisição conforme a documentação do modelo 2.5; não reaproveite rotas antigas
Proporções como 4:5 suportadas na versão antiga	Verifique item a item; a enumeração atual do 2.5 não tem 4:5; não troque silenciosamente por outra proporção
Dependência de qualidade, tamanho ou formato de saída padrão	Especifique explicitamente e revalide a saída, os custos e o processamento de arquivos downstream

As opções atuais de proporção do 2.5 são 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16 e auto. Além disso, aspect_ratio aceita os 10 tamanhos em pixels listados na documentação. Quando precisar de tamanho fixo, escolha um valor da enumeração; não inferir, apenas pelo formato da string, que qualquer widthxheight é aceito. Em especial, auto é descrito na nova documentação como o modelo escolhendo a composição adequada; não se deve herdar diretamente a suposição da rota antiga de edição de “seguir a imagem de entrada”.

As opções de qualidade são low, medium, high, xhigh, max e auto, com padrão medium. Níveis de qualidade com o mesmo nome não garantem o mesmo custo ou resultado visual dos modelos antigos. O protocolo antigo completo pode ser comparado nas documentações de geração do Image 2 e de edição do Image 2.

Erros e orçamento na mesma cadeia de validação

Um 400 no envio deve levar a verificar o nome do modelo, os campos e as enumerações; um 402, o saldo; um 415, o Content-Type. Se já houver uma tarefa criada com fail, salve data.error para diagnóstico e não reenvie a mesma entrada inválida. Um 503 permite repetir mais tarde com backoff; se o POST for interrompido por rede e não for possível saber se a tarefa foi criada, use a mesma chave de idempotência para evitar tarefas duplicadas. Descrição de erros na criação de tarefas

A verificação de custos começa na página de preços atual da HiAPI e na página do modelo específico. A validação da migração deve registrar o modelo completo, tamanho, qualidade, quantidade de imagens de referência, requisição, saída e fatura real; não reaproveite o preço unitário do Image 2 antigo nem trate o preço inicial de outra plataforma como cotação da HiAPI. Imagens de exemplo no site ajudam a avaliar o resultado, mas o tempo de API e a fatura precisam de registros próprios.

Depois de integrar, salvar e validar uma tarefa de geração e uma de edição, amplie para processos em lote. Consulte a página do modelo Flare ou a página do modelo Sunburst para ver o ponto de entrada atual e manter os parâmetros conforme o respectivo Docs.