Blogue

Guia de uso

Gerar imagens de produtos de e-commerce com flux-3 pela API HiAPI

Modelos de prompt, controle de fundo e iluminação, e uma requisição executável de geração de fotos de produto

Nov 12, 2026
Arte de capa em estilo de hachura gravada: linhas paralelas de cobre sobre azul-da-meia-noite formam molduras de produto abstratas e uma linha de montagem em degraus.
Nesta página

Por que o flux-3 é adequado para fotos de produtos de e-commerce

Os pipelines de catálogo de produtos falham por motivos geralmente entediantes: consistência. Uma página de produto não é uma única imagem principal, mas dezenas de imagens que abrangem vários SKUs, vários ângulos e atualizações sazonais, e todas precisam parecer ter sido fotografadas na mesma tarde, no mesmo estúdio. Entregar cada uma a um fotógrafo é lento e caro; entregar cada uma a qualquer gerador de imagens geralmente resulta em um conjunto de imagens que, isoladamente, parecem razoáveis, mas juntas ficam estranhas.

É exatamente aí que o flux-3 é útil. Ele é um modelo de geração de imagens disponibilizado pela API HiAPI, o que significa que seu pipeline de produtos pode tratar a criação de imagens como mais uma chamada HTTP: envie o prompt mais os parâmetros do produto, receba uma imagem, armazene-a e passe para o próximo SKU. Sem SDK exclusivo do fornecedor, sem abrir conta separada para cada modelo e sem escrever código de integração para cada provedor.

O que importa especialmente para e-commerce é que o flux-3 responde de forma previsível à estrutura do prompt. Foto de produto é um cenário altamente restrito: um único sujeito, centralizado ou deliberadamente enquadrado, fundo limpo e iluminação de estúdio. Essas restrições são justamente o que você pode expressar em texto e, uma vez que virem texto, tornam-se variáveis de modelo em vez de decisões criativas. É a diferença entre “pedir uma imagem ao modelo” e ter uma etapa de geração dentro de uma tarefa de catálogo.

O fluxo de trabalho prático deste guia é: definir uma estrutura de prompt reutilizável, ajustar a redação de fundo e iluminação até que a linha de base pareça correta e então substituir o bloco do sujeito por produto. Todo o resto permanece igual, e é isso que garante consistência visual em uma linha de produtos.

O que você precisa antes de começar

  • Uma chave de API da HiAPI e o identificador atual do modelo flux-3 obtido na lista de modelos da plataforma.
  • Dados do produto em formato estruturado: nome, material, cor, forma e quaisquer detalhes marcantes que você queira que o modelo renderize.
  • Um lugar para guardar o prompt de linha de base e as saídas geradas, para que você possa comparar versões depois.
Um produto, renderizado de forma consistente em nove fundos controlados — essa é a promessa do flux-3 para a consistência de catálogo.

A composição de um prompt de foto de produto com flux-3

Um prompt que só funciona para um produto tem pouca utilidade. Um prompt que você pode preencher é útil. A forma de chegar lá é dividir a descrição em blocos fixos, cada um correspondendo a uma variável no seu código.

Os cinco blocos

  • Sujeito. O que é o objeto, descrito com substantivos concretos. “Uma caneca de café de cerâmica fosca” é melhor que “uma caneca bonita”. Adicione pistas de escala quando importarem (“alta”, “de boca larga”).
  • Material e superfície. Acabamento e textura: alumínio escovado, cerâmica esmaltada, algodão trançado, vidro fosco. Os reflexos do modelo vêm daqui, então seja explícito.
  • Fundo. O fundo e a superfície onde o produto está: papel sem emenda, ardósia, degradê suave, fundo infinito branco puro. Mantenha este bloco deliberadamente curto e entediante — ele é andaime, não espaço criativo.
  • Iluminação. Direção, qualidade e contraste: luz principal suave vinda da esquerda, fonte difusa ampla, preenchimento suave, sombra sutil sob o objeto. Este bloco determina a maior parte da sensação “de estúdio” e é o que você mais vai ajustar.
  • Enquadramento de câmera. Como a lente compõe: foto de produto centralizada, na altura dos olhos, ângulo de três quartos, corte fechado, bastante espaço negativo acima.

Transformando os blocos em um modelo

Esses blocos são montados em uma string em tempo de execução, substituindo apenas o sujeito (e ocasionalmente o material) por SKU:

product photo of {subject}, {material}, {background}, {lighting}, {framing}

Um exemplo preenchido:

product photo of a matte ceramic coffee mug, glazed stoneware with visible clay texture,
on a seamless light gray paper backdrop, soft diffused key light from the upper left
with gentle fill and a soft contact shadow, centered eye-level shot with negative space above

Duas regras mantêm o modelo estável. Primeiro, mantenha a ordem dos blocos fixa — mesmo com texto idêntico, reordenar os blocos muda a ênfase. Segundo, ao percorrer SKUs, mantenha os blocos fixos como exatamente a mesma string, em vez de reescrevê-los a cada vez; pequenas variações de redação são a causa mais comum de fundos e iluminações inconsistentes em um catálogo.

Onde a criatividade não deve aparecer

Evite linguagem editorial nos blocos fixos: nada de adjetivos emocionais, nada de floreios de styling, nada de referências a cenários. Deixe qualquer variação para campanhas de marketing intencionais e mantenha o modelo de catálogo limpo. Um modelo que se lê como especificação técnica produz imagens que parecem especificação técnica — que é exatamente o que uma listagem de produto precisa.

Cada bloco do prompt — sujeito, material, fundo, iluminação, enquadramento — é uma placa intercambiável que você pode reordenar e reutilizar.

Controle de fundo e iluminação

Fundo e iluminação são os dois blocos que determinam se um conjunto de imagens se lê como um catálogo coerente. Ambos respondem bem a linguagem concreta e física.

Fundo: busque o entediante

Descreva o fundo como uma montagem física, não como estética. “Fundo de papel cinza-claro sem emenda” e “fundo infinito branco puro” são confiáveis porque descrevem uma configuração de estúdio conhecida. Palavras como “minimalista” ou “estético” são vagas e costumam deixar elementos de cena vazarem.

Alavancas úteis:

  • Tipo de superfície: papel sem emenda, vinil fosco, ardósia natural, madeira clara.
  • Cor e tom: cinza-claro, branco-creme, areia quente — mantenha a luminosidade de média a clara, para que as bordas do produto permaneçam legíveis.
  • Continuidade: “sem emenda” ou “infinito” dizem ao modelo que você quer que fundo e chão se fundam, eliminando a linha do horizonte que é difícil de limpar depois.
  • Vazio: se tentativas iniciais introduzirem objetos estranhos, vale escrever explicitamente “fundo vazio, sem adereços”.

Se você precisa de PNGs com fundo transparente para marketplaces, gere primeiro sobre um fundo sólido limpo e depois faça o recorte no pós-processamento. Pedir ao modelo de imagem para produzir um canal alfa real não é um caminho confiável.

Iluminação: direção primeiro, qualidade depois

A redação da iluminação se divide claramente em duas decisões. A direção determina onde os realces e as sombras caem; a qualidade determina quão suaves são as bordas desses realces.

  • Direção: “luz principal vinda do canto superior esquerdo”, “luz principal suave vinda da frente”, “luz vinda da direita, com preenchimento suave à esquerda”. Escolha uma e mantenha em toda a linha de produtos.
  • Qualidade: “fonte difusa ampla”, “sombras suaves”, “iluminação uniforme”. Luz difusa suave é o padrão seguro para fotos de produto, porque não estoura materiais brilhantes.
  • Sombra de contato: “sombra de contato suave sob o produto” assenta o objeto; sem ela, o produto parece flutuar.
  • Contraste: “baixo contraste, claro e uniforme” funciona para marketplaces de fundo branco; um pouco mais de contraste direcional funciona para cortes lifestyle premium.

Mantenha a linha de produtos consistente

Consistência tem menos a ver com prompts e mais com gestão de versões. Armazene os blocos de fundo e iluminação como presets nomeados (por exemplo, um preset “estúdio branco” e um preset “ardósia”) e, em cada tarefa de geração, referencie o preset pelo nome em vez de colar o texto por SKU. Quando você ajusta um preset, ajusta uma vez só, e o próximo lote herda a mudança de forma intencional, em vez de sofrer deriva.

Quando um resultado sair errado, mude um bloco por vez e regenere o mesmo produto. Mudar fundo e iluminação ao mesmo tempo impede saber qual trecho de redação surtiu efeito.

Setas de direção de luz e amostras de fundo: como a redação do prompt se mapeia em uma aparência consistente de linha de produtos.

Uma requisição HiAPI para flux-3 executável

A etapa de geração é uma chamada de API. O caminho exato do endpoint, o identificador do modelo e os campos da requisição estão documentados na plataforma e devem ser obtidos lá, porque podem evoluir; a forma abaixo é o padrão a ser conectado ao seu script.

import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]

presets = {
    "white_studio": {
        "background": "on a pure white infinity sweep, no props, empty backdrop",
        "lighting": "soft diffused key light from the upper left, even fill, "
                    "soft contact shadow beneath the product, low contrast",
        "framing": "centered eye-level product shot, generous negative space",
    }
}

def build_prompt(product, preset_name="white_studio"):
    p = presets[preset_name]
    return (
        f"product photo of {product['subject']}, {product['material']}, "
        f"{p['background']}, {p['lighting']}, {p['framing']}"
    )

def generate(product, preset_name="white_studio"):
    payload = {
        "model": "flux-3",           # confirme o identificador atual na lista de modelos
        "prompt": build_prompt(product, preset_name),
    }
    response = requests.post(
        "https://api.hiapi.ai/v1/images/generations",  # consulte a documentação para o caminho exato
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

product = {
    "subject": "a matte ceramic coffee mug",
    "material": "glazed stoneware with visible clay texture",
}

result = generate(product)
print(result)

Conectando ao processamento em lote

Alguns hábitos permitem que isso rode com segurança no catálogo inteiro, em vez de em um único produto:

  • Resolva cada valor a partir de variáveis de ambiente. Mantenha as chaves fora do código-fonte e dos logs.
  • Trate a resposta como não confiável. Leia a referência ou o payload da imagem retornada a partir do campo documentado e depois baixe e armazene no seu próprio bucket. Não confie em nenhuma URL temporária que dure mais que a tarefa.
  • Registre a string exata do prompt junto com cada saída. Armazene-a com os metadados da imagem. Quando alguém perguntar mais tarde por que a imagem do SKU 1234 parece diferente, a resposta deve estar no seu banco de dados, não na memória.
  • Use novas tentativas com backoff para falhas transitórias e limite a concorrência, para que lotes grandes não disparem limites de taxa.
  • Mantenha as requisições idempotentes por SKU e versão de prompt, para que reexecuções sobrescrevam o mesmo slot de saída em vez de espalhar duplicatas.

Da iteração de modelo ao pipeline de produção

O primeiro prompt validado é a linha de base, não o ativo final. Colocar em produção significa transformá-lo em algo que seu pipeline possa reproduzir e auditar.

Passo 1: trave a linha de base em uma pequena amostra

Gere de cinco a dez produtos em diferentes categorias de material — um brilhante, um fosco, um de tecido, um metálico, um transparente. Eles testam o bloco de iluminação de maneiras diferentes. Se o modelo se mantiver nessa amostra, você tem uma linha de base; se produtos brilhantes estourarem ou tecidos parecerem planos, ajuste esse bloco agora, não depois que o catálogo inteiro rodar.

Passo 2: nomeie e versione os presets

Dê ao preset um identificador de versão explícito e trate mudanças como uma nova versão, não como uma edição. Um esquema simples white_studio_v1 → white_studio_v2 permite regerar um lote com o preset antigo e comparar, e também permite fazer rollback se uma “pequena melhoria” acabar sendo uma regressão em metade dos seus SKUs.

Passo 3: guarde o prompt onde o pipeline possa lê-lo

Mantenha duas camadas: a definição compartilhada do preset (fundo, iluminação, enquadramento, versão) em um único lugar, e os campos de sujeito e material de cada SKU no seu banco de dados de produtos. O código de geração então combina os dois. Isso significa que mudanças no preset se propagam para toda tarefa futura, enquanto os dados do sujeito continuam sob responsabilidade da equipe de catálogo.

Passo 4: compare saídas de forma sistemática

A revisão lado a lado não escala depois de algumas dezenas de SKUs. Sinais mais baratos:

  • Revisão por folha de contatos: monte um lote em uma única grade e procure anomalias. Fundos com deriva e enquadramentos deslocados saltam aos olhos em tamanho de miniatura.
  • Amostragem de bordas contra o fundo: amostre cores de pixel perto das bordas da imagem e sinalize resultados cujos cantos diferem do tom esperado do preset. Isso captura a falha mais comum — o fundo mudando de cor sem aviso — sem precisar de olho humano.
  • Verificação de posição no quadro: se o produto deve estar centralizado com espaço negativo acima, meça onde a massa do sujeito está em cada imagem e sinalize anomalias.

Qualquer item sinalizado entra na fila de revisão; todo o resto é publicado automaticamente.

Passo 5: regenere com intenção

Uma vez que a linha de base esteja estável, um novo SKU é um problema de dados, não de prompt: adicione os campos de sujeito e material, enfileire a tarefa e deixe a automação cuidar do resto. Reserve execuções de regeneração para mudanças intencionais — fundos sazonais, novas variantes de iluminação — e, ao fazê-lo, aumente a versão do preset.

Armadilhas comuns e como evitá-las

A maioria das falhas ao gerar imagens de produto se resume aos mesmos poucos problemas, cada um com uma correção no lado do prompt ou no lado do pipeline.

Deriva de fundo entre lotes

A reclamação mais comum: imagens consistentes isoladamente, mas diferentes entre SKUs. Quase sempre é deriva de redação — alguém reescreveu o bloco de fundo, ou o modelo inseriu atributos do produto nele. Correção: trate fundo e iluminação como strings fixas vindas de uma única fonte de preset e, no código, verifique que o prompt montado contém literalmente o texto do preset.

Adereços e elementos de cena estranhos

O modelo adora adicionar cenário: um raminho de folhas, um pano dobrado, uma sombra que parece borda de mesa. Declare explicitamente o vazio (“fundo vazio, sem adereços”) e mantenha a linguagem de cena o mais física e restrita ao estúdio possível. Se persistir, simplifique a descrição do sujeito — adjetivos decorativos no bloco do sujeito costumam atrair decoração correspondente na cena.

Produtos flutuando

Sem sombra de contato, o objeto parece colado ao fundo. Inclua “sombra de contato suave sob o produto” no bloco de iluminação e deixe explícito que o produto está apoiado sobre uma superfície, não suspenso.

Enquadramento inconsistente

Misturar cortes arruína uma página de categoria. Fixe o bloco de enquadramento em uma única frase e não o deixe variar; se precisar de várias proporções, gere a mesma composição e corte no pós-processamento, em vez de fazer prompts para cada proporção.

Prompts excessivamente especificados

Prompts longos que descrevem a história, a marca e o enredo do produto tendem a produzir imagens editoriais, não imagens de catálogo. O modelo deve se ler como uma lista de planos. Quando o resultado parecer errado, a correção geralmente é remover palavras, não adicionar.

Tratar falhas de geração como defeito de código

Um resultado ruim isolado não é sinal para reescrever o pipeline. Reproduza-o com a string exata de prompt armazenada, mude um bloco, regenere e só então tire conclusões. Registrar o prompt junto com cada saída é justamente o que torna isso possível — e é o hábito de menor custo para se adquirir desde o início.

Comece com um preset, um lote de amostra e o prompt armazenado por imagem; expanda depois que a linha de base se mantiver em todos os tipos de material.

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API