Como usar flux-2/image-to-image com a API hiapi: curl, Python e exemplos de requisição disponíveis

Em resumo

• O que é: a solução disponível para chamar a API flux-2/image-to-image na hiapi — criar tarefa, consultar status, baixar resultado.
• Endpoint: use POST https://api.hiapi.ai/v1/tasks e especifique "model": "flux-2/image-to-image", depois GET /v1/tasks/<taskId> até a tarefa atingir o estado terminal.
• Campos de entrada obrigatórios (todos os quatro): prompt, image_urls (1–8 URLs públicas — é isso que permite múltiplas imagens de referência), aspect_ratio e resolution (1K ou 2K).
• O schema é estrito. Campos como strength ou fidelity não existem e serão rejeitados com 400. A fidelidade é controlada pelas suas imagens de referência, pelo prompt e pela resolution — não por um botão separado.

O que você vai construir e o que precisa preparar

Objetivo: enviar uma ou mais imagens de referência mais um prompt de texto ao flux-2 e receber uma imagem editada/redesenhada para download — usando curl ou Python, sem SDK.

Pré-requisitos:

1. Uma chave de API hiapi — criada no console hiapi. A chave tem o formato sk-... e vai no cabeçalho Authorization: Bearer.
2. Pelo menos uma URL de imagem acessível publicamente para usar como referência. A API busca as image_urls no servidor, então links de localhost ou URLs de buckets privados não funcionam — use um bucket público, CDN ou URL pré-assinada.
3. curl, ou Python 3.8+ com requests (pip install requests).

Schema da requisição

flux-2/image-to-image roda na interface unificada de tarefas da hiapi. O objeto input aceita exatamente os seguintes campos:

Campo	Tipo	Obrigatório	Descrição
prompt	string	Sim	O que modificar ou gerar. Mínimo de 3 caracteres.
image_urls	string[]	Sim	1–8 URLs públicas de imagens. Mais de uma = múltiplas referências: o flux-2 combina características de identidade, produto ou estilo entre todas as referências.
aspect_ratio	string	Sim	Um de 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 ou auto (segue a imagem de referência).
resolution	string	Sim	1K ou 2K.

Quaisquer outros campos serão rejeitados. Por exemplo, enviar campos strength ou fidelity retorna:

{
  "code": 400,
  "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'fidelity', 'strength' not allowed"
}

Vale a pena memorizar: o modo imagem-para-imagem do flux-2 não tem botão de intensidade de denoising. O grau de fidelidade da saída em relação à referência (edição "de alta fidelidade" vs. redesenho livre) depende de como você escreve o prompt — por exemplo, “mantenha o produto, seus rótulos e proporções exatamente como na referência; substitua apenas o fundo” — além de usar resolution: "2K" para trabalhos que exigem detalhes.

Exemplo mínimo funcional: curl

Passo 1 — criar a tarefa:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Coloque este produto sobre uma bancada de mármore branco com luz suave da manhã, mantenha o produto em si inalterado",
      "image_urls": ["https://your-cdn.example.com/product.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2K"
    }
  }'

Uma criação bem-sucedida retorna o ID da tarefa em data.taskId.

Passo 2 — consultar até concluir:

curl -s https://api.hiapi.ai/v1/tasks/TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Enquanto data.status não for terminal, continue consultando a cada poucos segundos. Quando "status": "success", a URL da imagem está em data.output[0].url.

Passo 3 — baixar o resultado imediatamente:

curl -s -o result.jpg "OUTPUT_URL"

As URLs de saída carregam um timestamp expireAt — são temporárias. Após o sucesso da tarefa, baixe os bytes imediatamente (ou copie para o seu próprio armazenamento); não faça hotlink direto das saídas das tarefas em produção.

Exemplo mínimo funcional: Python

Um script completo — criar, consultar, baixar — usando apenas requests:

import time
import requests

API_KEY = "sk-YOUR_KEY"
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def create_task() -> str:
    resp = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": ("Combine a pessoa da primeira imagem com a jaqueta "
                       "da segunda imagem, iluminação de estúdio, fundo neutro"),
            "image_urls": [
                "https://your-cdn.example.com/person.jpg",
                "https://your-cdn.example.com/jacket.jpg",
            ],
            "aspect_ratio": "3:4",
            "resolution": "2K",
        },
    }, timeout=30)
    body = resp.json()
    task_id = (body.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"falha na criação: {body}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS,
                            timeout=30).json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"tarefa falhou: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"tarefa {task_id} ainda em execução após {timeout_s}s")

task_id = create_task()
print("tarefa:", task_id)
task = wait_task(task_id)
url = task["output"][0]["url"]          # URL temporária — salve imediatamente
img = requests.get(url, timeout=120).content
with open("result.jpg", "wb") as f:
    f.write(img)
print("result.jpg salvo,", len(img), "bytes")

Note que aqui usamos image_urls com duas imagens — este é o uso real de múltiplas referências. Aceita até 8 imagens de referência; o modelo combina entre elas (pessoa + roupa, produto + estilo de fundo, personagem + referência de pose, etc.).

Práticas de produção

Use callback em vez de polling. Para qualquer cenário além de scripts, registre um callback ao criar a tarefa e deixe a hiapi enviar o resultado final ao seu serviço:

{
  "model": "flux-2/image-to-image",
  "input": { "...": "..." },
  "callback": { "url": "https://your-app.example.com/hooks/hiapi", "when": "final" }
}

Com "when": "final", você recebe apenas um POST quando a tarefa atinge o estado terminal. Regra prática: polling é adequado para CLI, processamento em lote e qualquer cenário de curta duração; callbacks são melhores para aplicações voltadas ao usuário, pois manter um worker em loop de polling para cada imagem não escala. Se você não puder expor um endpoint público de callback, use polling — apenas aumente o intervalo para 5 segundos ou mais.

Torne as retentativas seguras. Trate a criação de tarefa como o efeito colateral que ela é: antes de agir com base no resultado, armazene o taskId retornado no seu próprio registro de jobs; ao retentar, verifique novamente o estado da tarefa armazenada em vez de criar uma nova tarefa às cegas (cada criação bem-sucedida é cobrada separadamente). Se o seu executor de jobs puder disparar duas vezes, deduplique primeiro pelo seu próprio ID de job.

Trate os erros que você realmente vai encontrar:

• 401 permission_denied — chave incorreta, ou a chave não tem permissão para usar o modelo. Corpo da resposta:

  {"error": {"code": "permission_denied",
             "message": "This API key cannot use the selected model. ...",
             "type": "hiapi_error"}}
  

  Verifique a chave no console; nosso checklist de chave de API inválida cobre as causas comuns.

• 400 INVALID_REQUEST — violação de schema. A message lista todos os campos violados de uma vez (campos obrigatórios ausentes, valores de enum inválidos, campos extras desconhecidos), então leia tudo, em vez de corrigir um campo por retentativa.

• Tarefa status: "fail" — a tarefa foi aceita mas a geração falhou; o erro está em data.error. Trate isso no caminho de polling/callback, não na criação.

• URL de saída expirada — se o download retornar 4xx alguns minutos após o sucesso, você esperou demais. Verifique novamente o expireAt e sempre baixe imediatamente.

Leitura relacionada

• Página do modelo flux-2/image-to-image — parâmetros e preço atual
• Página do modelo flux-2/text-to-image — mesma família, sem imagem de referência
• flux-2 para imagens de produtos de e-commerce — solução ponta a ponta pelo lado de texto-para-imagem
• FLUX 1.1 Pro na hiapi — comparação com a opção da geração anterior
• Preços da hiapi — custo por imagem em cada resolução

Perguntas frequentes

Quantas imagens de referência posso enviar para o flux-2 imagem-para-imagem? De 1 a 8, como URLs públicas em image_urls. Mais de 8 causa falha de validação (maxItems: got N, want 8).

Existe parâmetro strength ou fidelity? Não. O schema de entrada aceita apenas prompt, image_urls, aspect_ratio e resolution; campos desconhecidos são rejeitados com 400. Controle a fidelidade pela formulação do prompt (deixe explícito o que deve permanecer inalterado) e use 2K quando os detalhes importarem.

Quais resoluções e proporções são suportadas? resolution é 1K ou 2K. aspect_ratio é um de 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3 ou auto — auto segue sua imagem de referência, o que normalmente é o desejado em edições.

Posso enviar imagens em base64 em vez de URL? Não — image_urls aceita URLs, e elas devem ser acessíveis publicamente para a API buscar. Faça upload para um bucket ou CDN primeiro e passe a URL gerada (URLs pré-assinadas funcionam).

Quanto custa cada imagem no flux-2 imagem-para-imagem? O preço varia com a resolução — consulte a página do modelo flux-2/image-to-image e a página de preços para a tarifa atual por imagem.

Por quanto tempo as URLs das imagens geradas são válidas? As URLs de saída são temporárias e contêm o campo expireAt. Após o sucesso da tarefa, baixe os bytes da imagem imediatamente e armazene por conta própria.

Qual a diferença entre flux-2/image-to-image e flux-2/text-to-image? Mesma família de modelos, modos diferentes: texto-para-imagem gera apenas a partir do prompt, enquanto imagem-para-imagem exige 1–8 imagens de referência e edita ou combina com base nelas. Os schemas de entrada são diferentes, então os corpos de requisição não são intercambiáveis.