Blogue

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

Nov 10, 2026
Arte de capa de um tutorial do HiAPI: camadas finas de papel que recuam em profundidade rasa em tons de creme, grafite e uma folha terracota.
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 →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API