Guia de uso

FLUX 1.1 Pro para imagens de produtos de e-commerce: guia da API hiapi

Jul 3, 2026

Se você vende coisas online, já conhece essa conta: uma página de detalhes de produto precisa de uma foto em fundo branco, uma foto em contexto de uso e, de preferência, um conjunto de imagens de vários ângulos — para cada SKU, cada variante de cor. Um dia de estúdio resolve dez produtos, enquanto uma API de imagem resolve mil.

flux-1.1-pro (o FLUX.1.1 [pro] da Black Forest Labs) é o modelo principal de fotorrealismo no hiapi: ele renderiza materiais convincentes — metal escovado, vidro, tecido, bokeh suave — com um preço fixo de US$ 0,05 por imagem. Este guia é uma receita de e-commerce pronta para ir ao ar: cada imagem abaixo foi gerada com o prompt exatamente como está impresso acima dela, usando a mesma chamada /v1/tasks que você pode copiar e colar, e registramos o intervalo real de parâmetros — incluindo aqueles que parecem existir, mas retornam 400 tão logo são enviados.

Entenda a API em 60 segundos

No hiapi, o flux-1.1-pro roda em um endpoint de tarefas assíncronas. Você cria a tarefa, consulta seu status e baixa o resultado:

# 1. Create the task
curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-pro",
    "input": {
      "prompt": "Studio packshot of an unbranded stainless steel wristwatch...",
      "aspect_ratio": "1:1",
      "output_format": "jpg",
      "seed": 6607
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01KWK3JG..."},"message":"success"}

# 2. Poll until status is "success" (typically 10–40s for flux-1.1-pro)
curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWK3JG... \
  -H "Authorization: Bearer $HIAPI_API_KEY"

# 3. Download output[0].url — it carries an expireAt timestamp,
#    so save the file to your own storage immediately.

Antes de entrar no assunto, duas observações operacionais:

As URLs de saída são temporárias. Baixe e transfira para o seu próprio armazenamento assim que a tarefa for concluída — veja o que acontece quando a URL de saída do hiapi expira.
Se uma tarefa ficar no estado processing por mais tempo do que o esperado, não reenvie às cegas; há um guia de diagnóstico de tarefas travadas ou com timeout.

O intervalo real de parâmetros (e os 400 que você recebe ao chutar)

Se você já usou modelos FLUX em outras plataformas, a memória muscular vai te levar a ajustar steps e guidance. Mas no schema de tarefas do hiapi para flux-1.1-pro, esses campos não existem — a API valida a entrada estritamente e rejeita propriedades desconhecidas:

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

Isso não é um bug; o FLUX 1.1 [pro] é oferecido como endpoint gerenciado, e o mecanismo interno de amostragem é fixado pelo provedor. A seguir, o que você pode enviar, validado pelo schema em produção:

Campo	Tipo	Valores aceitos / intervalo
`prompt`	string	obrigatório
`aspect_ratio`	string	`1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `4:5`, `5:4`, `custom`
`width`, `height`	integer	256–1440 px (usados no lugar da proporção ou junto com a proporção `custom`)
`seed`	integer	qualquer inteiro — fixa a composição para reprodutibilidade
`output_format`	string	`jpg`, `png`, `webp`
`prompt_upsampling`	boolean	faz o backend reescrever/expandir seu prompt
`safety_tolerance`	integer	0–6

Padrões práticos para fotos de produto: output_format: "jpg", um aspect_ratio explícito conforme a posição de veiculação (1:1 para grade de loja, 4:5 para feed/contexto de uso, 3:2 ou 1440×960 para banners), um seed fixo por família de SKU e prompt_upsampling desligado — no e-commerce você quer que o modelo siga estritamente a sua formulação, em vez de acrescentar invenções próprias.

Receita 1 — O packshot limpo em fundo branco

A imagem mais básica: um produto, fundo contínuo, luz principal suave. Diga explicitamente a cor do fundo, peça reflexo no chão e — importante para qualquer modelo fotorrealista — sempre inclua “sem marca, sem logo, sem texto”. Mostradores e etiquetas são exatamente onde o FLUX pode inventar rabiscos com formas de marca registrada, que você teria de retocar depois.

Studio packshot of an unbranded stainless steel wristwatch with a plain deep green dial and brushed metal bracelet, the dial completely clean with simple baton hour markers and no logo, no brand name, no text or numerals anywhere, standing upright on a seamless light grey background, centered composition, soft diffused key light from the upper left, subtle reflection beneath the watch, photorealistic e-commerce product photography

Envie com aspect_ratio: "1:1" e seed: 6607. O acabamento em metal escovado e o reflexo suave no chão são exatamente o que você paga para ter no nível profissional de US$ 0,05 — modelos baratos achatam justamente esses detalhes.

Receita 2 — A imagem em contexto de uso

A grade da loja pede fundo branco; a página de produto e as redes sociais convertem com contexto. Coloque o produto na cena, mantenha o rótulo em branco e use profundidade de campo rasa para transmitir “sofisticação”. 4:5 corresponde ao recorte do feed.

A lit soy candle in a clear glass jar with a plain blank kraft-paper label, on a rustic oak nightstand next to a stack of two linen-bound books, warm evening window light, softly blurred bedroom background, cozy lifestyle product photography for an online store, photorealistic

Envie com aspect_ratio: "4:5" e seed: 7301. Note que o rótulo em branco foi preservado — é a tela onde você depois compõe a arte real da marca.

Receita 3 — Variantes de cor com seed fixo

Este é o truque que mais economiza na produção de catálogo. O seed fixa a inicialização de ruído, então, se você mantiver o seed e a estrutura do prompt exatamente iguais e mudar apenas as palavras de cor, você obtém a mesma composição em uma nova variante de cor — sem novo ensaio fotográfico, sem fluxo img2img.

As duas imagens abaixo usam seed: 5150 e aspect_ratio: "1:1", com prompts que diferem em exatamente duas palavras (navy blue → coral pink):

A single insulated stainless steel water bottle in matte navy blue, standing on a round travertine stone slab against a soft warm beige studio background, centered, soft diffused lighting, minimalist e-commerce product photo, photorealistic

Mesmo contorno de garrafa, mesma laje, mesma composição, mas um SKU diferente. Esse é o prompt com seed fixo substituindo um dia inteiro de ensaio de variantes.

Em lote: renderize o catálogo inteiro por SKU

Esta é a rotina que executamos na prática: enviar, consultar, baixar, tentar de novo. A execução em produção revelou um ponto que você precisa planejar com antecedência: tarefas de flux-1.1-pro ocasionalmente falham com um genérico {"code": "TASK_FAILED"} — é algo transitório, e o mesmo input normalmente tem sucesso ao ser reenviado. Reserve até 3 tentativas por imagem (você só paga pelas imagens renderizadas com sucesso).

import json, time, requests

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

CATALOG = [
    {"sku": "bottle-navy",  "colour": "matte navy blue"},
    {"sku": "bottle-coral", "colour": "matte coral pink"},
    {"sku": "bottle-sage",  "colour": "matte sage green"},
]
TEMPLATE = ("A single insulated stainless steel water bottle in {colour}, "
            "standing on a round travertine stone slab against a soft warm "
            "beige studio background, centered, soft diffused lighting, "
            "minimalist e-commerce product photo, photorealistic")

def render(prompt, seed, retries=3):
    for attempt in range(retries):
        task = requests.post(API, headers=HEADERS, json={
            "model": "flux-1.1-pro",
            "input": {"prompt": prompt, "aspect_ratio": "1:1",
                      "output_format": "jpg", "seed": seed},
        }).json()
        task_id = task["data"]["taskId"]
        while True:
            state = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
            if state["status"] == "success":
                return requests.get(state["output"][0]["url"]).content
            if state["status"] == "fail":          # transient TASK_FAILED happens;
                break                              # resubmit with the same input
            time.sleep(5)
    raise RuntimeError(f"gave up after {retries} attempts")

for item in CATALOG:
    img = render(TEMPLATE.format(colour=item["colour"]), seed=5150)
    with open(f"{item['sku']}.jpg", "wb") as f:
        f.write(img)                               # re-host immediately; task URLs expire
    print(item["sku"], "done")

Se você for enviar centenas de SKUs, controle o ritmo de envio — Limites de taxa de APIs de geração de imagem explicados traz o comportamento de limitação e valores razoáveis de concorrência.

Preços e quando escolher o flux-1.1-pro

Verificado na página de preços do hiapi:

Modelo	Preço por imagem	Cenário de uso
`flux-schnell/text-to-image`	US$ 0,005	Rascunhos, composição de layout, miniaturas em grande volume
`flux-1.1-pro`	US$ 0,05 fixo	Packshots fotorrealistas e imagens em contexto, qualquer resolução até 1440px
`flux-2/text-to-image`	US$ 0,0375–US$ 0,125 (por MP)	Máxima aderência ao prompt, texto nítido dentro da imagem

O preço fixo é a vantagem discreta: um banner principal de 1440×960 e uma miniatura de 512×512 custam os mesmos US$ 0,05, enquanto o flux-2 cobra por megapixel. Se sua carga de trabalho é “fotos de produto fotorrealistas, tamanhos variados”, o flux-1.1-pro é a escolha padrão de custo previsível; se você precisa de contagem exata de objetos ou texto legível impresso na imagem, suba para o flux-2 — nós o testamos aqui com o mesmo conjunto de receitas de e-commerce.

Um PDP de cinco imagens (principal, fundo branco, contexto de uso, duas variantes de cor) soma US$ 0,25 por produto. Renovar um catálogo de 200 SKUs: US$ 50, uma tarde, um script.

Conclusão

O flux-1.1-pro no hiapi entrega fotos de produto fotorrealistas com um fluxo assíncrono de duas chamadas: um intervalo de parâmetros estrito, mas simples (proporção, dimensões, seed, formato — sem mexer com steps/guidance), variantes de cor com seed fixo e um preço fixo de US$ 0,05 que torna o orçamento do catálogo extremamente previsível. Pegue sua API key, comece pela página do modelo flux-1.1-pro e renderize seu primeiro packshot com a chamada curl acima — antes de o café esfriar, você já tem uma imagem pronta para o PDP.