Blogue

Guia de uso

muse-image-1.0/text-to-image para imagens de produtos de e-commerce: guia de fluxo de trabalho para desenvolvedores

Templates de prompt para ângulo e iluminação, escolha de tamanho e requisições em lote via API HiAPI

Nov 9, 2026
Fitas de latão fosco e verde-escuro entrelaçadas formando uma treliça aberta sobre um fundo verde quase preto — arte de capa deste guia.
Nesta página

Por que text-to-image se adequa a cargas de trabalho de produtos de e-commerce

Catálogos são essencialmente repetitivos: o mesmo produto, fotografado de alguns ângulos, com a mesma iluminação, sobre o mesmo fundo, em alguns tamanhos. Essa repetição é exatamente o que os modelos text-to-image fazem bem — não para substituir a sessão de estúdio dos produtos principais, mas para preencher a cauda longa do catálogo de forma barata e consistente.

Cenários em que a geração de imagens realmente agrega valor:

  • Variantes em grande volume. Esquemas de cores, pequenas diferenças de SKU e revisões de embalagem, casos em que o custo de refazer a foto supera o valor da própria imagem.
  • Placeholders e materiais de pré-lançamento. Páginas de listagem, materiais de revisão interna e testes A/B que precisam de conteúdo com aparência real antes de as fotos finais ficarem prontas.
  • Exploração de composição. Testar vista superior plana versus imagem principal em 45 graus antes de contratar fotógrafo e agenda de estúdio.

Cenários inadequados: alegações regulamentadas, texto de embalagem que precisa ser legível e preciso, e imagens principais em que o cliente vai comparar texturas finas de materiais. Esses ainda exigem câmera e uma pessoa.

Para o desenvolvedor, o modelo mental é uma linha de montagem. Entra uma descrição estruturada do produto, o template de prompt é renderizado, o modelo devolve uma ou mais imagens, e uma checagem de QA decide o que pode ir para a loja. Cada seção abaixo trata de como tornar essa linha de montagem monótona e repetível, em vez de inteligente.

A linha de montagem de catálogo é como uma trama plana: um prompt entra na estrutura do xadrez, e a mesma estrutura produz várias imagens de produto independentes.

Chamar muse-image-1.0/text-to-image via HiAPI

Todas as requisições passam pela mesma interface HiAPI, então você autentica uma vez e mantém um único cliente para todos os modelos que chamar. O identificador do modelo é muse-image-1.0/text-to-image; sua requisição carrega o prompt, a escolha de tamanho de saída e quaisquer opções de geração única que você queira fixar.

Estruturalmente, uma geração única é: montar o payload da requisição, enviar via POST pelo cliente HiAPI, ler o objeto de resultado retornado e persistir a referência da imagem junto com o ID do produto ao qual ela pertence. Dois hábitos que valem a pena cultivar desde a primeira chamada:

  1. Guardar o prompt em uma variável, não inline na requisição. Você vai reutilizá-lo e compará-lo centenas de vezes.
  2. Registrar o prompt renderizado exato de cada saída. Semanas depois, quando uma imagem parecer errada, o prompt é sua única base de depuração.
import os
from hiapi import HiAPI

client = HiAPI(api_key=os.environ["HIAPI_API_KEY"])

prompt = render_product_prompt(product, angle="three-quarter", light="softbox-left")

result = client.images.generate(
    model="muse-image-1.0/text-to-image",
    prompt=prompt,
    size="1024x1024",
)

save_asset(product_id=product.id, angle="three-quarter", result=result)

Trate size como parte do template, não como uma decisão posterior — o mesmo prompt pode recompor o sujeito em proporções diferentes. As seções seguintes abordam tanto a estrutura do prompt quanto a decisão de tamanho.

A requisição vai do cliente ao endpoint até o modelo, e as fitas trançadas retornam um resultado de imagem.

Templates de prompt para ângulos de captura consistentes

A consistência no catálogo vem de um esqueleto de prompt fixo, com apenas alguns slots substituídos. Se cada prompt for escrito do zero, cada imagem terá desvios. Construa um template por tipo de captura e mantenha a linguagem de descrição de câmera idêntica byte a byte entre todos os produtos.

Um esqueleto que funciona:

{subject_block}. {camera_block}. {light_block}. {background_block}. {style_block}

Só o subject_block varia por produto. O camera_block é constante para cada ângulo:

  • Imagem principal / três quartos: product photographed at a 45-degree three-quarter view, slightly above eye level, full product in frame with even margins
  • Frontal: straight-on front view, camera at product mid-height, centered, no perspective tilt
  • Vista superior plana: directly overhead top-down view, product centered, flat lay composition
  • Close de detalhe: close-up macro view of the product surface, shallow depth of field

Duas regras fazem isso funcionar na prática:

  • Declare o ângulo duas vezes. Um ângulo explícito somado a uma cláusula de enquadramento (como "full product in frame with even margins") é mais confiável do que qualquer um dos dois isoladamente.
  • Evite referências relativas. "Same angle as the last image" não significa nada para um modelo text-to-image; cada prompt precisa ser autossuficiente.

Mantenha os templates sob controle de versão junto com o código de renderização. Quando alterar o camera_block, incremente a versão e regenere uma pequena amostra antes de comitar — uma mudança de redação é uma mudança em todo o catálogo.

Templates de prompt para iluminação e fundo

Iluminação e fundo são o que faz um conjunto gerado parecer a mesma sessão fotográfica, em vez de um monte de imagens sem relação. Ambos pertencem à parte constante do template e precisam de direção e suavidade explícitas.

Linguagem de iluminação que transfere de forma confiável:

  • Direção: key light from camera left, light from upper right, soft overhead light. A direção é a alavanca mais direta de consistência — fixe-a por tipo de captura.
  • Qualidade: soft diffused light, large softbox, gentle shadows, hard directional light with defined shadow edge.
  • Preenchimento e spill: subtle fill from the right, low-contrast shadows, clean highlight on the top surface.

Linguagem de fundo:

  • Estúdio infinito: on a seamless light grey studio backdrop, no horizon line, soft contact shadow beneath the product.
  • Superfície lifestyle: resting on a matte stone surface, softly out-of-focus neutral background.
  • Pronto para recorte: isolated on a plain white background, product fully in frame, generous margins for cropping.

Dois lembretes práticos. Primeiro, quanto mais superfícies reflexivas o produto tiver, mais precisa deve ser a descrição da iluminação, porque a posição dos realces é a aparência do produto. Segundo, não misture fundos dentro do mesmo tipo de captura — um conjunto de tiles de grade deve compartilhar o fundo, senão a grade parece montada a partir de três fornecedores diferentes. Fixe esses blocos como constantes e só os altere de forma deliberada.

Escolher tamanhos de saída e proporções

Antes do processamento em lote, decida o tamanho por posicionamento, porque reexecutar com um tamanho diferente é uma nova geração completa, não um redimensionamento. Primeiro mapeie o posicionamento para uma proporção, depois para a dimensão em pixels que o front-end realmente renderiza.

  • Grades e tiles de categoria: quadrado. Recortes de grade de produtos são imprevisíveis, então uma composição quadrada com margem generosa se adapta à maioria dos layouts de tile.
  • Páginas de detalhe do produto: quadrado ou 4:3, dimensionado para o visualizador com zoom, não para a miniatura. Se a página de detalhe corta em proporção fixa, corresponda exatamente a ela em vez de brigar com o CSS.
  • Banners e faixas principais: formato largo, com zonas de segurança planejadas explicitamente. Peça o produto centralizado com espaço negativo nas laterais, para que o texto de marketing tenha onde ficar.
  • E-mail e redes sociais: corresponda à proporção nativa da plataforma; regerar sai mais barato do que preencher com bordas.

Algumas regras práticas:

  1. Escolha um tamanho canônico por posicionamento e reuse-o. Misturar tamanhos em uma grade de tiles produz diferenças visíveis de qualidade.
  2. Não amplie imagens geradas para preencher posicionamentos maiores. Gere em tamanho maior e reduza.
  3. Revalide a composição quando a proporção mudar. Uma imagem principal em 45 graus composta para quadrado pode perder a base do produto em um recorte largo; ajuste a cláusula de enquadramento no camera_block conforme necessário.
  4. Mantenha o tamanho no registro da tarefa. Ao revisar saídas depois, o tamanho faz parte do contexto, não é ruído de metadados.

Requisições em lote e processamento de resultados item a item

Na escala de catálogo, a unidade de trabalho é a tarefa, não a requisição: um produto, um tipo de captura, um tamanho, um prompt renderizado. Modele primeiro a tarefa como dado e envie por uma fila com limite de concorrência, para que uma falha seja uma linha que pode ser reexecutada, e não uma tarde perdida.

Um loop robusto faz quatro coisas:

  • Renderizar o prompt de forma determinística: a partir do template mais os campos do produto, e armazenar a string renderizada na tarefa.
  • Limitar a concorrência: ao que sua conta e o armazenamento downstream suportarem; não dispare o catálogo inteiro de uma vez.
  • Processar os resultados item a item. Operações em lote têm sucesso ou falha por item, então grave cada resultado sob seu job_id e nunca assuma que o lote inteiro é atômico.
  • Repetir com backoff apenas em erros transitórios. Erros de validação — prompts malformados, tamanhos não suportados — falham da mesma forma ao repetir, então classifique antes de tentar de novo.
for job in queue.fetch_pending(limit=50):
    try:
        result = client.images.generate(
            model="muse-image-1.0/text-to-image",
            prompt=job.prompt,
            size=job.size,
        )
        db.record_success(job.id, result)
    except TransientError as e:
        queue.requeue(job.id, backoff=e.retry_after)
    except ValidationError as e:
        db.record_failure(job.id, reason=str(e))

Mantenha uma coluna de status por tarefa (pending, done, failed) e ofereça uma visão de dead letter para as falhas. Quando um lote de tarefas terminar, reporte contagens por tipo de captura e tamanho, não apenas um total — é aí que as regressões se escondem.

Checklist de QA antes de publicar imagens geradas

Imagens geradas precisam de um portão, e o portão deve ser um checklist com alguém responsável por trás. Verificações automatizadas pegam os problemas baratos; revisores pegam os caros.

Verificações automatizadas antes da revisão:

  • Proporção e dimensões em pixels corretas para o posicionamento de destino.
  • Nenhuma saída visivelmente corrompida; os arquivos abrem e decodificam sem erro.
  • Cores conforme esperado quando o prompt especifica a cor do produto.
  • Margem suficiente nos tiles de grade para tolerância de recorte.

Revisão humana antes da publicação:

  • O produto parece este produto — forma, proporções, ferragens e acabamento?
  • Há texto, logos ou textos de embalagem inventados? Texto gerado é um ponto de falha comum e um risco jurídico na loja.
  • Iluminação e fundo consistentes com o restante do grupo em tamanho de miniatura, não só em tamanho real.
  • Nenhum objeto estranho, componente extra ou reflexo ilógico na cena.
  • Alegações de marketing e rótulos regulamentados não foram alterados pela geração; essas imagens devem passar pelo fluxo fotográfico.

Registre o revisor e a versão do prompt para cada asset aprovado. Quando chegar uma reclamação de cliente ou pedido de remoção, essa trilha permite encontrar de uma vez todas as imagens afetadas — e regerar ou retirar o conjunto inteiro.

Comece com um tipo de captura, um tamanho e uma pequena amostra de produtos, execute pela interface HiAPI e só expanda os templates depois que as saídas passarem na revisão.

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