Tutorial
Como chamar fibo-2.0/image-to-image pela API da HiAPI: prática com curl e Python
Nesta página
O papel de fibo-2.0/image-to-image no pipeline
Modelos de texto para imagem partem de um prompt; modelos de imagem para imagem partem de uma imagem que você já tem. A diferença parece pequena, mas define a posição do modelo no pipeline: fibo-2.0/image-to-image deixa de ser o primeiro passo que produz material do zero e passa a ser a etapa de edição que transforma uma imagem existente.
O fluxo típico é assim: você obtém ou gera uma imagem base, envia-a para fibo-2.0/image-to-image com instruções descrevendo a mudança desejada e entrega o resultado às etapas seguintes — revisão, composição, armazenamento ou outra chamada de modelo. Como o modelo recebe ao mesmo tempo a imagem de entrada e o prompt, ele consegue redesenhar o estilo, ajustar ou transformar as partes que você descreve preservando a composição, a posição do sujeito e a estrutura geral.
Quando escolher imagem para imagem em vez de texto para imagem
Escolha imagem para imagem quando a saída precisar manter uma relação reconhecível com uma imagem existente: redesenhar o estilo de uma foto preservando o sujeito, ajustar iluminação ou tratamento de cor, gerar variações de um material já aprovado ou limpar uma base bruta antes do uso final. Se você não tem imagem inicial e só tem uma descrição, escolha texto para imagem.
O que essa interface exige de você
A chamada é o envio de uma tarefa: você envia a imagem de entrada, o prompt e os parâmetros que deseja controlar, e a API retorna uma tarefa rastreável. Trate essa interface como uma etapa bem definida dentro de uma cadeia maior, não como um aplicativo completo de edição — preparar a imagem de entrada e tratar o resultado é responsabilidade sua.
Como a requisição é essencialmente assíncrona, o design da integração deve girar em torno disso: enviar, salvar o identificador da tarefa, fazer polling até a conclusão e então obter a referência de saída. O restante deste guia constrói exatamente esse fluxo.
Preparação antes de enviar a requisição
Antes da primeira chamada, prepare três coisas: credenciais, uma compreensão correta do formato da interface e uma imagem de entrada pronta.
Credenciais
Todas as requisições à API da HiAPI são autenticadas com uma chave de API. A chave deve ficar no lado do servidor — nunca incorpore no código do navegador nem faça commit em repositório. A prática mais limpa é ler de uma variável de ambiente, para que o mesmo código funcione localmente e em produção:
export HIAPI_API_KEY="your-api-key"
Se você ainda não tem uma chave, crie-a no console da sua conta HiAPI antes de continuar.
Formato da interface
O modelo é identificado na API da HiAPI como fibo-2.0/image-to-image. Todas as chamadas de modelo compartilham a mesma URL base e as mesmas convenções de requisição, o que significa que, uma vez tendo uma chamada funcional, trocar para outro modelo consiste principalmente em alterar o identificador do modelo e os campos do payload.
Preparar a imagem de entrada
Uma requisição de imagem para imagem precisa de uma imagem real, não de uma URL que você espera que ele consiga interpretar. Decida antes como fornecê-la: como arquivo local enviado com a requisição ou como referência aceita pela API; e confirme que o formato funciona antes de escrever o código da aplicação. As duas falhas mais comuns nas primeiras requisições são enviar um caminho que só existe no seu notebook e enviar um arquivo em formato que a interface não aceita.
Checklist prático antes de montar a chamada:
- A imagem é um arquivo real que a sua linguagem consegue ler.
- O prompt descreve a edição desejada em linguagem simples, não apenas um amontoado de palavras-chave.
- Você sabe quais parâmetros enviar e quais manter no padrão.
- A sua chave de API está disponível no ambiente que faz a requisição.
Com isso pronto, é hora da própria requisição.
Anatomia de uma requisição curl funcional
Comece pelo curl. Ele elimina toda abstração entre você e a requisição HTTP e, se algo der errado, permite determinar que o problema está na requisição, não na biblioteca cliente.
curl -X POST "https://api.hiapi.ai/v1/images/generations" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fibo-2.0/image-to-image",
"prompt": "turn the scene into a soft watercolor illustration, keep the subject and framing",
"image": "BASE64_ENCODED_IMAGE_OR_ACCEPTED_REFERENCE",
"n": 1
}'
A seguir, o papel de cada parte.
Linha de requisição
-X POST define o método. A URL é o endereço base da API da HiAPI mais o caminho de geração de imagens. Mantenha o endereço base em uma variável ou valor de configuração para evitar hardcode em vários lugares; assim, mudanças futuras exigem editar um único ponto.
Cabeçalhos
Authorization: Bearer $HIAPI_API_KEY carrega sua credencial; o shell expande a variável de ambiente exportada anteriormente, então a chave não aparece literalmente no histórico de comandos. Content-Type: application/json informa à API que o corpo deve ser interpretado como JSON. Enviar um corpo JSON sem esse cabeçalho é uma causa comum de erros difíceis de entender.
Payload
model identifica fibo-2.0/image-to-image. prompt é a sua instrução — descreva a edição, não a imagem de saída inteira, pois a imagem de entrada já carrega a estrutura. image é a forma de imagem de entrada aceita pela interface; se for embutida diretamente, é o conteúdo do arquivo codificado em base64. n controla a quantidade de saídas solicitadas; manter o padrão é o começo mais seguro.
Se a imagem for grande, embutir diretamente no comando shell fica pesado. Codifique-a primeiro em um arquivo e faça referência a ele, ou passe direto ao método Python da próxima seção — lá, ler e codificar o arquivo leva uma linha.
Ler a resposta
Não presuma que a resposta contém os bytes da imagem pronta. Execute a chamada curl e inspecione o JSON: procure o identificador da tarefa ou um campo de status para saber se a tarefa já terminou ou ainda está em execução. Capture a estrutura antes de escrever qualquer código de parsing, pois o formato da resposta determina como você fará o polling.
Portar a requisição para Python
Python torna a requisição mais fácil de manter e permite encapsulá-la em uma função reutilizável em todo o código. Abaixo, um cliente leve com a mesma requisição:
import base64
import os
import time
import requests
BASE_URL = "https://api.hiapi.ai/v1"
API_KEY = os.environ["HIAPI_API_KEY"]
def encode_image(path: str) -> str:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode("utf-8")
def submit_image_edit(image_path: str, prompt: str) -> dict:
payload = {
"model": "fibo-2.0/image-to-image",
"prompt": prompt,
"image": encode_image(image_path),
"n": 1,
}
response = requests.post(
f"{BASE_URL}/images/generations",
headers={"Authorization": f"Bearer {API_KEY}"},
json=payload,
timeout=60,
)
response.raise_for_status()
return response.json()
Por que essa estrutura
Separar encode_image de submit_image_edit deixa o tratamento de arquivos e o tratamento HTTP independentes, cada um mais fácil de testar. Ler a chave do ambiente no momento da importação faz com que a falha seja imediata se ela faltar, em vez de gerar um 401 várias camadas depois. Definir timeout explicitamente evita que uma conexão travada deixe o processo de trabalho pendurado indefinidamente.
Tratar o corpo da resposta
raise_for_status() converte falhas na camada HTTP em exceções capturáveis, com log do corpo da resposta — muito mais útil do que analisar silenciosamente um objeto de erro como se fosse sucesso. Depois de obter o JSON analisado, registre o identificador de tarefa que ele contiver e, durante o desenvolvimento, registre a resposta completa para ver exatamente quais campos existem. Não escreva o parser com base em suposições; escreva com base na resposta que você realmente observou.
Manter reutilizável
Duas pequenas melhorias logo compensam: colocar a URL base e o nome do modelo em constantes, para que outras chamadas de modelo compartilhem o cliente; e fazer a função de envio retornar uma estrutura tipada (um pequeno dataclass ou um dict com chaves conhecidas), para que o código de polling tenha um contrato estável em que se apoiar.
Lidar com o ciclo de vida assíncrono e o polling
Tarefas de imagem não terminam instantaneamente. A integração deve tratar o envio e a conclusão como dois eventos separados.
Passo 1: enviar e persistir
Depois de enviar a tarefa, guarde o identificador em um local persistente — uma linha de banco de dados, uma mensagem de fila ou, no mínimo, uma linha de log. Se o processo falhar entre o envio e a conclusão, uma tarefa não registrada é trabalho perdido. Vincule o identificador à entidade do seu sistema que é dona desse resultado, para reconciliação posterior.
Passo 2: polling com backoff
Consulte o status da tarefa em intervalos razoáveis. Um laço apertado martelando a interface de status desperdiça recursos e é o erro assíncrono mais comum:
def wait_for_job(job_id: str, interval: float = 2.0, max_wait: float = 180.0) -> dict:
deadline = time.monotonic() + max_wait
while time.monotonic() < deadline:
response = requests.get(
f"{BASE_URL}/jobs/{job_id}",
headers={"Authorization": f"Bearer {API_KEY}"},
timeout=30,
)
response.raise_for_status()
job = response.json()
if job.get("status") in {"succeeded", "failed"}:
return job
time.sleep(interval)
interval = min(interval * 1.5, 10.0)
raise TimeoutError(f"job {job_id} did not finish in {max_wait}s")
Começar com um intervalo curto e crescer mantém a responsividade das primeiras verificações e evita requisições de alta frequência por longos períodos. Um prazo rígido impede espera infinita por tarefas que nunca terminam.
Passo 3: tratar falhas como resultado normal
Uma tarefa concluída não é necessariamente uma tarefa bem-sucedida. Verifique o status antes de ler a saída e trate a falha com um ramo explícito: registre os detalhes do erro retornado pela tarefa, emita um sinal de nova tentativa para o chamador e decida se a nova tentativa deve reutilizar a mesma entrada ou regerar. Uma tarefa que expirou no cliente pode ainda estar rodando no servidor, então não reenvie às cegas sem verificar.
Passo 4: obter e armazenar o resultado
Depois que a tarefa reporta sucesso, leia a referência de saída que ela fornece e baixe-a prontamente. Se for armazenar o resultado por longo prazo, copie para o seu próprio armazenamento em vez de depender de a referência permanecer válida para sempre.
Erros comuns e como corrigi-los
A maioria das falhas se enquadra em algumas categorias previsíveis. Percorra esta lista em ordem.
Falha de autenticação
401 ou 403 quase sempre significa cabeçalho errado ou chave ausente. Confirme que o cabeçalho é exatamente Authorization: Bearer <key>, com um espaço após Bearer; e confirme que a variável de ambiente está realmente definida no processo que faz a requisição — não apenas no seu shell interativo. Colar a chave com espaço em branco no final ou aspas extras responde por boa parte desses problemas.
Payload malformado
400 ou 422 normalmente significa que a API não consegue interpretar o corpo. Verifique três coisas em ordem: se Content-Type: application/json está presente, se o JSON realmente analisa (vírgulas finais quebram isso) e se os campos obrigatórios estão com os nomes corretos. Se enviar dados de imagem em base64, confirme que é base64 válido e que o formato de arquivo subjacente é suportado — strings truncadas ou codificadas duas vezes produzem erros de validação confusos.
Erros de polling
Se a tarefa parece nunca terminar, confirme que você está consultando com o identificador realmente retornado na resposta de envio e que está lendo o campo de status correto. Um laço apertado que ignora o estado failed parece travado. Adicione um timeout rígido e registre as mudanças de estado observadas; esse log geralmente revela o problema imediatamente.
Armadilhas de parsing da resposta
Se o código lançar exceção ao ler o resultado, não adivinhe o formato da resposta. Registre primeiro o corpo bruto. Problemas comuns incluem tratar uma referência como bytes, assumir que campos só presentes em sucesso sempre existem e usar o parser do caminho de falha em uma resposta de sucesso. Construa a lógica de extração com base nas respostas que você realmente viu.
Hábito de triagem rápida
Quando algo quebrar, isole a camada: execute o comando curl com o mesmo payload. Se o curl funciona e o Python falha, o erro está no cliente; se ambos falham, o erro está na requisição. Esse teste simples economiza mais tempo do que qualquer outro hábito de depuração.
Com uma chamada funcional e um laço de polling robusto, fibo-2.0/image-to-image se torna uma etapa de edição confiável — comece pela página do modelo na HiAPI e adapte as requisições acima às suas próprias imagens.
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