Blogue

Tutorial

Usando flux-2/image-to-image pela API HiAPI: tutorial com curl e Python

Nov 12, 2026
Imagem de capa: sobre um fundo verde-pinho profundo, alguns prismas grandes são cortados diagonalmente em blocos de cor planos, com facetas geométricas em verde-ciano e verde-neblina, simples e ordenadas.
Nesta página

O que flux-2/image-to-image faz e quando usá-lo

flux-2/image-to-image é um endpoint de edição, não um gerador puramente texto-para-imagem. Você precisa fornecer duas coisas: uma imagem de referência e uma instrução de edição escrita em linguagem natural. O modelo lê a imagem de referência como contexto visual — sujeito, composição, estilo, iluminação — e gera uma nova imagem que segue sua instrução e permanece ancorada nessa referência.

Essa distinção importa ao projetar o pipeline. Com texto-para-imagem, você descreve tudo do zero e torce para o modelo cair perto da sua intenção. Com imagem-para-imagem, você já tem um material visual e quer uma transformação controlada: reestilizar uma foto de produto, trocar o fundo, ajustar o clima da cena ou iterar o design mantendo a composição de base estável.

Cenários adequados

  • Variantes de material. Gerar vários tratamentos estilizados a partir de uma referência já aprovada.
  • Edição guiada. Aplicar mudanças pontuais (“deixe a luz mais quente”, “troque o fundo por uma parede de estúdio lisa”), sem regenerar a cena inteira.
  • Consistência de um conjunto de resultados. Reutilizar a mesma referência para que um lote de saídas compartilhe o mesmo ponto de ancoragem visual.
  • Ferramentas de colaboração humano-máquina. Permitir que o usuário envie uma imagem, descreva a alteração e receba o resultado na sua própria interface.

Cenários inadequados

  • Retoque ou composição com precisão de pixel. Este é um modelo generativo, não um editor de imagens raster.
  • Situações sem nenhuma referência — nesse caso, texto-para-imagem é um ponto de partida melhor.
  • Qualquer fluxo em que a instrução precise carregar todos os detalhes sozinha; a referência faz trabalho real, e uma referência ruim só produz resultados ruins.

Pense neste endpoint como imagem de referência + instrução -> imagem editada. Todo o tutorial se baseia nessa forma: como enviar, como ler o que volta e como manter tudo funcionando quando a rede não colabora.

Pré-requisitos e configuração de autenticação

Antes da primeira chamada, prepare três coisas.

1. Uma conta HiAPI

Cadastre-se e abra o console. Todas as requisições deste tutorial passam pela API unificada da HiAPI, então não é preciso cadastro separado em cada provedor nem instalar um SDK por provedor.

2. Uma chave de API

Crie uma chave de API no console. Trate-a como uma senha: não faça commit em repositório, não cole em código de cliente e não registre em logs. A prática padrão é carregá-la de uma variável de ambiente em tempo de execução:

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

Depois referencie HIAPI_API_KEY onde a chave for necessária. Se você faz deploy em contêiner ou plataforma serverless, defina-a como segredo nesse ambiente, em vez de embuti-la na imagem.

3. Uma imagem de referência acessível

O endpoint exige uma imagem de referência, então decida de antemão como fornecê-la. Duas formas comuns:

  • Uma URL que a API possa buscar, por exemplo um link assinado apontando para o seu próprio armazenamento de objetos.
  • Bytes codificados em Base64, enviados inline no corpo da requisição, o que evita expor URLs internas mas aumenta o tamanho do payload.

Comece com uma imagem de teste pequena — algumas centenas de KB bastam para validar a integração. Uploads grandes deixam cada retentativa mais lenta e o diagnóstico mais difícil.

Ponto de verificação

Neste ponto você deve ter uma chave armazenada em uma variável de ambiente e uma imagem de teste acessível da sua máquina. Procure manter a chave fora do histórico do shell (um arquivo .env carregado pela ferramenta costuma ser mais limpo do que um export inline na linha de comando).

Há também um hábito que vale cultivar desde já: registre IDs de requisição e tempos desde o primeiro dia. Quando a produção falha, a diferença entre uma requisição rastreável e uma não rastreável é enorme.

Montando a requisição: imagem de referência e instrução de edição

Toda chamada de imagem-para-imagem se constrói em torno de duas entradas. Acerte essas duas e o resto é encanamento.

Entrada um: a imagem de referência

A referência é a âncora. Ela diz ao modelo o que a cena contém e como ela se parece antes de qualquer edição. Dicas práticas:

  • Case a proporção com a saída desejada. Se a referência é panorâmica e você precisa de saída quadrada, espere corte ou distorção, dependendo da configuração da chamada.
  • Parta de uma imagem limpa e bem iluminada. Referência turva gera edição turva.
  • Prefira um único sujeito nítido. Colagens confusas dão ao modelo âncoras demais competindo entre si.

Entrada dois: a instrução de edição

A instrução é a descrição em linguagem natural da mudança que você quer. É daqui que vem a maior parte da diferença de qualidade. Trate-a como um prompt com uma imagem de referência anexada.

  • Declare a mudança, não a cena inteira. “Troque o fundo por uma parede de estúdio branca lisa” é melhor do que “produto sobre fundo branco” — este último induz o modelo a redesenhar tudo.
  • Diga o que deve ser preservado. Formulações como “mantenha a pose e a composição do sujeito inalteradas” reduzem bastante o desvio.
  • Seja específico sobre estilo e luz. “Luz suave de dia nublado, cores de baixa saturação” dá ao modelo mais informação útil do que “deixe mais bonito”.
  • Evite contradições. Se a referência é uma cena externa de dia e você pede um interior noturno, espere que o modelo tome uma decisão que talvez não lhe agrade.

Corpo da requisição

A requisição enviada a flux-2/image-to-image contém o identificador do modelo, a referência e a instrução. Um modelo mental útil:

{
  "model": "flux-2/image-to-image",
  "input": {
    "image": "<URL ou imagem de referência em base64>",
    "prompt": "<instrução de edição>"
  }
}

Se a referência for base64, monte um data URI conforme o schema da requisição, ou passe o encoding bruto junto com o tipo MIME. Se for URL, garanta que o link esteja publicamente acessível durante a chamada — links assinados que expiram no meio da requisição produzem falhas difíceis de entender.

Itere primeiro, integre depois

Antes de conectar qualquer coisa ao código, escreva duas ou três instruções para a mesma referência e compare as saídas. Com instruções específicas o modelo é previsível; com instruções vagas, instável; aprender isso agora custa muito menos do que em produção.

Uma requisição curl funcional

A forma mais rápida de validar chave, referência e instrução é uma chamada curl. O exemplo abaixo assume que sua chave está em HIAPI_API_KEY e que a referência é acessível por URL.

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "image": "https://your-bucket.example.com/reference.jpg",
      "prompt": "Troque o fundo por uma parede de estúdio branca lisa. Mantenha a pose, a composição e a iluminação sobre o sujeito inalteradas."
    }
  }'

Alguns pontos a observar:

  • A chave viaja no cabeçalho Authorization como token bearer. Nunca a coloque na URL.
  • Content-Type é JSON. Esquecer isso é uma causa comum de 4xx confusos.
  • O id do modelo fica no corpo da requisição, então o mesmo endpoint pode rotear para outros modelos trocando um campo.
  • A instrução é uma frase completa, não uma lista de palavras-chave. Isso é intencional — veja a seção anterior.

Lendo a saída bruta

Rode uma vez e veja a resposta inteira antes de escrever qualquer código de parsing. Se ajudar, passe por um formatador:

curl -sS -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json | python -m json.tool

Guardar o corpo da requisição em um arquivo (request.json) facilita iterar mais do que editar strings entre aspas do shell, e ainda deixa um artefato persistente para reproduzir bugs depois.

Se precisar de base64 em vez de URL

Troque o valor de image por um data URI montado a partir do seu arquivo:

python - <<'PY'
import base64, json, pathlib
data = base64.b64encode(pathlib.Path("reference.jpg").read_bytes()).decode()
body = {
    "model": "flux-2/image-to-image",
    "input": {
        "image": f"data:image/jpeg;base64,{data}",
        "prompt": "Deixe a luz mais quente e reduza um pouco o contraste.",
    },
}
pathlib.Path("request.json").write_text(json.dumps(body))
PY

Agora a mesma chamada curl funciona, porque o payload está salvo em request.json. Se a chamada der certo, você tem tudo o que precisa para passar ao Python.

A mesma chamada em Python

A versão em Python é deliberadamente sem graça: monta o mesmo dicionário, envia com os mesmos cabeçalhos e mantém endpoint e modelo em constantes, para não divergir da versão curl.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "flux-2/image-to-image"


def edit_image(reference_url: str, instruction: str, timeout: float = 60.0) -> dict:
    api_key = os.environ["HIAPI_API_KEY"]  # falha imediatamente se não estiver definida
    payload = {
        "model": MODEL,
        "input": {
            "image": reference_url,
            "prompt": instruction,
        },
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=timeout,
    )
    response.raise_for_status()
    return response.json()


if __name__ == "__main__":
    result = edit_image(
        "https://your-bucket.example.com/reference.jpg",
        "Troque o fundo por uma parede de estúdio branca lisa. "
        "Mantenha a pose, a composição e a iluminação sobre o sujeito inalteradas.",
    )
    print(result)

Por que organizar assim

  • Use os.environ["HIAPI_API_KEY"] em vez de .get(), para que a falta da chave falhe na hora, em vez de enviar uma requisição não autenticada.
  • timeout é explícito. Geração de imagem não é instantânea; uma requisição sem timeout acaba travando o worker.
  • Chame raise_for_status() antes de fazer parsing. Você quer uma exceção em 4xx ou 5xx, não um KeyError confuso em algum ponto adiante.
  • Endpoint e modelo são constantes de módulo, o que torna trivial apontar a suíte de testes para um servidor stub.

Usando entrada base64

Se você passa bytes em vez de URL, codifique o arquivo e monte o data URI no mesmo ponto em que monta o payload:

import base64, pathlib

def as_data_uri(path: str, mime: str = "image/jpeg") -> str:
    raw = pathlib.Path(path).read_bytes()
    return f"data:{mime};base64," + base64.b64encode(raw).decode()

Depois chame edit_image(as_data_uri("reference.jpg"), instruction). Separe a etapa de codificação da função de requisição, para poder testar em unidade a validação e a montagem do prompt sem tocar na rede.

Interpretando a resposta

A chamada retornou um objeto JSON. Agora extraia a imagem editada de um jeito que não quebre mesmo se a resposta ganhar campos no futuro.

Verifique, não presuma

Durante o desenvolvimento, imprima uma resposta bruta e observe onde a referência à imagem aparece — normalmente uma URL ou um payload base64 dentro da estrutura de resultado. Depois escreva accessors que verifiquem a existência, em vez de mergulhar direto em chaves aninhadas.

def extract_image_url(response: dict) -> str:
    data = response.get("data") or []
    if not data:
        raise ValueError(f"Nenhum dado de imagem na resposta: {response}")
    first = data[0]
    url = first.get("url") or first.get("b64_json")
    if not url:
        raise ValueError(f"Payload de imagem não reconhecido: {first}")
    return url

Dois hábitos desse trecho valem manter: falhar alto carregando o payload real na mensagem de erro e aceitar qualquer das duas formas (URL ou base64), em vez de codificar uma delas. O formato da resposta evolui; o leitor tolerante sobrevive.

Persista imediatamente

A URL retornada pode ser temporária. Se a imagem importa, baixe-a na mesma tarefa e guarde no seu próprio bucket:

def persist(url: str, dest: str) -> None:
    if url.startswith("data:"):
        header, b64 = url.split(",", 1)
        import base64, pathlib
        pathlib.Path(dest).write_bytes(base64.b64decode(b64))
        return
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(dest, "wb") as f:
            for chunk in r.iter_content(1 << 16):
                f.write(chunk)

A persistência também lhe dá uma chave estável para registrar no banco de dados, o que é bem mais útil do que guardar um link que pode apodrecer.

Valide o que recebeu

Verificações baratas pegam erros caros. Confirme que o arquivo não está vazio, que o magic number corresponde a algum formato de imagem e, opcionalmente, que as dimensões são as esperadas. Rejeitar imagens corrompidas ou truncadas na fronteira é muito melhor do que entregá-las ao usuário.

Registre a procedência

Armazene o id do modelo, o texto da instrução, a chave da referência e o timestamp junto com a saída. Quando alguém perguntar três semanas depois por que uma imagem ficou daquele jeito, essa linha é a resposta — e ela torna trivial repetir uma edição específica.

Retentativas e tratamento de erros em produção

Chamadas de geração de imagem falham por motivos muito diferentes, e tratá-las como uma só é o clássico bug de produção.

Distinga erros transitórios de erros finais

  • Transitórios — timeouts, conexão resetada, 429 por rate limit, respostas 5xx. A mesma requisição, repetida após uma pausa, provavelmente dará certo.
  • Finais — 400 requisição inválida, 401 chave errada ou ausente, 404 modelo desconhecido, erro de validação do payload. Repetir esses gasta tempo e dinheiro e adia a correção real.

Repita apenas os da primeira categoria. Para os da segunda, faça a tarefa falhar imediatamente e exponha a mensagem de erro — ela quase sempre indica exatamente qual campo está com problema.

Repita com backoff e jitter

import random, time, requests

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retries(fn, attempts: int = 5, base: float = 1.0):
    last = None
    for i in range(attempts):
        try:
            return fn()
        except requests.HTTPError as e:
            status = e.response.status_code if e.response is not None else None
            if status not in RETRYABLE:
                raise
            last = e
        except (requests.Timeout, requests.ConnectionError) as e:
            last = e
        delay = base * (2 ** i) + random.uniform(0, 0.5)
        time.sleep(delay)
    raise RuntimeError("tentativas esgotadas") from last

O backoff exponencial evita martelar um serviço já sobrecarregado; o jitter evita que um lote de workers repita em sincronia. Sempre limite o número de tentativas e o tempo total — loop ilimitado é pior do que falhar limpo.

Respeite o rate limit

Ao receber 429, siga qualquer dica de retentativa nos cabeçalhos da resposta antes de aplicar o backoff. Se estiver rodando lotes grandes, adicione limite de concorrência do seu lado, em vez de depender do servidor para estrangular você.

Deixe as falhas visíveis

  • Marque as retentativas com um id de tarefa único e registre cada tentativa, seu resultado e o tempo gasto.
  • Emita métricas da taxa de retentativa; um aumento lento é alerta precoce de degradação em algum ponto acima.
  • Após a última tentativa falhar, mova a tarefa para uma dead-letter queue com o corpo completo da resposta, nunca apenas uma mensagem como “failed”.

Idempotência e sensatez de custos

Uma requisição repetida pode ter dado certo no servidor mesmo que seu cliente nunca tenha visto a resposta. Se o seu produto não tolera saídas duplicadas, use um id próprio como chave da tarefa e faça reconciliação antes de repetir. E, como a chamada é cobrada por uso, cuidado com loops de retentativa inflando a conta em silêncio — um consumidor travado que repete para sempre é o bug mais caro nesse quesito.

Armadilhas comuns e próximos passos

A maior parte da dor de integração com flux-2/image-to-image vem de uma pequena lista de erros. Antes de publicar, confira seu código contra esses pontos.

  • Instrução vaga. “Melhore isso” produz resultados aleatórios; “remova o texto da placa e mantenha o formato da placa” produz resultados úteis. Especificidade é a maior alavanca de qualidade.
  • Referência inadequada. Proporção errada, fonte desfocada ou colagem confusa não se salvam com um prompt melhor.
  • URL expirada. Links assinados que morrem no meio da requisição geram falhas que parecem erro do servidor. Use validade suficientemente longa ou passe para base64.
  • Estrutura de resposta codificada na mão. Acessar chaves aninhadas diretamente transforma uma pequena mudança de schema em interrupção. Use extractors defensivos com erros claros.
  • Sem timeout. Timeout ausente ocupa um worker indefinidamente e esconde o problema real.
  • Repetir erros finais. Um 400 não se corrige sozinho. Leia a mensagem.
  • Saída perdida. Se a URL retornada é temporária e você não persistiu a imagem, você ficou sem nada.
  • Registrar segredos e prompts sem cuidado. Chaves jamais devem aparecer em logs; instruções fornecidas pelo usuário podem exigir anonimização conforme o seu domínio.

Próximos passos

Depois que o fluxo de chamada única estiver sólido, a evolução natural é: envolver a chamada em uma tarefa em background para manter a UI responsiva; armazenar pares instrução/resposta para fazer testes A/B da redação dos prompts; e, se os usuários fornecerem as próprias imagens, adicionar uma camada de moderação ou validação na entrada. Consulte a página do modelo flux-2/image-to-image e a documentação da HiAPI para ver quais parâmetros seu caso de uso pode precisar a seguir. Construa o mínimo que funciona, meça e deixe a qualidade das instruções fazer o trabalho pesado.

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