Tutorial
Como chamar a edição imagem-para-imagem fibo-edit-1.5 pela API HiAPI: guia com curl e Python
Explicação prática de requisições executáveis para edição de imagem baseada em instruções
Nesta página
O que o endpoint imagem-para-imagem fibo-edit-1.5 faz
fibo-edit-1.5/image-to-image é um endpoint de edição de imagem orientado por instruções. Ele não descreve uma cena do zero: recebe uma imagem de referência e uma instrução em linguagem natural e devolve uma nova imagem com essa edição aplicada, mantendo o restante da composição inalterado.
Esse posicionamento afeta diretamente a forma como você projeta a requisição. A imagem de referência carrega o contexto visual — sujeito, enquadramento, iluminação, estilo — e a instrução carrega a mudança. Uma boa instrução diz explicitamente o que deve mudar e permanece silenciosa sobre o que deve ficar igual. "Substitua o céu por um pôr do sol nublado, mantendo o edifício e o primeiro plano inalterados" comunica muito mais do que "deixe mais bonito".
Uma chamada bem-sucedida produz um recurso de imagem editada. Dependendo de como o endpoint é invocado, a resposta devolve a saída gerada em um formato que você pode salvar ou buscar — consulte a referência do endpoint para conhecer a estrutura exata da resposta e os parâmetros aceitos. Trate essa referência como a única fonte autoritativa para nomes de campos, formatos de imagem aceitos e limites de tamanho, pois esses detalhes podem evoluir independentemente deste documento.
Usos típicos incluem retoque de fotos de produtos, substituição de fundo, ajustes de estilo e edições locais em que a regeneração da imagem inteira perderia fidelidade. Se a sua tarefa for gerar a partir de texto apenas, e não editar, este endpoint não é a ferramenta adequada; use um modelo de texto-para-imagem.
Uma expectativa importante a estabelecer desde cedo: a edição é, por natureza, iterativa. Sua primeira instrução raramente acerta em cheio, então organize o fluxo de trabalho em torno de iterações de baixo custo — mude uma variável por vez, mantenha a imagem de referência fixa e compare as saídas antes de avançar.
O que compõe uma requisição funcional
Antes de escrever qualquer código, mapeie as entradas de que uma requisição precisa. Cada chamada a fibo-edit-1.5/image-to-image combina quatro tipos de informação.
Autenticação
Todas as requisições passam pela interface unificada da HiAPI e carregam sua chave de API no cabeçalho Authorization. Mantenha a chave em uma variável de ambiente, nunca no código-fonte, e jamais a faça commit.
Imagem de referência
Você precisa fornecer a imagem de origem sobre a qual a edição atua. Há duas formas comuns: uma URL pública que o serviço consiga buscar, ou dados codificados em base64 embutidos no corpo JSON. URLs facilitam a iteração; base64 evita depender de hospedagem externa. Consulte a referência do endpoint para saber quais formas são aceitas e eventuais restrições de dimensão ou resolução.
Instrução de edição
É uma string em linguagem coloquial que descreve a mudança. Escreva-a no modo imperativo, indicando a região ou o elemento a alterar e o que deve ser preservado. Evite empilhar várias edições não relacionadas numa mesma instrução — separe-as em chamadas distintas, para que você consiga identificar qual delas causou um resultado ruim.
Controle de saída
Ajustes opcionais, como dimensões, formato de saída ou quantidade de imagens candidatas. Nas primeiras chamadas, mantenha os padrões; ajuste depois, de forma consciente. Cada parâmetro que você define é mais uma variável a descartar quando algo dá errado.
Assim, um corpo de requisição mínimo tem dois campos substanciais — a imagem e a instrução — envolvidos em um objeto JSON, com suas preferências de saída opcionalmente anexadas. Se você consegue responder "qual imagem, qual mudança, em que formato quero receber", então tem tudo para escrever a chamada.
Chamando com curl
Comece pelo curl: ele isola a camada HTTP, de modo que, se algo der errado, você sabe que o problema está na requisição e não no código da aplicação.
Primeiro, exporte sua chave:
export HIAPI_API_KEY="your-api-key"
Em seguida, envie o corpo JSON com a URL da imagem de referência e a instrução:
curl -sS https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "https://example.com/input.jpg",
"prompt": "Substitua o céu sem graça por um gradiente suave de pôr do sol; mantenha o edifício e o primeiro plano inalterados."
}'
Algumas dicas práticas:
- Confirme a URL base e o caminho na referência do endpoint, em vez de copiá-los de memória.
- Use
-sS, para que o curl fique silencioso em caso de sucesso, mas ainda exiba erros de transporte. - Se não quiser depender de hospedagem externa, codifique o arquivo em base64 e substitua o valor de
imagepela string codificada, respeitando o nome de campo indicado na referência. - Durante a exploração, passe a saída por
jq .para tornar a resposta mais legível.
Para confirmar a resposta, procure o payload ou a URL da imagem retornada e abra-a. Se o corpo da resposta contiver um objeto de erro, anote os campos type e message — eles indicarão se o problema está na imagem, na instrução ou na estrutura da requisição. Salve uma resposta bruta bem-sucedida em um arquivo; ela servirá de fixture de teste quando você escrever o cliente em Python e de evidência caso o comportamento mude no futuro.
A mesma requisição em Python
A versão em Python deve corresponder exatamente à chamada curl — mesmo caminho, mesmos cabeçalhos, mesmo corpo — para que qualquer divergência seja um bug no seu código, e não uma diferença no que você está pedindo.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
URL = "https://api.hiapi.ai/v1/fibo-edit-1.5/image-to-image"
payload = {
"image": "https://example.com/input.jpg",
"prompt": (
"Substitua o céu sem graça por um gradiente suave de pôr do sol; "
"mantenha o edifício e o primeiro plano inalterados."
),
}
response = requests.post(
URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json=payload,
timeout=120,
)
response.raise_for_status()
result = response.json()
print(result)
Enviando um arquivo local
Se você estiver editando um arquivo no disco, codifique-o e envie a string em vez da URL:
import base64
with open("input.jpg", "rb") as f:
encoded = base64.b64encode(f.read()).decode("utf-8")
payload = {
"image": encoded,
"prompt": "Transforme o fundo em um cinza neutro e limpo; mantenha o produto nítido.",
}
Antes de depender desse modo, verifique na referência do endpoint o nome exato do campo e a codificação esperada.
Armazenando a saída
Grave a imagem retornada em disco, para poder comparar iterações lado a lado e registrar qual instrução produziu qual resultado. Um pequeno utilitário que salva a saída com um nome derivado de um hash da instrução torna as comparações posteriores triviais.
Defina sempre um timeout explícito. A edição de imagens demora mais do que uma simples chamada de texto, e uma requisição sem limite de tempo deixará o processo de trabalho pendurado indefinidamente se a rede travar.
Tratando erros e repetindo com segurança
As falhas se agrupam em algumas categorias, e cada uma exige uma resposta diferente.
Erros do cliente
A requisição em si está errada: JSON malformado, campo de imagem ausente, formato de imagem não suportado, uma instrução que o modelo não consegue executar ou um problema de autenticação. Repetir esses erros como estão só desperdiça tempo e cota — eles falharão exatamente da mesma forma. Corrija a requisição. Ao encontrar esse tipo de erro, registre o corpo completo da requisição (com a parte da imagem truncada) e a mensagem de erro, e então corrija a entrada.
Limite de taxa
Você enviou requisições mais rápido do que a cota permite. A resposta correta é recuar e tentar de novo, não martelar o endpoint. Siga qualquer indicação de nova tentativa fornecida na resposta; caso contrário, use backoff exponencial.
Erros de servidor e transitórios
Timeouts, conexões redefinidas e falhas no upstream merecem nova tentativa. É aí que entra a lógica de repetição idempotente.
Estratégia prática de repetição
- Repita apenas em caso de timeout, erro de conexão e respostas de limite de taxa ou de erro de servidor.
- Use backoff exponencial com teto — por exemplo, comece com um atraso curto, dobre a cada tentativa e pare após um número pequeno e fixo de tentativas.
- Adicione jitter ao atraso, para que processos paralelos não repitam todos no mesmo instante.
- Nunca repita requisições rejeitadas por problemas de schema, formato ou instrução.
- Registre cada tentativa com o número da tentativa e o resultado, para identificar se as falhas se concentram.
import random, time, requests
def edit_with_retry(payload, attempts=4):
delay = 1.0
for i in range(attempts):
try:
r = requests.post(URL, headers=HEADERS, json=payload, timeout=120)
except (requests.Timeout, requests.ConnectionError):
pass
else:
if r.status_code < 400:
return r.json()
if r.status_code not in (429, 500, 502, 503, 504):
r.raise_for_status()
time.sleep(delay + random.uniform(0, 0.5))
delay = min(delay * 2, 30)
raise RuntimeError("A edição continuou falhando após as novas tentativas")
Trate isso como um esqueleto: alinhe os códigos de status repetíveis com o que o endpoint realmente retorna e centralize a política em um só lugar, para que todos os chamadores a compartilhem.
Verificações antes de ir para produção
Antes de conectar o endpoint à produção, cumpra uma lista de verificação curta.
Valide o caminho feliz duas vezes
Execute novamente a chamada curl e o cliente Python que você salvou, com as mesmas entradas, e confirme que produzem resultados equivalentes. Se divergirem, seus corpos de requisição na verdade não são iguais.
Calibre as instruções com entradas reais
Teste suas instruções com imagens representativas, não apenas com uma única amostra. A qualidade da edição depende muito da especificidade da instrução e do quanto a imagem de referência sustenta essa mudança. Mantenha um pequeno conjunto de pares instrução-saída como suíte de testes de regressão; ao ajustar a redação, você verá o que melhorou e o que piorou.
Verifique limites e formatos
Confirme na referência do endpoint os formatos de imagem aceitos, as dimensões máximas e qualquer limite de tamanho de requisição. Faça validação local antes de enviar — rejeitar uma imagem ruim no cliente é mais rápido e mais barato do que uma ida e volta.
Confirme chaves e logs
Garanta que a chave de API venha de uma variável de ambiente, que os logs de requisição truncam o payload da imagem e que nenhuma chave apareça em relatórios de erro.
Confirme o comportamento em caso de falha
Force um timeout e um corpo de requisição malformado no ambiente de pré-produção, verifique se sua política de repetição age corretamente e se as falhas permanentes são expostas ao chamador em vez de desaparecerem silenciosamente.
Quando tudo isso passar, a integração se tornará entediante — no melhor sentido. Obtenha a lista autoritativa de parâmetros na referência do endpoint imagem-para-imagem fibo-edit-1.5 e construa a partir de uma chamada curl funcional.
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