Gerar imagens de produtos de e-commerce com z-image via API hiapi

A maioria dos modelos de imagem consegue desenhar um produto. Muito menos conseguem desenhá-lo bem e escrever o preço corretamente. Para cenários de e-commerce — etiquetas de preço, banners promocionais, cartões de desconto, rótulos de embalagem — o texto dentro da imagem é o que importa, e um único caractere ilegível significa que o material é rejeitado.

z-image é um modelo texto-para-imagem de nível Turbo no hiapi, criado exatamente para esse nicho: geração rápida de imagens fotorrealistas, texto dentro da imagem (inglês e chinês) preciso, e preço de $0.008 por imagem — menos de um terço do preço da maioria das alternativas. Cada imagem neste guia foi gerada com ele usando exatamente o prompt mostrado ao lado dela, por meio da mesma chamada /v1/tasks que você copiará abaixo, e cada renderização leva cerca de 30–60 segundos de ponta a ponta.

Por que escolher z-image para imagens de produto

Três atributos importam para um pipeline de e-commerce, e z-image se sai bem nos três:

• Renderização de texto. Seguindo as regras de prompt abaixo, cartões promocionais, banners de logística e rótulos de garrafa voltam com cada palavra escrita corretamente.
• Velocidade. É um modelo com ajuste Turbo; nossas renderizações de teste concluíram bem menos de um minuto todas as vezes, o que permite processar as imagens de centenas de SKUs em lote no tempo de um café.
• Preço. A $0.008/imagem (verificado na página de preços), atualizar um catálogo de 1.000 imagens custa $8. A mesma tarefa com gpt-image-2 ($0.03/imagem) custaria $30.

Se você quiser uma visão mais completa do modelo — configuração de chave, exemplos gerais, quando não usá-lo — consulte Z-Image API: preços, chave de API, exemplos e quando usar. Este guia concentra-se no fluxo de trabalho de e-commerce.

Interface de API verificada

z-image roda no endpoint de tarefas assíncronas do hiapi. Você envia a tarefa, faz polling até o sucesso e então baixa a saída. Confirmamos dois fatos de schema contra a API em produção (ambos diferem de alguns outros modelos da plataforma):

1. input aceita apenas prompt e aspect_ratio. Enviar um campo resolution retorna HTTP 400 (additional properties not allowed) — diferente de gpt-image-2, que exige esse campo.
2. aspect_ratio deve ser um de 1:1, 4:3, 3:4, 16:9, 9:16. Qualquer outro valor (testamos 3:2) é rejeitado com 400, listando os valores válidos.

A resolução de saída é fixa por proporção — nossas renderizações voltaram como PNG: 1536×1536 (1:1), 1344×768 (16:9), 928×1232 (3:4) e 1728×1296 (4:3).

Enviar a tarefa

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-image",
    "input": {
      "prompt": "Studio e-commerce product photo: a matte black insulated steel water bottle on a seamless light-gray background...",
      "aspect_ratio": "1:1"
    }
  }'

A resposta traz um id de tarefa:

{"code": 200, "data": {"taskId": "tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG"}}

Fazer polling e baixar

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01KWGHSXWH8J1Z2CADYNQQ8GDG \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Faça polling a cada poucos segundos até que data.status seja success e data.output exista; trate fail como estado terminal. Uma dica prática: logo após a geração, a tarefa pode relatar brevemente um estado intermediário (observamos archiving) antes que o array output apareça, então seu loop deve depender da existência da URL de saída, não apenas da string de status.

import os, time, requests

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

def generate(prompt: str, ratio: str = "1:1") -> bytes:
    r = requests.post(API, headers=HEADERS, json={
        "model": "z-image",
        "input": {"prompt": prompt, "aspect_ratio": ratio},
    }, timeout=60)
    task_id = r.json()["data"]["taskId"]

    deadline = time.time() + 300
    while time.time() < deadline:
        task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        output = task.get("output") or []
        if output and output[0].get("url"):
            return requests.get(output[0]["url"], timeout=120).content
        if task.get("status") == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(5)
    raise TimeoutError(task_id)

png = generate("...your product prompt...", "1:1")
open("product.png", "wb").write(png)

Baixe imediatamente. output[0].url é um link temporário com um carimbo de tempo expireAt — persista os bytes no seu próprio armazenamento (S3/R2/CDN) assim que a tarefa tiver sucesso. Se a tarefa parecer travada, aqui está como diagnosticar tarefas hiapi travadas ou com timeout.

Cinco receitas de e-commerce, com saídas reais

Todas as imagens abaixo são renderizações reais do z-image geradas a partir dos prompts exatos mostrados. Sem retoques.

1. Imagem principal com etiqueta de preço

Studio e-commerce product photo: a matte black insulated steel water bottle centered
on a seamless light-gray background with soft shadow. A rectangular coral paper card
leans against the bottle. The card contains ONLY these two lines of bold clean
sans-serif text and no other words: "SUMMER SALE" on line one, "$19.99" on line two.
Text flat-on to camera, large, perfectly legible. Photorealistic.

Observe a formulação: o texto exibido fica entre aspas e o prompt diz que o cartão contém apenas essas palavras. Em nossa primeira tentativa, descrevemos o texto inline ("...reads exactly: SUMMER SALE on the first line and $19.99 on the second line") e o modelo fielmente compôs a palavra "ON" entre as duas linhas — as palavras de instrução vazaram para o render. Cite as strings literais; mantenha as instruções fora das aspas.

2. Banner promocional horizontal

Wide e-commerce promo banner, photorealistic flat-lay of white sneakers and a kraft
shipping box on a pastel blue background. On the right side, bold navy sans-serif
text with exactly these four words and amount, nothing else: "FREE SHIPPING OVER $50".
All four words must appear. Text large, straight, perfectly legible. Clean commercial
studio lighting.

16:9 gera um banner de 1344×768, pronto para a posição de destaque da página inicial da sua loja.

3. Cartão de desconto vertical para redes sociais

Vertical social-media product card: a small brown glass cosmetic dropper bottle on a
warm beige podium, soft daylight. Above the bottle, bold black modern sans-serif
headline text reads exactly: 30% OFF TODAY ONLY. Text flat to camera, large and
perfectly legible. Minimalist premium e-commerce style, photorealistic.

3:4 (928×1232) é a proporção mais próxima do formato de post de feed; se sua plataforma exigir, corte para 4:5 a jusante.

4. Rótulo de embalagem legível

Macro e-commerce product photo of a frosted glass skincare bottle with a clean white
label. The label text, printed in elegant dark sans-serif, reads exactly: GLOW SERUM
on the first line and VITAMIN C 10% on the second line. Straight-on angle, label
fully visible and sharp, soft studio lighting, photorealistic, white background.

Este é o teste mais difícil do grupo — texto pequeno em vidro curvo — e o rótulo voltou limpo, incluindo o "10%".

5. Linha de cores (sem texto)

E-commerce catalog photo: three identical ceramic coffee mugs lined up left to right
in sage green, terracotta orange, and navy blue, on a plain white studio background
with soft even shadows. No text anywhere in the image. Photorealistic, consistent
product geometry across all three mugs.

A geometria consistente entre as variantes é exatamente o que a torna utilizável como faixa de catálogo — o z-image manteve as três canecas coloridas com exatamente o mesmo formato em uma única geração.

Regras de prompt que fazem o texto sobreviver

Destiladas do que realmente funcionou (e falhou) em nossos testes:

1. Coloque as strings literais entre aspas. text reads exactly: "SUMMER SALE" — o modelo trata as palavras ao redor sem aspas como candidatas a texto.
2. Acrescente "and no other words" (e nenhuma outra palavra). Caso contrário, o modelo pode inventar textos extras de selo para preencher o espaço.
3. Mantenha o texto de frente para a câmera. Nosso único render ilegível foi texto pendurado em ângulo em uma etiqueta; o mesmo texto em um cartão plano saiu perfeito. A distorção de perspectiva é onde os glifos quebram primeiro.
4. Um a dois blocos de texto por imagem. Cada bloco de texto adicional multiplica a probabilidade de falha; para layouts complexos, componha a jusante.
5. Valide antes de publicar. A esse preço, você pode arcar com um ciclo de nova tentativa: renderize, faça OCR ou inspeção visual do texto, regenere se não corresponder. Mesmo com uma nova tentativa por imagem com falha, o custo é apenas uma fração do de modelos alternativos.

Custo em lote

Um cenário concreto: 200 SKUs × 3 materiais cada (imagem de listagem de produto, banner promocional, cartão social) = 600 imagens.

Modelo	Preço/imagem	600 imagens	Observações
z-image	$0.008	$4.80	Velocidade Turbo, forte desempenho de texto na imagem
flux-schnell	$0.005	$3.00	O mais barato, mas sem foco em renderização de texto
qwen-image-2.0	$0.025	$15.00	Forte qualidade geral
gpt-image-2	$0.03	$18.00	Exige o campo resolution; veja o guia de e-commerce aqui

(Preços obtidos da página de preços do hiapi na data de publicação.)

O modo em lote é apenas colocar a função generate() acima em um loop — envie alguns poucos em paralelo, colete os ids de tarefa e então faça polling em grupos. Se você for escalar bastante, leia primeiro como o hiapi lida com limites de taxa e picos de tráfego.

Começando

Obtenha uma chave de API no seu console e aponte o snippet acima para o seu próprio catálogo de produtos — a página do modelo z-image tem o model card, e a documentação do hiapi cobre a API de tarefas em detalhes. A $0.008 por render, a maneira mais barata de descobrir se ele se encaixa no seu pipeline é testá-lo nos seus dez SKUs mais difíceis esta tarde.