flux-2 para imagens de produtos de e-commerce: guia prático da API hiapi

TL;DR

• O que é isto: um guia prático para gerar imagens de produtos de e-commerce com o flux-2/text-to-image no hiapi. Cada imagem nesta página foi gerada exatamente pelo prompt impresso logo acima dela — sem demonstrações emprestadas — então você pode reproduzir cada uma.
• Por que o flux-2 é adequado para imagens de produtos: ele se apoia na aderência ao prompt e na alta fidelidade, que é exatamente o que o trabalho de catálogo precisa — quantidade exata de itens, cores específicas, fundos limpos e sem emendas, e rótulos em branco (sem texto), todos seguidos à risca.
• Fatos do modelo (verificados na API): o flux-2 roda em um endpoint de tarefas assíncrono (/v1/tasks). input.resolution usa o formato de megapixels — 0.5 MP, 1 MP, 2 MP ou 4 MP — e não 1K/2K. aspect_ratio é opcional e aceita valores como 1:1, 3:2, 16:9.
• Preço (por imagem): 0.5 MP custa $0.0375, 1 MP custa $0.05, 2 MP custa $0.075, 4 MP custa $0.125. Consulte os preços em tempo real na página de preços.
• Como executar: envie um POST para a API de tarefas, faça polling até o status ser success, e então baixe a imagem de output[0].url (essa URL expira — salve os bytes imediatamente). O script completo de copiar e colar está no final, incluindo um loop em lote.

Por que o flux-2 é adequado para fotografia de produtos

A maioria dos modelos de texto para imagem consegue desenhar uma caneca bonita. O problema no e-commerce não é "bonito", mas precisão. Uma listagem de produto precisa da cor correta, da quantidade correta de itens, de um fundo limpo com espaço para você mesmo sobrepor texto, e de rótulos mantidos em branco para você colocar o texto real depois. Quando o modelo improvisa — desenha uma garrafa a mais, inventa texto no rótulo, tinge o fundo branco — a imagem não pode ser publicada.

O flux-2 é marcado por aderência ao prompt e alta fidelidade, o que na prática significa que ele tende a seguir o prompt literalmente. É exatamente aí que está a chave para imagens de catálogo: você escreve as restrições, o modelo as obedece, em vez de "interpretá-las criativamente". As receitas abaixo são construídas em torno disso — cada receita depende de uma restrição específica (quantidade, cor, layout) para que você veja a aderência com os próprios olhos.

Como ler estas receitas

Cada receita tem três partes: uma linha de objetivo, o prompt exato (copie como está) e a imagem que ele gera. Cada prompt foi escrito por mim e executado no flux-2 pela API de tarefas real. Alguns hábitos que funcionam consistentemente com este modelo:

• Declare o fundo explicitamente. "Fundo de estúdio cinza-claro sem emendas" é melhor do que deixar ao acaso, e deixa a imagem diretamente utilizável na página de detalhes do produto (PDP).
• Escreva "sem texto, sem logotipo" quando quiser rótulos em branco. O flux-2 obedece a isso, o que significa que você pode adicionar a marca real depois.
• Dê restrições contáveis e verificáveis. "Exatamente três garrafas", "âmbar à esquerda, transparente no meio, ciano à direita" — instruções específicas são onde a aderência faz diferença.
• Reserve espaço negativo no prompt ("bastante espaço em branco no topo para o título"), especialmente quando a imagem ficará sob texto sobreposto.

Receita 1 — Fundo branco limpo

Objetivo: a imagem mais básica de listagem de produto — uma peça, fundo sem emendas, margens uniformes, pronta para a página do produto.

A single matte-white ceramic coffee mug centered on a seamless light-grey studio background, three-quarter front angle, empty and unbranded. Soft even top-light with one subtle rim highlight down the left edge, a soft grounded contact shadow beneath. Studio e-commerce packshot, perfectly centered, wide even margins on all sides, photoreal, high detail, no text, no logo.

As margens e a centralização vêm diretamente do prompt — exigi-las explicitamente é o que torna o recorte utilizável na grade de listagem.

Receita 2 — Teste de aderência ao prompt

Objetivo: provar que o modelo segue instruções precisas e contáveis — exatamente o motivo pelo qual o trabalho de produtos escolhe o flux-2 em primeiro lugar.

Product photo of exactly three glass spray bottles standing in a row on a white acrylic surface: the left bottle filled with pale amber liquid, the middle bottle filled with clear liquid, the right bottle filled with soft teal liquid. All three have matte-black fine-mist pump tops and blank labels with no writing. Even frontal studio light, soft reflections on the acrylic, seamless white background. Photoreal commercial product photography, sharp focus, no text anywhere in the image.

Conte: três frascos, não quatro. O líquido de preenchimento, da esquerda para a direita, é âmbar, transparente, ciano — na ordem correta. As tampas de bomba são preto fosco. Os rótulos estão em branco, então você pode adicionar o texto real depois. Esse é o retorno — você especifica, ele obedece, a imagem fica pronta para uso.

Receita 3 — Imagem lifestyle/contextual

Objetivo: colocar o produto em uma cena sem escondê-lo — a imagem "em uso" que aparece ao lado da foto em fundo branco na listagem do produto.

Lifestyle e-commerce shot of a tan leather crossbody bag resting on a pale oak cafe table beside a folded newspaper and a cup of espresso, soft morning window light from the left, warm out-of-focus cafe interior in the background with creamy bokeh. The bag is the clear hero, sharp and well-lit, staged naturally but uncluttered. Photoreal, editorial product-in-use photography, warm neutral palette, shallow depth of field, no visible brand marks or text.

Declarar o protagonista ("a bolsa é o herói claro, nítida") e jogar todo o resto no desfoque mantém o produto legível enquanto conta uma história — exatamente o equilíbrio que uma imagem lifestyle precisa.

Receita 4 — Conjunto de ângulos para PDP

Objetivo: um conjunto de ângulos para a página de detalhes do produto — várias visões consistentes do mesmo item, combinando em iluminação e proporção.

A clean product-detail-page angle set of one pair of low-top canvas sneakers in off-white, shown as three separate views arranged left to right on a seamless light-grey background: a straight side profile, a three-quarter front angle, and a top-down overhead view. Consistent soft studio lighting and identical scale across all three, even spacing, soft contact shadows. Catalog-grade e-commerce photography, photoreal, crisp, unbranded, no text or labels.

Exigir "iluminação consistente e escala idêntica nas três visões" é o que faz o conjunto parecer o mesmo produto, em vez de três renders soltos. Não substitui um equipamento de verdade para 360 graus, mas é uma forma rápida de montar o layout de uma PDP antes da sessão de fotos oficial.

Executando o flux-2 na API de tarefas

O flux-2 usa o protocolo de tarefas assíncronas do hiapi — você cria a tarefa, faz polling e depois baixa o resultado. O único detalhe que precisa estar certo: resolution usa o formato de megapixels. Envie "1 MP", não "1K", senão a API retorna 400 dizendo que o valor deve ser um entre 0.5 MP / 1 MP / 2 MP / 4 MP.

1. Criar a tarefa

curl -s https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2/text-to-image",
    "input": {
      "prompt": "A single matte-white ceramic coffee mug centered on a seamless light-grey studio background, three-quarter front angle, soft even top-light, photoreal e-commerce packshot, no text, no logo",
      "aspect_ratio": "1:1",
      "resolution": "1 MP"
    }
  }'
# -> {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

2. Fazer polling até concluir e então baixar

import os, time, requests

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}


def generate(prompt, aspect_ratio="1:1", resolution="1 MP"):
    # create
    r = requests.post(BASE, headers=HEADERS, json={
        "model": "flux-2/text-to-image",
        "input": {"prompt": prompt, "aspect_ratio": aspect_ratio, "resolution": resolution},
    }).json()
    task_id = r["data"]["taskId"]

    # poll (a single image usually lands well under two minutes)
    deadline = time.time() + 600
    while time.time() < deadline:
        task = requests.get(f"{BASE}/{task_id}", headers=HEADERS).json()["data"]
        if task["status"] == "success":
            # output[0].url is a temporary link — download the bytes now
            url = task["output"][0]["url"]
            return requests.get(url, timeout=120).content
        if task["status"] == "fail":
            raise RuntimeError(task.get("error"))
        time.sleep(5)
    raise TimeoutError(task_id)


img = generate("A single matte-white ceramic coffee mug on a seamless light-grey background, photoreal e-commerce packshot, no text")
open("mug.jpg", "wb").write(img)

A URL em output[0].url carrega um carimbo de tempo expireAt — é um link de curta duração. Baixe os bytes imediatamente e envie para o seu próprio armazenamento; não faça hotlink dela em uma listagem de produto online.

Gerando o catálogo inteiro em lote

Para uma loja real, você não faz só uma imagem — faz uma imagem por SKU. Mantenha uma lista de prompts, reutilize a função generate() acima e salve cada resultado com o nome do seu SKU:

catalog = {
    "SKU-1001": "A single matte-white ceramic coffee mug on a seamless light-grey studio background, three-quarter angle, soft even top-light, photoreal e-commerce packshot, no text, no logo",
    "SKU-1002": "A tan leather crossbody bag on a seamless light-grey studio background, front-on, soft studio light, grounded contact shadow, photoreal packshot, no visible brand marks",
    "SKU-1003": "A pair of off-white low-top canvas sneakers, side profile, seamless light-grey background, crisp catalog lighting, photoreal, unbranded, no text",
}

for sku, prompt in catalog.items():
    img = generate(prompt, aspect_ratio="1:1", resolution="1 MP")
    open(f"{sku}.jpg", "wb").write(img)
    print(f"{sku} done")

Antes de escalar, algumas coisas valem a pena saber:

• A resolução determina o custo. Em 1 MP cada imagem custa $0.05; só suba para 2 MP ($0.075) ou 4 MP ($0.125) em imagens principais em que o detalhe extra valha a pena. Um catálogo de 200 SKUs em 1 MP custa cerca de $10. Antes de orçar, consulte a página de preços para os números atuais.
• Execute tarefas simultaneamente. Cada SKU é uma tarefa independente — crie várias tarefas e faça polling delas em paralelo, em vez de uma de cada vez; lotes grandes ficam prontos em pouco tempo de relógio.
• Mantenha uma cláusula de "estilo" consistente. Note o trecho final compartilhado em cada prompt acima ("fundo de estúdio cinza-claro sem emendas... pacote fotorrealista, sem texto"). Trave essa formulação para que um lote de imagens pareça um catálogo, e não uma colcha de retalhos.

Pontos principais

• A vantagem do flux-2 no trabalho de produtos é executar estritamente o que você pede literalmente — quantidade exata, cor exata, rótulos em branco — então escreva as restrições explicitamente para que ele as obedeça.
• Sempre declare o fundo no prompt e reserve espaço negativo; isso deixa o render diretamente utilizável na listagem do produto.
• Na API de tarefas, envie resolution em megapixels (1 MP), faça polling de /v1/tasks/{id} até success, e baixe antes que output[0].url expire.
• O preço sobe com a resolução — use 1 MP para lotes de catálogo e reserve 2 MP/4 MP para imagens principais.

Pronto para experimentar? Obtenha uma chave, aponte o model para flux-2/text-to-image e confira as tarifas em tempo real na página de preços antes de gerar o catálogo em lote.