Como usar flux-2-klein-4b/image-to-image através da API hiapi

O FLUX.2 [klein] 4B é um modelo de edição de imagem compacto e rápido lançado pela Black Forest Labs: basta fornecer uma imagem de referência e uma instrução em linguagem natural, e ele retorna uma imagem editada de até 4 MP. No hiapi, ele é executado como todos os outros modelos através da mesma Unified Async API — crie uma tarefa com POST /v1/tasks e depois faça polling ou receba um callback para obter o resultado. Este guia cobre a estrutura exata da requisição, exemplos funcionais em curl/Python e como integrá-lo num ambiente de produção.

O que você precisa

• Uma chave de API hiapi. Obtenha-a em dashboard — a chave tem o formato sk-... e vai no cabeçalho Authorization: Bearer.
• Um URL de imagem de referência acessível publicamente (jpeg, png ou webp — svg não é suportado). Imagens acima de 4 MP são automaticamente reduzidas para 4 MP.
• O preço atual de flux-2-klein-4b/image-to-image é dividido por faixas de resolução (0,25 MP a 4 MP) — consulte hiapi pricing para obter o preço em tempo real; não codifique os valores diretamente aqui.

Exemplo mínimo funcional

O ID do modelo é flux-2-klein-4b/image-to-image — use exatamente essa grafia (incluindo a barra) como valor de model (não no caminho do URL). Todos os modelos hiapi compartilham o mesmo endpoint; apenas os campos do objeto input variam conforme o modelo.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-klein-4b/image-to-image",
    "input": {
      "prompt": "Keep the subject and camera angle. Replace the background with a deep-blue studio gradient and add soft rim lighting.",
      "image_urls": ["https://your-cdn.example.com/product-shot.jpg"],
      "resolution": "2 MP",
      "aspect_ratio": "16:9"
    }
  }'

Essa requisição retorna imediatamente um taskId — a geração é assíncrona:

{"code": 0, "message": "success", "data": {"taskId": "task_..."}}

Faça polling para obter o resultado:

curl "https://api.hiapi.ai/v1/tasks/task_..." \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Quando status se tornar "success", a imagem editada estará em data.output[0].url. Esse URL é temporário (contém expireAt), então baixe ou re-hospede o arquivo imediatamente — não armazene o hotlink diretamente.

Implementação do mesmo fluxo em Python:

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer sk-YOUR_API_KEY",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_url: str) -> str:
    payload = {
        "model": "flux-2-klein-4b/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": [image_url],
            "resolution": "2 MP",
            "aspect_ratio": "16:9",
        },
    }
    resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

task_id = create_task(
    "Keep the subject and camera angle. Replace the background with a deep-blue "
    "studio gradient and add soft rim lighting.",
    "https://your-cdn.example.com/product-shot.jpg",
)
result = wait_task(task_id)
print(result["output"][0]["url"])

Parâmetros da requisição

flux-2-klein-4b/image-to-image aceita um schema de entrada estrito — campos adicionais não listados aqui são rejeitados com 400:

Campo	Obrigatório	Descrição
prompt	Sim	Descrição em linguagem natural da edição a aplicar.
image_urls	Sim	Array contendo exatamente um URL de imagem de referência. Passar mais de um retorna maxItems: got N, want 1.
resolution	Não	Um dos valores: 0.25 MP, 0.5 MP, 1 MP (padrão), 2 MP, 4 MP. Use 0,25/0,5 MP para rascunhos de baixo custo e 2/4 MP para a saída final.
aspect_ratio	Não	Um dos valores: match_input_image (padrão), 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 21:9, 9:21.
seed	Não	Inteiro usado para obter saídas reproduzíveis entre requisições idênticas no restante.
output_format	Não	jpg (padrão), png ou webp.
output_quality	Não	Inteiro, qualidade de compressão para jpg/webp (padrão 95).

Este modelo não tem campos size ou n — essas são convenções de outros provedores que este schema não reconhece. Cada modelo hiapi tem seu próprio conjunto de campos, então antes de portar requisições criadas para outros modelos, consulte a página de referência do modelo.

Considerações para produção

Prefira callbacks em vez de polling. Adicione um objeto callback de nível superior e o hiapi notificará seu serviço em vez de você fazer polling em loop:

{
  "model": "flux-2-klein-4b/image-to-image",
  "input": { "prompt": "...", "image_urls": ["..."] },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

when aceita apenas "final" — uma notificação enviada uma única vez quando a tarefa atinge um estado terminal (success ou fail), e não um fluxo de progresso. Trate o callback como um sinal de despertar: ao recebê-lo, ainda deve fazer GET /v1/tasks/<taskId> para ler o estado autoritativo, e mantenha o handler idempotente em relação ao taskId, para evitar entregas duplicadas.

Idempotência. Persista o taskId imediatamente após create_task retornar, antes de iniciar o polling ou aguardar o callback. Se o processo falhar durante a espera, ao reiniciar deve retomar com GET /v1/tasks/<taskId> em vez de recriar a tarefa — a criação de tarefas é um evento cobrado, enquanto o GET pode ser repetido gratuitamente.

Tratamento de erros. Chaves inválidas ou não autorizadas retornam HTTP 401 com um corpo de resposta estruturado:

{
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. Please check permissions or use another key. If the issue persists, contact support with request ID: ...",
    "request_id": "...",
    "type": "hiapi_error"
  }
}

Registre o request_id — o suporte pode usá-lo para localizar a chamada exata. Um input malformado (falta de prompt/image_urls, valor de aspect_ratio não suportado ou campos extras não reconhecidos) retorna 400 com error_code: "INVALID_REQUEST" e a mensagem indica o campo problemático; corrija o corpo da requisição em vez de tentar novamente como está.

Leitura relacionada

• Referência do modelo FLUX.2 [klein] 4B image-to-image — documentação completa dos parâmetros e corpos de requisição de exemplo.
• Referência do modelo FLUX.2 [klein] 4B text-to-image — a variante correspondente de text-to-image, sem imagem de referência.
• hiapi pricing — custo atual por imagem, dividido por faixas de resolução.
• Visão geral da Unified Async API — o contrato POST /v1/tasks / GET /v1/tasks/:id compartilhado por todos os modelos da plataforma.

Perguntas frequentes

Quais formatos de imagem image_urls aceita? jpeg, png ou webp. svg não é suportado. Imagens maiores que 4 MP são automaticamente reduzidas para 4 MP antes da edição.

Posso passar várias imagens de referência? Não — image_urls neste modelo tem limite de exatamente um elemento. Passar mais retorna 400 (maxItems: got N, want 1).

Por que minha requisição foi rejeitada com "additional properties ... not allowed"? O schema é estrito: qualquer campo que não esteja na tabela de parâmetros acima (por exemplo, convenções de outros provedores como size, n ou strength) provoca um 400. Consulte a referência do modelo para saber o conjunto exato de campos aceitos.

Como manter a proporção da imagem original? Defina aspect_ratio como match_input_image — este também é o valor padrão se você omitir completamente o campo.

Qual é a diferença entre flux-2-klein-4b/image-to-image e a variante 9B? Ambos compartilham o mesmo schema de requisição (prompt, image_urls, resolution, aspect_ratio, seed, output_format, output_quality). A versão 9B troca parte da velocidade e do custo por maior realismo, renderização de texto e detalhes — use a 4B quando iterar de forma rápida e barata, e a 9B quando as edições precisarem se sustentar em detalhes finos.

Preciso de um URL de callback, ou o polling é suficiente? O polling com GET /v1/tasks/:id é suficiente para desenvolvimento local, tarefas de baixo volume ou como fallback quando a entrega de callbacks falhar. Para tráfego de produção, callbacks evitam a sobrecarga de um loop de polling para cada requisição.