Imagens de produtos de e-commerce com o Imagen 4: prompts, código em lote e controle de qualidade

Resumo

• O Imagen 4 padrão roda na HiAPI como imagen-4.0, com preço de $0.06 por imagem, gerando uma imagem por requisição e suportando apenas texto para imagem. Abra a página do modelo Imagen 4 para testar um prompt primeiro.
• Para catálogos de produtos, ele é adequado para gerar fotos de produto em fundo branco e fotos de ambientação que, de outra forma, exigiriam uma sessão fotográfica para cada cor. Ele não consegue reproduzir o seu SKU real, porque não aceita imagem de referência como entrada.
• aspect_ratio é obrigatório (sem valor padrão) e seed precisa ser uma string numérica. Nas nossas execuções, "seed": "sku-dripper-01" passou na validação, mas cerca de um segundo depois todas as tarefas falharam com TASK_FAILED.
• Planeje uma etapa de controle de qualidade. Em um lote de 4 imagens, recebemos uma jarra de vidro não solicitada, um esmalte brilhante onde pedimos fosco e texto falso em um rótulo de adereço, mesmo com negative_prompt: "text, logo" configurado.

O que este guia cobre

Este é um fluxo de trabalho prático para lojas online, voltado a gerar um conjunto de imagens para uma linha de produtos: uma imagem de catálogo em fundo branco por SKU, uma imagem de ambientação para a página do produto e um recorte vertical para stories no celular. Tudo abaixo foi executado contra a API ao vivo em 2026-11-04, usando um produto fictício: um coador de café de cerâmica verde-acinzentado e uma caneca combinando.

Se você só precisa fazer a primeira requisição funcionar, comece por Como usar a API do Imagen 4. Para modelos genéricos de prompt, consulte Prompts do Imagen 4. Este guia trata de como gerar conjuntos de imagens de loja em lote e revisá-los antes de publicar.

Escolha o nível antes de escrever o prompt

Os três níveis do Imagen 4 na HiAPI são todos texto para imagem e têm a mesma estrutura de requisição: basta alterar o id do model para trocar de nível. Os preços vêm da tabela de preços da HiAPI na data do teste.

Nível	ID do modelo	Preço por imagem	Página do modelo
Fast	imagen-4.0-fast	$0.03	Imagen 4 Fast
Standard	imagen-4.0	$0.06	Imagen 4
Ultra	imagen-4.0-ultra	$0.09	Imagen 4 Ultra

Para catálogos de produtos, a conta é simples. 200 SKUs × (1 imagem de produto + 1 imagem de ambientação) = 400 imagens, o que dá $24 no nível Standard, $12 no Fast e $36 no Ultra, sem contar nenhuma nova tentativa. Este artigo testou apenas o nível Standard, portanto não fazemos nenhuma afirmação sobre a qualidade do Fast ou do Ultra. Para o detalhamento completo de preços, consulte Preços da API do Imagen 4.

Requisição: quatro campos, dois deles propensos a erro

O schema de entrada do imagen-4.0 é fechado. A seguir estão os casos limite que encontramos ao montar o processamento em lote, com as mensagens de erro exatas:

Campo	Regra	O que observamos
prompt	String obrigatória	—
aspect_ratio	Obrigatório, um dos valores 1:1, 16:9, 9:16, 3:4, 4:3, auto	Omitido: aspect_ratio: missing required field "aspect_ratio". "2:1": value must be one of '1:1', '16:9', '9:16', '3:4', '4:3', 'auto'
negative_prompt	String opcional	Aceito. Reduziu o texto nos adereços, mas não o eliminou (veja o controle de qualidade)
seed	String opcional	Número (12): seed: got number, want string. String não numérica ("sku-dripper-01"): aceita com HTTP 200 e depois a tarefa termina com TASK_FAILED. String numérica ("1042"): funciona normalmente
Qualquer outro conteúdo	Rejeitado	additional properties 'foo' not allowed

O problema do seed nos custou uma rodada extra. Usar o código do SKU como seed para rastrear as reexecuções é tentador, e o validador deixou passar. Todas as quatro tarefas do nosso primeiro lote retornaram o seguinte:

{"code":200,"data":{"error":{"code":"TASK_FAILED","message":"task failed"},"model":"imagen-4.0","status":"fail"}}

Depois fomos removendo os campos um a um. O mesmo prompt apenas com negative_prompt teve sucesso; apenas com "seed": "sku-dripper-01" falhou; e "seed": "1042" funcionou. Mantenha o seed numérico e guarde o mapeamento dos SKUs na sua própria tabela de tarefas.

O tamanho da saída depende da proporção. Nas nossas execuções, 1:1 retornou 1024×1024, 4:3 retornou 1152×864 e 9:16 retornou 720×1280, todos em WebP. Se a sua loja precisar de imagens ampliadas de 2000 px, planeje uma etapa de upscale. A saída em si não terá esse tamanho.

Prompts para conjuntos de imagens de catálogo

Escreva os modelos de prompt por tipo de foto e não por produto, e depois preencha com a descrição do produto. Mantenha a iluminação, o ângulo de câmera e o fundo consistentes entre os SKUs, para que a grade de imagens de produto pareça um único catálogo.

Foto de produto (1:1). Especifique o fundo, a composição, uma única direção de luz e a sombra desejada:

Studio packshot of a matte sage-green ceramic coffee mug with a thin loop handle
on a seamless pure white background, centered, handle pointing right, eye-level view,
soft diffused key light from the left, gentle contact shadow, e-commerce catalog photography

O resultado da caneca saiu limpo: a alça aponta para a direita como solicitado, a sombra é suave e o fundo é uniforme. Não precisou de nenhuma edição.

Imagem de ambientação (4:3). Indique o objeto principal, a superfície, a direção da luz e quais adereços devem ficar desfocados. Em seguida, reforce que o produto é o assunto nítido:

Lifestyle product photo: a matte sage-green ceramic pour-over dripper sitting on a glass carafe
on a light oak kitchen counter, morning window light from the right, a bag of coffee beans and a
gooseneck kettle softly out of focus in the background, warm natural tones, shallow depth of field,
the dripper is the sharp hero of the frame

Esse prompt gerou a imagem no topo deste artigo.

Imagem vertical para stories (9:16). Se você for colocar um título no topo, peça explicitamente espaço negativo:

Vertical lifestyle product photo for a mobile story: overhead flat lay of a matte sage-green ceramic
pour-over dripper on a linen napkin, scattered roasted coffee beans, a small ceramic cup of black coffee,
on a pale stone surface, soft even daylight, generous empty space in the top third for a headline

O espaço vazio no terço superior apareceu como solicitado. Mas repare que há grãos inteiros de café dentro do coador: ninguém prepara café assim, e quem compra café vai notar. Veja mais sobre isso abaixo.

Código assíncrono para processamento em lote

A geração de imagens na HiAPI é assíncrona: POST /v1/tasks retorna um taskId, e então você consulta GET /v1/tasks/{taskId} até que status seja success ou fail (veja a documentação da API assíncrona). Para catálogos, envie todas as tarefas de uma vez e consulte em paralelo. Este é o script que executamos, com os prompts encurtados. As duas imagens de ambientação vieram diretamente desse script. As duas imagens de produto foram geradas uma a uma com os mesmos prompts enquanto investigávamos a falha de seed descrita acima (a foto de produto do coador foi gerada sem seed).

import os, time, json, concurrent.futures as cf
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
           "Content-Type": "application/json"}

NEG = "text, logo, watermark, hands, people, clutter, reflections of camera"

JOBS = [
    {"sku": "dripper-white", "aspect_ratio": "1:1", "seed": "1041", "prompt": "Studio packshot of ..."},
    {"sku": "mug-white",     "aspect_ratio": "1:1", "seed": "1042", "prompt": "Studio packshot of ..."},
    {"sku": "dripper-scene", "aspect_ratio": "4:3", "seed": "2041", "prompt": "Lifestyle product photo: ..."},
    {"sku": "dripper-story", "aspect_ratio": "9:16", "seed": "3041", "prompt": "Vertical lifestyle product photo ..."},
]

def submit(job):
    body = {"model": "imagen-4.0",
            "input": {"prompt": job["prompt"], "aspect_ratio": job["aspect_ratio"],
                      "negative_prompt": NEG, "seed": job["seed"]}}  # seed: digits only
    r = requests.post(API, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["taskId"]

def wait(task_id, timeout_s=300):
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30)
        data = r.json()["data"]
        if data["status"] in ("success", "fail"):
            return data
        time.sleep(4)
    raise TimeoutError(task_id)

def run(job):
    t0 = time.time()
    task_id = submit(job)
    data = wait(task_id)
    if data["status"] != "success":
        return {"sku": job["sku"], "status": "fail", "error": data.get("error")}
    url = data["output"][0]["url"]
    img = requests.get(url, timeout=60).content
    path = f"{job['sku']}.webp"
    open(path, "wb").write(img)          # download now: output URLs expire
    return {"sku": job["sku"], "status": "success", "task_id": task_id,
            "seconds": round(time.time() - t0, 1), "bytes": len(img), "file": path}

with cf.ThreadPoolExecutor(max_workers=4) as pool:
    for result in pool.map(run, JOBS):
        print(json.dumps(result))

Três detalhes importam em produção:

1. Tarefas com falha ainda retornam HTTP 200. Verifique data.status == "fail" e data.error.code. Não confie apenas em raise_for_status().
2. Baixe imediatamente. output[0].url é um link temporário com um carimbo de tempo expireAt (cerca de 7 dias depois, nas nossas respostas). Copie os bytes para o seu próprio armazenamento ou CDN. Não faça hotlink dessa URL na sua loja.
3. Registre o id da tarefa junto ao SKU. Quando um revisor rejeitar uma imagem, você precisa saber o prompt, o seed e o id da tarefa que a geraram.

Nas nossas execuções, uma tarefa individual levou de 7 a 8 segundos no servidor (created → completed). As duas tarefas de ambientação em paralelo levaram 31 e 42 segundos de tempo real, incluindo o intervalo de polling de 4 segundos e o download. Com max_workers=4, em lotes pequenos o que domina é a sobrecarga do polling, não o tempo de geração.

Controle de qualidade: o que verificar antes de publicar as imagens

A geração texto para imagem produz produtos plausíveis, não uma foto daquela unidade específica do seu estoque. Cada imagem precisa ser verificada por uma pessoa ou automaticamente contra o SKU real. A seguir estão os problemas que encontramos em um lote de 4 imagens:

Item de verificação	O que aconteceu no nosso lote	Como corrigir
Apenas o produto listado na imagem	A foto de produto do coador incluiu ainda uma jarra de vidro verde combinando com alça, que o prompt nunca pediu (veja a imagem acima).	Adicione "single object, nothing else in frame" e tente de novo. Nunca publique um conjunto que você não vende.
Acabamento de superfície e material	Pedimos esmalte "fosco". As duas imagens do coador voltaram com acabamento brilhante. A caneca ficou mais próxima de acetinado.	Trate as palavras de material como sugestão. Compare com o produto real e rejeite se não corresponder.
Texto em adereços	O saco de café na cena de ambientação tinha uma marca parecida com logo e texto de rótulo ilegível, mesmo com negative_prompt: "text, logo".	Não coloque adereços com rótulo no prompt, ou desfoque-os ou recorte-os. Nunca deixe texto falso entrar em um anúncio de produto.
Lógica do produto	A imagem vista de cima colocou grãos inteiros de café dentro do coador.	Peça a alguém que conheça a categoria do produto para revisar as imagens de ambientação.
Consistência entre imagens	O padrão de nervuras e o formato da base do coador variaram entre a foto de produto, a imagem de ambientação e a vista de cima.	A menos que correspondam ao objeto real, não misture imagens geradas do "mesmo" SKU na mesma página de produto.
Tamanho e proporção	Todas as saídas respeitaram a proporção solicitada (1024², 1152×864, 720×1280).	Verifique automaticamente as dimensões em pixels após o download.

O último ponto é a decisão crítica para a loja. Use o Imagen 4 para banners de categoria, imagens de ambientação de estilo de vida, criativos de anúncios e imagens de espaço reservado para produtos que só existem em especificação. Para fotos de listagem que precisam mostrar o seu produto exato, comece pela foto real e use um modelo de imagem para imagem. Nosso guia de e-commerce com imagem para imagem do Seedream 4.5 detalha esse fluxo de trabalho.

Perguntas frequentes

O imagen-4.0 consegue colocar o meu produto real em uma nova cena? Não. Na HiAPI ele aceita apenas prompt, aspect_ratio, negative_prompt e seed. Não há campo de entrada de imagem, portanto não é possível usar a foto do seu produto como referência.

O negative_prompt remove todo o texto? Nos nossos testes, não. Vale a pena enviá-lo, mas ainda apareceu texto falso em rótulos de adereços de fundo nas cenas de ambientação. A correção confiável é evitar adereços com rótulo.

Por que a minha tarefa falha imediatamente com TASK_FAILED? Verifique primeiro o seu seed. Strings não numéricas como "sku-dripper-01" passam na validação, mas nas nossas execuções todas as tarefas falharam. Use números em formato de string, por exemplo "1042".

Google-Imagen4 é outro modelo? Nos nossos testes, requisições enviadas com "model": "Google-Imagen4" tiveram sucesso, e o payload da tarefa reportou "model": "imagen-4.0". Em código novo, use imagen-4.0.

Próximos passos

Escolha um produto, escreva os três modelos de prompt acima para ele e execute o script em lote contra o modelo Imagen 4. Se você for integrar isso a um pipeline de catálogo, a documentação da API assíncrona cobre autenticação e polling.