Como usar gpt-image-2.5-sunburst/image-to-image com a API HiAPI: curl e Python

O que o endpoint de imagem para imagem oferece

O endpoint gpt-image-2.5-sunburst/image-to-image segue uma convenção simples: você envia uma imagem de referência mais uma instrução de edição em linguagem natural, e o modelo retorna uma nova imagem com essa instrução aplicada, ao mesmo tempo ancorada na imagem de referência. Diferente do texto para imagem — que parte do zero e depende inteiramente do seu prompt —, a imagem para imagem usa a imagem de referência como contexto visual: composição, sujeito, estilo e pistas de cor são herdados, a menos que sua instrução peça explicitamente para alterá-los.

Isso o torna a escolha certa para cenários em que você já tem material pronto e deseja uma transformação controlada, como estilizar uma foto de produto, mudar a iluminação ou o fundo, ajustar a aparência do sujeito ou gerar variações de um conceito existente. Quando você não tem material de origem e deseja máxima liberdade criativa, escolha texto para imagem; quando a fidelidade a uma imagem existente importa mais que a novidade, escolha imagem para imagem.

O modelo mental essencial para o desenvolvedor: a imagem de referência é uma restrição de entrada, e a instrução de edição é o incremento. Uma boa instrução descreve o que deve mudar, não tudo o que deve existir. “Troque o fundo por um degradê de estúdio limpo, mantendo o sujeito e sua sombra” funciona melhor que uma descrição completa de cena, porque a imagem de referência já fornece a cena. Tenha isso em mente ao ler a estrutura da requisição abaixo — o corpo da requisição é pequeno, mas a qualidade da instrução determina a qualidade da saída.

Preparação e estrutura da requisição

Antes da primeira chamada, confirme que você tem três coisas:

• Chave de API, emitida pela sua conta HiAPI. Mantenha-a em uma variável de ambiente, não no código-fonte.
• URL base, ou seja, a base URL da API HiAPI, consulte seu painel ou a documentação de referência da API.
• Caminho do endpoint: gpt-image-2.5-sunburst/image-to-image.

Cada requisição é um POST com corpo JSON e cabeçalho Authorization. Conceitualmente, o corpo contém três partes lógicas:

1. Seleção do modelo — o identificador do modelo desse endpoint, para que o gateway encaminhe a chamada corretamente.
2. Entrada — a imagem de referência (URL hospedada ou string de dados base64) e o texto da instrução de edição.
3. Controle de saída — quaisquer parâmetros opcionais listados na documentação do endpoint, como tamanho ou quantidade. Use apenas os parâmetros que aparecem na documentação oficial de referência; não adivinhe nomes.

Uma dica de disciplina: por ser um endpoint gerenciado, quais campos são aceitos é definido pela documentação de referência atual da API, não por inferência a partir de outras APIs de imagem. Em caso de dúvida, envie primeiro o corpo mínimo válido (model, image, prompt), confirme o retorno de uma resposta 200 e só então adicione campos opcionais um a um. Assim cada falha pode ser atribuída a uma única alteração, em vez de um corpo montado de uma vez.

Enviar a imagem de referência e a instrução de edição

Há duas formas suportadas de fornecer a imagem de referência, e a escolha depende principalmente de onde os bytes da imagem estão armazenados.

URL hospedada

Se a imagem já estiver publicamente acessível, passe sua URL diretamente. Isso mantém o corpo pequeno, a serialização rápida e é a opção mais simples durante o desenvolvimento. A URL precisa ser buscável diretamente pelo serviço — não pode estar atrás de autenticação, não pode ser uma cadeia de redirecionamentos, nem uma página HTML que por acaso contenha uma imagem.

Dados base64

Se a imagem for local ou um recurso privado, codifique-a e envie inline. O base64 infla o corpo em cerca de um terço, então imagens de origem grandes podem se aproximar do limite de tamanho. Se estiver perto do limite, reduza a resolução antes de codificar.

Armadilhas de formato e tamanho

• Use formatos convencionais (PNG, JPEG, WebP) e garanta que a extensão do arquivo corresponda aos bytes reais.
• Imagens grandes demais são a causa mais comum de rejeição de requisição. Prefira imagens de origem com dimensões razoáveis; normalmente não é preciso material em resolução total para uma edição.
• Se você montar a string base64 por conta própria, inclua o prefixo data URI apenas se os exemplos da documentação de referência da API o incluírem; caso contrário, remova-o. Misturar essas duas convenções é uma fonte comum de erros “invalid image”.

Escrever a instrução de edição

A qualidade da saída depende da instrução. Seja específico sobre o que mudar e diga claramente o que preservar. Indique o alvo (“a jaqueta”), a transformação (“recolorir em azul-marinho escuro”) e a restrição (“manter a pose da modelo e as sombras existentes”). Evite empilhar várias edições não relacionadas em uma única instrução — se precisar de mudanças independentes, divida em várias chamadas, assim cada resultado também fica mais fácil de avaliar.

Uma requisição curl executável

Abaixo está uma requisição que pode ser executada no terminal. Substitua a chave e os placeholders de imagem pelos seus próprios valores.

curl -X POST "$HIAPI_BASE_URL/gpt-image-2.5-sunburst/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": "Substitua o fundo por um degradê de estúdio neutro e suave; mantenha o sujeito, sua pose e as sombras existentes inalterados."
  }'

Item a item:

• -X POST — a operação cria uma nova imagem, por isso usa POST.
• A URL é formada pela URL base mais o caminho do endpoint; colocar a URL base em uma variável de ambiente facilita alternar entre ambientes.
• Authorization: Bearer ... — sua chave de API. Exporte-a como HIAPI_API_KEY, assim ela não aparece no histórico do shell nem nos logs.
• Content-Type: application/json — o corpo é JSON; omitir esse cabeçalho é uma causa comum de respostas 4xx confusas.
• model — o identificador do endpoint. Mantenha-o exatamente igual à documentação.
• image — a imagem de referência, aqui como URL hospedada. Para usar base64, substitua pela string de dados ou por uma variável codificada localmente.
• prompt — a instrução de edição. Mantenha apenas o que deve mudar e o que deve ser preservado.

Se quiser testar com um arquivo local sem codificar manualmente, a maioria dos shells pode montar o JSON com um pequeno script ou com jq; o importante é que o corpo final seja um JSON válido com esses campos.

A mesma requisição em Python

A versão em Python mantém o corpo exatamente igual, facilitando comparar as respostas lado a lado. Use requests:

import os
import requests

base_url = os.environ["HIAPI_BASE_URL"]
api_key = os.environ["HIAPI_API_KEY"]

payload = {
    "model": "gpt-image-2.5-sunburst/image-to-image",
    "image": "https://your-cdn.example.com/reference.png",
    "prompt": (
        "Substitua o fundo por um degradê de estúdio neutro e suave; "
        "mantenha o sujeito, sua pose e as sombras existentes inalterados."
    ),
}

response = requests.post(
    f"{base_url}/gpt-image-2.5-sunburst/image-to-image",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
print(response.json())

Dois pontos merecem atenção. Primeiro, json=payload define o tipo de conteúdo e serializa o corpo por você, eliminando toda uma classe de erros de montagem manual de JSON. Segundo, timeout=120 é intencional: a geração de imagem não é instantânea, e um cliente que espera para sempre é pior que um cliente que falha de forma limpa. Ajuste o timeout ao seu workload, mas sempre defina um.

Para usar um arquivo local, leia seus bytes, codifique em base64 e atribua o resultado a image. Com URL hospedada, mantenha a string como está. Quando a chamada curl e a chamada Python retornarem a mesma estrutura, você confirma que ambas se comportam igual e pode seguir com qualquer uma delas.

Solucionar falhas comuns de requisição

A maioria das falhas se enquadra em quatro categorias. Verifique-as na ordem abaixo, porque cada uma pode se disfarçar de outra.

Erros de autenticação

401 ou 403 quase sempre significam chave ausente, malformada ou expirada. Verifique se o cabeçalho é exatamente Authorization: Bearer <key>, confirme que não há aspas ou quebras de linha extras vindas de copiar e colar, e confirme que a variável de ambiente está realmente definida no shell ou processo que executa a requisição. Uma chave que funciona no curl mas não no Python geralmente indica uma variável não definida, não uma chave inválida.

Corpo da requisição malformado

Um 400 com informação de validação geralmente significa JSON inválido ou campo obrigatório ausente. Antes de enviar, imprima o corpo formatado, confirme que model corresponde ao identificador do endpoint e que o nome do campo da instrução de edição está igual à documentação. Ao escrever JSON à mão no curl, vírgulas finais e aspas simples são os culpados clássicos; o json= do Python evita esses problemas.

Entrada de imagem inválida ou grande demais

Se o serviço rejeitar a imagem, verifique três coisas: a URL é publicamente acessível e retorna uma imagem (não um redirecionamento ou página de erro), o formato é suportado e o corpo não ultrapassa o limite de tamanho especificado na documentação. Para entrada base64, confirme que a codificação está limpa e que a convenção do prefixo data URI corresponde ao exemplo de referência. Em caso de dúvida, reduza a resolução e tente novamente — imagens de origem menores resolvem boa parte desses erros.

Timeouts e falhas transitórias

Gerações demoradas podem ultrapassar o timeout do cliente, e respostas 429 ou 5xx indicam limitação de taxa ou problema transitório no servidor. Diferencie-as de erros do cliente: não repita um 400 sem alterações, mas 429 ou 503 são adequados para retentativa com backoff. Registre o código de status e o corpo da resposta a cada falha — logs de erro claros transformam a investigação de adivinhação em verificação item a item.

Do script a um cliente reutilizável

Um script descartável prova que o endpoint funciona; um pequeno wrapper o mantém estável em um pipeline. Envolva a chamada em uma função que cuide de três coisas: requisição, timeout e política de retentativa limitada.

import os
import time
import requests

class ImageEditClient:
    def __init__(self, base_url: str, api_key: str, timeout: int = 120):
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.timeout = timeout

    def edit(self, image: str, prompt: str, retries: int = 3):
        url = f"{self.base_url}/gpt-image-2.5-sunburst/image-to-image"
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "Content-Type": "application/json",
        }
        payload = {
            "model": "gpt-image-2.5-sunburst/image-to-image",
            "image": image,
            "prompt": prompt,
        }
        last_error = None
        for attempt in range(retries):
            try:
                resp = requests.post(
                    url, headers=headers, json=payload, timeout=self.timeout
                )
            except requests.Timeout as err:
                last_error = err
                time.sleep(2 ** attempt)
                continue
            if resp.status_code in (429, 500, 502, 503, 504):
                last_error = RuntimeError(f"transient {resp.status_code}: {resp.text}")
                time.sleep(2 ** attempt)
                continue
            if resp.status_code >= 400:
                raise RuntimeError(f"request failed {resp.status_code}: {resp.text}")
            return resp.json()
        raise RuntimeError(f"exhausted retries: {last_error}")

As decisões de design importam mais que o código em si. A retentativa se aplica apenas a timeouts e códigos de status transitórios, nunca a erros de cliente 4xx, porque repetir um corpo malformado só desperdiça cota. O backoff exponencial evita que um pipeline limitado por taxa martele o endpoint repetidamente. Erros de cliente são lançados imediatamente com o corpo da resposta, para que o chamador veja exatamente o que o serviço rejeitou. E centralizar o identificador do modelo em um único lugar significa que trocar para outro endpoint de imagem no futuro exige mudar uma linha, sem vasculhar toda a base de código.

Com essa base, adicione logs estruturados a cada tentativa e verifique dimensões/formato antes de o consumidor downstream usar a resposta. Quando estiver pronto para explorar outros modelos de imagem no mesmo gateway, o catálogo de modelos da HiAPI é o lugar certo para comparar endpoints sem reescrever o cliente.