flux-2/image-to-image para imagens de produtos de e-commerce: guia da API hiapi

Se você já tem fotos de produtos razoáveis — mesmo que sejam fotos bagunçadas com fundo errado e enquadramento ruim — o flux-2/image-to-image consegue transformá-las em imagens de e-commerce prontas para publicação sem precisar refazer as fotos. Ele é um modelo de edição, não de geração a partir de texto: insira de 1 a 8 imagens de referência mais uma instrução, e ele retorna uma nova imagem preservando com precisão a forma, a cor, o material e as proporções do produto, ao mesmo tempo em que altera tudo ao redor — fundo, iluminação, composição e até o cenário em que o produto está inserido.

Executamos de ponta a ponta, pela API /v1/tasks da hiapi, duas tarefas comuns de e-commerce — substituição de fundo de estúdio e composição em cenários de lifestyle — e, antes de escrever este conteúdo, verificamos o schema de entrada, o comportamento de proporção e o preço real por imagem na página de preços da hiapi.

• O flux-2/image-to-image aceita até 8 imagens de referência por chamada, portanto a substituição de fundo (1 imagem) e a composição de cenário (2 ou mais) usam exatamente o mesmo endpoint.
• aspect_ratio: "auto" realmente segue a proporção da própria imagem de entrada — uma foto vertical 9:16 de um tênis permanece 9:16, a menos que você a substitua. Valores explícitos como "1:1" forçam esse formato, independentemente do que você enviar.
• O preço é escalonado por resolução: US$ 0,035/imagem em 1K e US$ 0,05/imagem em 2K — preço fixo, sem cobrança por megapixel.
• É uma edição de verdade, não uma repintura: o logotipo, as costuras e a textura do material do próprio produto permanecem após a mudança de fundo/cenário.
• Um script de processamento em lote (veja abaixo) é suficiente para percorrer todo um catálogo de produtos com o mesmo prompt de limpeza de fundo.

O que o flux-2/image-to-image realmente faz

Por baixo dos panos, é um único modelo na interface unificada de tarefas da hiapi — você não escolhe entre uma ferramenta de "remoção de fundo" e uma ferramenta de "composição"; você escreve uma instrução e fornece as imagens de referência corretas para a tarefa:

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/image-to-image",
    "input": {
      "prompt": "Remove the background and place the product on a seamless white studio background with a soft contact shadow. Keep the product'"'"'s shape, color and proportions unchanged.",
      "image_urls": ["https://your-cdn.example.com/raw-product-photo.jpg"],
      "aspect_ratio": "auto",
      "resolution": "1K"
    }
  }'

Os campos obrigatórios são prompt (string), image_urls (array, máximo de 8), aspect_ratio (auto, 1:1, 4:3, 3:4, 16:9, 9:16, 3:2 ou 2:3) e resolution (1K ou 2K). A resposta retorna um taskId — faça polling em GET /v1/tasks/{taskId} até que status seja success e então baixe a imagem imediatamente de output[0].url (esse link expira, então não o trate como armazenamento permanente).

A substituição de fundo precisa de apenas uma imagem de referência. Para compor o produto em um cenário de lifestyle, envie duas: a imagem do produto primeiro, a cena de destino depois, e descreva no prompt qual objeto vai em qual lugar.

O que a proporção "auto" realmente faz

Esta é a parte que vale a pena testar antes de montar um pipeline em torno dela, porque é fácil presumir que o modelo sempre gera um quadrado fixo ou algum formato padrão fixo. Não é o caso.

Esta é uma foto vertical de tênis executada com aspect_ratio: "auto" — a saída foi 720×1280, correspondendo exatamente ao 9:16 da imagem de referência de entrada, sem cortes nem barras para outro formato. auto significa "seguir a entrada", não "escolher um padrão".

Mesma imagem de origem, mesmo prompt — a única mudança foi definir explicitamente aspect_ratio: "1:1". A saída foi um quadrado exato de 1024×1024, com o modelo recompondo para se ajustar, em vez de simplesmente cortar. Se o seu catálogo precisa de uma grade quadrada consistente para as páginas de listagem, force essa proporção; se você quer que cada imagem mantenha sua composição nativa, mantenha auto.

Dois exemplos de composição em cenário

A substituição de fundo é o caso simples. A técnica mais útil para conteúdo de e-commerce é compor uma imagem limpa do produto em um cenário de lifestyle — útil para imagens principais, posts sociais ou fotos secundárias de "combinação", sem precisar de uma sessão de fotos real.

Aqui foram usadas duas imagens de referência: uma foto limpa dos fones de ouvido e uma cena separada de mesa de carvalho iluminada pelo sol. O prompt especificou qual objeto colocar e onde ("apoiado naturalmente perto da planta") e pediu ao modelo que correspondesse à direção da luz já presente na cena e projetasse uma sombra convincente — justamente esse detalhe faz a composição parecer real, em vez de colada.

Mesmo cenário de destino, produto diferente, também com aspect_ratio: "auto" (que herdou a composição quadrada da imagem de referência do cenário). A forma e o material cerâmico do porta-filtro foram preservados exatamente como na própria foto de referência — apenas o ambiente ao redor mudou.

Processar um catálogo de produtos em lote

A US$ 0,035/imagem (resolução 1K) — mais barato do que refazer uma sessão de fotos para um único produto —, rodar todo um catálogo de produtos com o flux-2/image-to-image se justifica facilmente. Se você quiser apenas testar prompts com custo baixo primeiro, vale a pena conhecer o nível mais leve flux-2-klein-4b/image-to-image antes de usar o modelo completo em escala; os preços atuais de ambos estão na página de preços da hiapi.

Depois de ajustar o prompt para um produto, executá-lo em todo o catálogo é só um loop sobre a mesma requisição. Este exemplo percorre um conjunto de fotos de produtos originais, executa a mesma instrução de limpeza de fundo em cada uma e imprime a URL de hospedagem do resultado:

import os
import time

import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]

HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json",
}

BACKGROUND_PROMPT = (
    "Remove the existing background and place the product on a seamless pure white "
    "studio background with a soft, realistic contact shadow and even diffused catalog "
    "lighting. Keep the product's exact shape, color, material and proportions unchanged."
)


def edit_product_image(prompt, image_urls, aspect_ratio="auto", resolution="1K"):
    payload = {
        "model": "flux-2/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,
            "aspect_ratio": aspect_ratio,
            "resolution": resolution,
        },
    }
    resp = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    task_id = resp.json()["data"]["taskId"]

    while True:
        time.sleep(3)
        status = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30).json()
        state = status["data"]["status"]
        if state == "success":
            return status["data"]["output"][0]["url"]
        if state == "fail":
            raise RuntimeError(f"task {task_id} failed: {status}")


CATALOG = [
    {"sku": "SNK-001", "image_url": "https://cdn.example.com/raw/snk-001.jpg"},
    {"sku": "HDP-014", "image_url": "https://cdn.example.com/raw/hdp-014.jpg"},
    {"sku": "DRP-022", "image_url": "https://cdn.example.com/raw/drp-022.jpg"},
]

for item in CATALOG:
    out_url = edit_product_image(BACKGROUND_PROMPT, [item["image_url"]])
    print(item["sku"], "->", out_url)

Cada output[0].url é um link com validade limitada — baixe e re-hospede a imagem dentro do loop (no seu próprio bucket, CDN ou qualquer serviço que sustente o backend da sua loja), em vez de salvar o link bruto. Para um passo a passo completo do ciclo de tarefa/polling/download (com tratamento de erros), veja como usar o flux-2/image-to-image pela API hiapi.

Perguntas frequentes

O flux-2/image-to-image altera o próprio produto ou apenas o fundo? Com um prompt adequado, ele deve alterar apenas o que você mandar — fundo, cenário, iluminação — mantendo a forma, a cor e o material do produto iguais aos da imagem de referência. Nem toda tentativa é perfeita; antes de publicar, confira a saída contra a imagem de origem, especialmente textos pequenos ou logotipos em embalagens.

Quantas imagens de referência posso usar por chamada? Até 8. A substituição de fundo precisa apenas de 1. A composição de cenário normalmente precisa de 2 (produto + cenário de destino) — mais imagens de referência são úteis quando você quer que o modelo corresponda a um personagem, adereço ou elemento de marca já existente em um conjunto de fotos.

Devo usar resolução 1K ou 2K? 1K (US$ 0,035/imagem) é suficiente para a maioria dos catálogos de produtos e listagens na web — as composições dos fones e do porta-filtro acima foram geradas em 1K. Para banners principais ou qualquer coisa que depois será cortada e ampliada, escolha 2K (US$ 0,05/imagem).

Qual é a diferença entre o flux-2/image-to-image e o nível Klein? O Klein (9b e 4b) troca parte da fidelidade de edição por um preço menor — bom para testar prompts com custo baixo antes de rodar o modelo completo em todo o catálogo. Os preços atuais estão na tabela de preços acima.

Posso forçar um tamanho de saída específico em vez de deixar o modelo decidir? Sim — defina aspect_ratio com um valor explícito (1:1, 4:3, 16:9 etc.) em vez de auto. O modelo recompõe para se ajustar a esse formato, em vez de simplesmente cortar a saída de correspondência automática.

Principais conclusões

• O flux-2/image-to-image edita fotos de produtos existentes, em vez de gerar do zero — entrada de imagem de referência, saída de imagem editada, com a identidade do produto preservada.
• aspect_ratio: "auto" segue o formato da própria imagem de entrada; defina explicitamente quando precisar de uma proporção de saída consistente em toda a grade do catálogo.
• Resolução 1K (US$ 0,035/imagem) cobre a maioria dos casos de e-commerce; 2K (US$ 0,05/imagem) para tamanhos de destaque ou saídas muito recortadas.
• O mesmo endpoint trata tanto da substituição de fundo com uma imagem quanto da composição de cenário com várias imagens — a única diferença é quantas image_urls você envia.
• O processamento em lote é apenas um loop comum em torno do ciclo de tarefa/polling/download, sem endpoint de lote separado.

Se você já está pronto para aplicá-lo ao seu próprio catálogo de produtos, a página do modelo flux-2/image-to-image traz o schema em tempo real e uma requisição de início rápido, e as receitas de prompts do flux-2/image-to-image reúnem mais padrões de prompt testados além da substituição de fundo e da composição de cenário.