Blogue

Tutorial

Como chamar gpt-image-2.6-flare/image-to-image pela API HiAPI: curl e Python

Upload da imagem de referência, requisições síncronas e assíncronas, e como depurar uma chamada funcional

Nov 10, 2026
Imagem de capa: planos de concreto escalonados se entrecruzam sob a luz solar oblíqua, sobre um fundo cinza-quente há uma sombra cinza-azulada profunda e finas juntas em tom sálvia.
Nesta página

O que este endpoint faz e quando usar image-to-image

Modelos de geração de imagem a partir de texto são ótimos em criar cenas do zero, mas muitas tarefas de produção partem de uma imagem existente. gpt-image-2.6-flare/image-to-image é justamente o endpoint que a HiAPI oferece para esse tipo de tarefa: você envia uma imagem de referência e um prompt, e o modelo retorna uma imagem transformada que segue suas instruções e se mantém firmemente ancorada à imagem de referência.

Casos de uso típicos incluem:

  • Transferência de estilo e repintura — transformar uma foto de produto em ilustração estilizada, ou repintar uma foto em outra linguagem visual.
  • Edição e retoque — ajustar iluminação, fundo ou composição de um material existente sem precisar refotografar.
  • Geração de variantes — gerar várias variantes visuais de um design base para testes A/B ou exploração criativa.
  • Adaptação de material — ajustar o tamanho ou recompor a imagem de referência para diferentes canais, preservando seu sujeito principal.

Se sua tarefa é "descrever algo e receber uma imagem", text-to-image é a escolha mais simples. Use image-to-image apenas quando a saída precisar derivar claramente de uma imagem de entrada específica — essa imagem de referência é o sentido inteiro da chamada. No restante deste artigo, montaremos uma requisição real de ponta a ponta: primeiro com curl para provar que funciona, depois em Python para você integrá-la ao seu serviço.

Pré-requisitos e estrutura da requisição

Antes de chamar o endpoint, certifique-se de que os seguintes itens estão prontos:

  • Uma conta HiAPI e uma API key. A key é enviada como bearer token no cabeçalho Authorization. Não a envie para repositórios de código; carregue-a a partir de uma variável de ambiente (por exemplo, HIAPI_API_KEY).
  • O id do modelo. Use exatamente gpt-image-2.6-flare/image-to-image — ids de modelo diferenciam maiúsculas de minúsculas, e a barra também faz parte do identificador.
  • O caminho do endpoint. A geração de imagem fica sob as rotas de geração de imagem no host da API HiAPI. Consulte a página do modelo para obter a URL base e o caminho atuais, em vez de codificar fixamente algum host que você viu em trechos antigos.
  • Um arquivo de imagem de referência, em formato comum (PNG ou JPEG são padrões seguros). Mantenha o tamanho razoável; arquivos grandes demais deixam o upload lento e podem disparar limites de requisição.

Uma requisição gpt-image-2.6-flare/image-to-image contém três partes principais:

  1. Seletor de modelo — informa à HiAPI para qual modelo rotear a requisição.
  2. Prompt — a instrução textual que descreve a transformação desejada. Não é opcional; o prompt é o que orienta a edição.
  3. Imagem de referência — a imagem de entrada com base na qual o modelo deve processar. Como passá-la depende do método de requisição (veja a próxima seção).

Além disso, passe apenas os parâmetros documentados para esse modelo na página dele na HiAPI. Se você se pegar inventando um campo porque o nome "parece certo", pare e consulte a documentação — parâmetros desconhecidos são uma causa comum de erros 4xx confusos.

Como passar a imagem de referência

Conceitualmente, a imagem de referência é apenas mais um campo de entrada no corpo da requisição — mas o tamanho dela a torna especial. Existem duas formas práticas de enviar os bytes à API, e essa escolha afeta muito mais seu código cliente do que a própria API.

Opção A: embutida no corpo da requisição

Imagens pequenas podem ser incorporadas diretamente no payload JSON, normalmente como uma string codificada em base64. Você lê o arquivo, codifica e coloca a string no campo image da requisição. Tudo fica em uma única requisição, o que é ótimo para miniaturas, ícones e fixtures de teste.

O custo: base64 infla o payload em cerca de um terço, o codificador JSON pode não lidar com strings muito longas, e depurar corpos de requisição de vários megabytes nos logs é sofrível. Embutir é por conveniência, não para materiais grandes.

Opção B: enviar primeiro e referenciar por URL

Para qualquer coisa além de imagens pequenas, envie o arquivo primeiro para um armazenamento que você controla e passe a URL dele como referência. O corpo da requisição fica pequeno, novas tentativas custam pouco, e a mesma imagem pode ser reutilizada em várias chamadas sem reenvio.

Alguns pontos de atenção ao usar URL:

  • A URL precisa ser publicamente acessível pela API — não atrás de autenticação, não localhost, nem um link assinado que expira no meio da requisição.
  • Use um tipo de conteúdo aceito pelo modelo; se a URL retorna HTML em vez de imagem, a validação falha.
  • Prefira nomes de arquivo estáveis, para correlacionar logs entre seu armazenamento e as requisições à HiAPI.

Em qualquer uma das opções, a imagem de referência e o prompt são enviados na mesma requisição. A API não exige um handshake separado de "enviar primeiro, gerar depois" — a chamada ao modelo é uma única operação lógica.

Chamadas síncronas vs. assíncronas

Geração de imagem leva tempo, e é por isso que muitas APIs de imagem oferecem tanto o modo síncrono quanto o modo de tarefa assíncrona. A mesma troca se aplica aqui.

Síncrono

Você envia a requisição e mantém a conexão aberta até a imagem retornar. Seu código é uma linha reta: montar a requisição, POST, ler a resposta, pronto.

Use chamadas síncronas quando:

  • Você está prototipando ou depurando e quer ver o resultado completo de uma vez.
  • A requisição roda em um ambiente onde bloquear por um tempo é aceitável (ferramentas CLI, workers em background).
  • Você quer o cliente mais simples possível, sem lógica de polling.

A desvantagem é que geração longa significa conexão aberta por muito tempo, e qualquer proxy ou balanceador entre você e a API pode impor seus próprios timeouts.

Assíncrono

Você envia a requisição como uma tarefa, recebe imediatamente um identificador de tarefa e então faz polling (ou recebe callback) até a conclusão. Seu cliente precisa de uma pequena máquina de estados: enviar, aguardar, obter resultado, tratar falha.

Use chamadas assíncronas quando:

  • Você atende tráfego voltado ao usuário e não pode bloquear a thread da requisição.
  • Você gera em lote muitas imagens e quer distribuí-las em paralelo e coletar resultados.
  • Sua infraestrutura tem timeouts curtos de requisição que você não controla.

Como escolher: se alguém está esperando o resultado dentro de uma requisição web, use assíncrono. Se um script ou worker espera offline, síncrono é mais simples e serve. Não complique demais: comece síncrono e migre para assíncrono quando timeouts ou limites de concorrência reais o obrigarem.

O restante deste artigo usa o modo síncrono, porque deixa cada etapa visível, mas o corpo da requisição que você monta é o mesmo nos dois modos — só a infraestrutura ao redor muda.

Uma requisição curl funcional

Vamos montar a chamada a partir do terminal. Primeiro, defina sua key:

export HIAPI_API_KEY="your-api-key-here"

Passo 1: preparar a imagem de referência

Comece com uma imagem pequena e inequívoca, para que uma falha não deixe dúvida sobre a causa:

ls -lh reference.png
file reference.png

file deve reportar PNG image data ou JPEG image data. Se reportar outra coisa, corrija antes de continuar.

Passo 2: enviar a requisição

A requisição é um POST para o endpoint de geração de imagem, com corpo JSON contendo o modelo, seu prompt e a imagem de referência. Dependendo do método de upload escolhido, o campo image é uma URL ou uma string base64.

curl -sS -X POST "$HIAPI_BASE_URL/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png"
  }'

Sobre esses parâmetros:

  • -sS oculta a barra de progresso mas ainda mostra erros — bom para scripts.
  • Authorization: Bearer $HIAPI_API_KEY mantém a chave fora do comando em si.
  • $HIAPI_BASE_URL é definido a partir da página do modelo; não adivinhe o host.
  • Aqui o campo image usa o método de URL; para imagem embutida, substitua pela string base64.

Passo 3: ler a resposta

Adicione -i para incluir os cabeçalhos de resposta e -w '\nHTTP %{http_code}\n' para imprimir o código de status. Uma chamada bem-sucedida retorna a imagem (ou um link para ela, dependendo do formato de resposta) mais metadados. Em falha, você recebe um status 4xx ou 5xx e um corpo de erro JSON — antes de mudar qualquer outra coisa, leia o campo message.

Passo 4: canalizar a saída para um arquivo

Para obter um arquivo limpo, redirecione stdout para um arquivo e verifique novamente com file. Se a resposta for um JSON contendo uma URL, extraia essa URL e baixe-a com um segundo curl. Antes de conectar isso a qualquer automação, sempre valide que os bytes baixados são realmente uma imagem.

A versão Python da mesma requisição

A base em curl se traduz diretamente para Python. Este exemplo usa apenas a biblioteca padrão mais requests:

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "gpt-image-2.6-flare/image-to-image",
    "prompt": "Recreate this scene as a flat vector illustration with a muted palette",
    "image": "https://your-storage.example.com/reference.png",
}

response = requests.post(
    f"{BASE_URL}/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=120,
)

response.raise_for_status()
data = response.json()
print(data)

Tratar a resposta

O formato da resposta varia — ela pode conter a imagem diretamente ou uma URL. Escreva uma pequena função auxiliar para unificar os dois casos, para que o código a jusante não precise saber qual é:

def extract_image(data):
    if "url" in data:
        return requests.get(data["url"], timeout=60).content
    if "image" in data:
        import base64
        return base64.b64decode(data["image"])
    raise ValueError(f"Unexpected response shape: {list(data)}")

Tratar erros

Não deixe raise_for_status() ser seu único caminho de erro. Envolva a chamada e exponha a mensagem de erro da API:

try:
    response = requests.post(url, headers=headers, json=payload, timeout=120)
    response.raise_for_status()
    image_bytes = extract_image(response.json())
except requests.HTTPError as e:
    print("HTTP", e.response.status_code, e.response.text)
    raise
except requests.Timeout:
    print("Request timed out; consider the async job route instead")
    raise

Variante assíncrona

Para o modo assíncrono, envie a tarefa com o mesmo payload, leia o id da tarefa na resposta e depois faça polling do endpoint de status da tarefa com uma breve pausa entre tentativas. Defina um limite máximo de tentativas de polling e trate o esgotamento do orçamento como falha — nunca faça polling infinito dentro de um handler de requisição.

Diagnosticar erros comuns

A maioria das falhas se enquadra em algumas categorias. Verifique esta lista em ordem; cada passo isola uma variável.

Erros de autenticação (401 / 403)

  • HIAPI_API_KEY está realmente definida no shell ou no processo? echo $HIAPI_API_KEY deve imprimi-la.
  • O cabeçalho está exatamente como Authorization: Bearer <key> — A maiúsculo, B maiúsculo, um espaço?
  • A key foi revogada ou rotacionada? Gere-a novamente e tente com uma requisição mínima.

Payload de imagem de referência inválido

Esta é a falha mais comum, e normalmente não é culpa do modelo:

  • URL inacessível: abra a URL da imagem em um navegador de outra rede. Se retornar 404 ou redirecionar para uma página de login, a API também não conseguirá acessá-la.
  • Tipo de conteúdo errado: URLs que retornam HTML ou JSON são rejeitadas. Use curl -I <url> para confirmar que a resposta é Content-Type: image/....
  • Arquivo corrompido ou ilegível: execute file reference.png localmente. Verifique se a string base64, após decodificada, corresponde aos bytes do arquivo original.
  • Arquivo grande demais: consulte os limites de tamanho documentados na página do modelo; reduza o tamanho antes de tentar novamente.

Formato de parâmetro incorreto

  • Id de modelo digitado errado: gpt-image-2.6-flare/image-to-image precisa corresponder exatamente, incluindo a barra.
  • Prompt ausente: a instrução textual é obrigatória e não pode ser omitida.
  • Campos extras: remova qualquer parâmetro que você não encontre na documentação. Chaves desconhecidas costumam disparar 4xx.
  • Sintaxe JSON: valide seu corpo de requisição com jq . <<< "$BODY" antes de enviar.

Timeouts

Se a requisição cai antes da imagem retornar, a conexão ficou aberta por tempo demais. Encurte o prompt, reduza a imagem de referência, aumente o timeout do cliente; se o problema persistir, mude para o modo de tarefa assíncrona — gerações longas são exatamente o caso de uso do assíncrono.

Estratégia de depuração

Mude apenas uma variável por tentativa. Comece com uma imagem de referência muito pequena e inequívoca e um único prompt, prove que o pipeline funciona, depois introduza insumos reais gradualmente. Registre o corpo completo da resposta a cada falha; o campo message geralmente aponta diretamente a parte problemática da requisição.

Integrar ao seu pipeline

Depois que a base funcionar, alguns hábitos mantêm gpt-image-2.6-flare/image-to-image confiável em produção.

Valide a entrada antes da chamada. Verifique se a imagem de referência está em formato suportado, dentro do limite de tamanho e, se for URL, se está acessível. Rejeite entradas ruins na sua própria fronteira, em vez de pagar por uma ida e volta que vai falhar.

Valide a saída após a chamada. Confirme que a resposta contém bytes de imagem reais (verifique os magic numbers), e não uma página HTML de erro misturada. Uma verificação barata de cabeçalho poupa muita depuração confusa a jusante.

Retente com backoff, mas só para os erros certos. 5xx transitórios e timeouts de rede merecem retentativa com backoff exponencial e jitter; erros 4xx causados por parâmetros ruins falham exatamente do mesmo jeito sempre, então corrija a requisição em vez de retentá-la.

Prefira assíncrono para trabalho voltado ao usuário. Se alguém está esperando na página, envie a tarefa e faça polling a partir do cliente — não mantenha a requisição web aberta para uma geração longa.

Mantenha o id do modelo em configuração. Ids de modelo mudam com o tempo. Leia-os de um único ponto de configuração, para que trocar de modelo exija uma linha, não uma substituição global.

Combine com outros modelos HiAPI. Este endpoint combina naturalmente com text-to-image, formando fluxos híbridos (gerar a imagem base, depois editá-la); se seu pipeline precisar, também com etapas de upscale ou remoção de fundo. Como tudo passa pela mesma interface e autenticação HiAPI, adicionar uma etapa é apenas mais uma chamada com a mesma key.

Comece pela base em curl, migre para Python e mude para assíncrono quando o tráfego exigir. A página do modelo traz os parâmetros e limites atuais de requisição — consulte-a antes de presumir um nome de campo ou limite de tamanho.

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