Tutorial
Como usar gpt-image-2.6-sunburst/image-to-image via API HiAPI: prática com curl e Python
Envie imagens de referência, consulte tarefas assíncronas e depure requisições de ponta a ponta
Nesta página
Cenários de uso do gpt-image-2.6-sunburst/image-to-image
Texto para imagem entrega o resultado que o modelo produz livremente a partir do prompt. Imagem para imagem parte do material que você já tem: você fornece uma imagem de referência e uma instrução ao endpoint, e o modelo gera uma nova imagem derivada dessa referência. No HiAPI, gpt-image-2.6-sunburst/image-to-image é o endpoint dedicado a esse segundo modo.
Escolha-o quando a imagem de origem for parte do requisito — por exemplo, reformular o estilo de um material existente, ajustar iluminação ou composição, aplicar um tratamento visual a fotos de produto, ou gerar variações controladas de um design. A imagem de referência é a âncora: ela carrega o sujeito, a paleta e o layout, e seu prompt descreve a transformação, não a cena do zero. Se você não tem material de origem e só quer uma imagem a partir de uma descrição, o endpoint de texto para imagem é mais simples e dá mais liberdade ao modelo.
Duas consequências práticas definem tudo o que vem a seguir. Primeiro, a requisição carrega uma entrada quase binária (referência de imagem), o que afeta como você monta o corpo da requisição. Segundo, a geração de imagem não é instantânea, então o endpoint opera como tarefa assíncrona em vez de retornar a imagem de forma inline. Planeje as duas etapas — "enviar" e "obter" —, não uma chamada bloqueante única.
Pré-requisitos e configuração de autenticação
Antes da primeira requisição, você precisa de três coisas: uma conta HiAPI, uma chave de API e uma forma de referenciar a imagem de origem que o endpoint aceite. Crie a chave no console do HiAPI e trate-a como uma senha — ela autoriza cada chamada cobrada na sua conta.
Passe a chave como token bearer no cabeçalho Authorization. Nunca a codifique diretamente em arquivos-fonte, notebooks ou histórico de commits. Exporte-a como variável de ambiente para testes no shell e, no código da aplicação, leia-a do ambiente (ou de um gerenciador de segredos):
export HIAPI_API_KEY="your_api_key_here"
Decida antecipadamente como fornecer a imagem de referência. Normalmente você pode enviar o material para um local temporário e passar a URL, ou enviar a imagem como dados codificados em base64 no corpo da requisição. URLs deixam a requisição menor e mais fácil de registrar; base64 dispensa hospedagem extra, mas infla o corpo. Em qualquer caso, mantenha o arquivo em um formato suportado pelo endpoint e verifique os limites de tamanho antes de enviar. Anote também a URL base da API HiAPI da sua conta — todo caminho abaixo deve ser prefixado com ela.
Enviar a imagem de referência com curl
Comece no shell, assim você vê exatamente o que está sendo enviado. A chamada é um POST para o endpoint de imagem para imagem, com corpo JSON contendo a imagem de referência e a instrução.
curl -X POST "$HIAPI_BASE_URL/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1
}'
Campo a campo: model escolhe o endpoint; image carrega a imagem de referência (aqui uma URL; se você não hospedar o arquivo, uma string de dados base64); prompt é a instrução de edição, que deve descrever a mudança, não re-descrever o sujeito; n é a quantidade de saídas desejadas. Mantenha o prompt específico e delimitado — instruções que contradizem a imagem de referência tendem a produzir resultados confusos.
Envie a requisição e examine o corpo da resposta. Para um endpoint assíncrono, você não recebe a imagem pronta; recebe um identificador de tarefa ou um objeto de status. Salve essa resposta antes de continuar — ela é o handle para tudo o que vem depois. Usar curl -i para uma checagem rápida também mostra o código de status HTTP, a forma mais rápida de distinguir problema de autenticação (4xx no envio) de problema de conteúdo.
Fazer a mesma chamada em Python
Depois que a chamada no shell funcionar, porte-a para Python. A biblioteca padrão basta, mas requests deixa o exemplo mais legível:
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "gpt-image-2.6-sunburst/image-to-image",
"image": "https://your-bucket.example.com/reference.png",
"prompt": "Repaint this scene in warm sunset tones, keep the composition and objects unchanged",
"n": 1,
}
resp = requests.post(
f"{BASE_URL}/v1/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
resp.raise_for_status()
job = resp.json()
print(job)
As diferenças em relação ao curl são mecânicas: a chave vem de os.environ, o corpo é um dict serializado em JSON e raise_for_status() transforma um envio falho em exceção, em vez de erro silencioso. A última linha importa — a maior parte da dor de depuração vem de tratar uma resposta 4xx como sucesso e então ficar consultando um ID de tarefa que nunca existiu.
Para entrada binária, leia o arquivo, codifique em base64 e coloque a string em image em vez da URL. O restante do corpo permanece igual, então você pode alternar entre as formas sem mudar a lógica da requisição.
Tratar o ciclo de vida de tarefas assíncronas
A geração de imagem leva tempo, então o endpoint segue o padrão "enviar e depois consultar". Entenda os três estados e o resto é trabalho de registro.
1. Enviar e capturar a tarefa
Seu POST retorna um identificador de tarefa. Extraia-o imediatamente e persista em algum lugar — uma linha no banco, uma mensagem na fila, uma linha de log consultável. Se o seu processo cair entre o envio e a consulta, esse identificador é a única forma de recuperar o trabalho pelo qual você já pagou.
2. Consultar até a tarefa terminar
Consulte o endpoint de status com o ID da tarefa em intervalos fixos. Comece de forma conservadora — alguns segundos entre verificações — e faça backoff gradual para tarefas longas, para não martelar a API. Pare em um estado terminal: sucesso, falha ou o timeout que você mesmo definiu. Nunca consulte em loop apertado.
import time
def wait_for_job(job_id, base_url, api_key, timeout=300, interval=2):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"{base_url}/v1/images/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
if data["status"] in ("succeeded", "failed"):
return data
time.sleep(interval)
interval = min(interval * 1.5, 15)
raise TimeoutError(f"job {job_id} not finished in time")
3. Obter e armazenar o resultado
Em caso de sucesso, a resposta aponta para a imagem gerada. Se a URL for temporária, baixe-a prontamente e grave no seu próprio armazenamento com um nome sob seu controle, para que os consumidores a jusante nunca dependam de um link temporário. Registre o ID da tarefa junto com o material armazenado — é o auxílio de depuração mais barato que você tem.
Em produção, a consulta deve ser conduzida por um worker em segundo plano, não pelo handler da requisição. Uma requisição web bloqueada por toda a duração da geração de imagem é frágil e ocupa conexões sem necessidade.
Erros comuns e como corrigi-los
Quando uma chamada falha, percorra esta lista de cima para baixo; o primeiro item captura a maioria dos problemas.
401 / 403 no envio
Problema de autenticação. Verifique se a chave está no cabeçalho Authorization, se o esquema Bearer foi usado e se não há espaços em branco ou quebras de linha estranhas vindas de copiar e colar. Confirme que a variável de ambiente está realmente definida no shell ou processo que executa a requisição.
400 / 422 no corpo da requisição
Corpo malformado ou algum campo incorreto. Causas comuns: erro de sintaxe JSON por string curl manual, valor de image que não é nem URL acessível nem base64 válido, prompt ausente, ou formato de imagem não suportado. Valide o JSON localmente e confirme que a imagem de referência realmente carrega no navegador.
404 no modelo ou caminho
Caminho ou nome de modelo com erro de digitação. O identificador de modelo é uma string exata — gpt-image-2.6-sunburst/image-to-image é diferente da variante de texto para imagem e diferencia maiúsculas de minúsculas.
Timeouts e consultas travadas
Distinga tarefa lenta de tarefa ruim. Defina timeout para cada chamada HTTP, estabeleça seu próprio prazo total e registre o último estado de tarefa observado ao desistir. Se as tarefas costumam ultrapassar seu prazo, aumente-o, em vez de mudar para um loop de retentativa apertado.
Saída vazia ou inutilizável
A tarefa teve sucesso, mas a imagem não é o que você queria. Isso geralmente é problema de prompt: instrução vaga demais ou em conflito com a imagem de referência. Torne a instrução de edição mais específica sobre o que deve mudar e o que deve permanecer igual.
Recomendações de produção para pipelines de imagem para imagem
Depois que o protótipo funciona, o trabalho restante é confiabilidade e previsibilidade.
- Reexecute apenas erros reexecutáveis. Use backoff exponencial em falhas de envio causadas por 5xx e erros de rede; não reexecute 4xx às cegas, pois só falhará de novo. Controle a idempotência por conta própria vinculando a chave da tarefa ao seu próprio ID de requisição, para que uma retentativa não duplique o trabalho.
- Separe envio e consulta. Coloque o envio e a consulta em workers ou estágios diferentes. Isso desacopla a latência da sua API do tempo de geração e permite escalar a consulta de forma independente.
- Controle seu próprio armazenamento. Baixe o resultado para o seu próprio bucket assim que a tarefa terminar. Trate a URL retornada como um link temporário.
- Versione os prompts. Prompts são ativos de produção. Armazene o prompt, a imagem de referência e o ID da tarefa junto com cada saída, para que meses depois você possa reproduzir ou explicar um resultado.
- Acompanhe latência e custo. Tarefas de imagem são cobradas por saída, então limite a concorrência por usuário e registre o uso por tarefa. Monitore a latência p95 do envio até o armazenamento do material — é o número que o usuário realmente percebe.
Com o formato da requisição e o ciclo de vida definidos, o resto é engenharia de rotina. Você encontra os detalhes do modelo na documentação do HiAPI e, a partir dali, conecta o endpoint ao seu pipeline.
Artigos relacionados
Ver todos os artigos →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio