Blogue

Tutorial

Como chamar fibo-2.0/image-to-image pela API da HiAPI: prática com curl e Python

Nov 13, 2026
Imagem de capa: folhas de papel cor de osso empilhadas de forma desalinhada com linhas de borda em carvão, intercaladas por uma folha de papel vermelho-ferrugem, composição plana.
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 →

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