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

qwen-image-2.0 é o modelo de texto-para-imagem de segunda geração da Alibaba, disponibilizado pela interface /v1/tasks do hiapi a $0,025 por imagem, com saída padrão em 2K. Para e-commerce, ele tem duas características especialmente interessantes: nessa faixa de preço, a renderização de texto em chinês é a mais limpa entre todos os modelos de texto-para-imagem atuais; além disso, sua aderência ao prompt em briefings longos e detalhados de produtos é muito estável — exatamente o que listings transfronteiriços realmente precisam.

Este guia é a versão executável do fluxo de trabalho. Cada chamada de API é algo que você pode colar direto no terminal, os modelos de prompt foram testados e renderizados no endpoint ao vivo, e o preço por imagem é o número em tempo real da tabela de preços do HiAPI. Não há nada teórico aqui: os valores de custo pressupõem os valores de size que o qwen-image-2.0 realmente aceita, não números de marketing.

Por que escolher qwen-image-2.0 para imagens de produtos transfronteiriços

Quando você precisa levar 200 SKUs de uma vez para listings de marketplace, três coisas importam.

1. Renderização de texto chinês. A maioria dos listings de e-commerce vendidos para China continental, Hong Kong, Taiwan ou Sudeste Asiático precisa de texto chinês legível em embalagens, banners ou rótulos. O qwen-image-2.0 é o único no hiapi em que você pode escrever um prompt como “o rótulo da garrafa traz 玫瑰精华水 em chinês serifado em negrito” e o modelo renderiza esses glifos exatos na posição exata que você descreveu.
2. Aderência ao prompt em briefings longos de produtos. Briefings de e-commerce são longos: material, hex de cor, acabamento superficial, direção da luz, formato da sombra, cor de fundo, ângulo da câmera. Quando o briefing cresce, o qwen-image-2.0 mantém a coerência geral — o modo de falha costuma ser apenas um item faltante, não uma invenção do produto.
3. Faixa de custo que suporta explosão de variantes. Uma página típica de SKU quer 4–6 imagens (foto de estúdio, cena, vista superior, comparação de escala, duas variantes). A $0,025 por imagem, isso dá $0,10–$0,15 por SKU. Um lançamento de 200 SKUs custa $20–$30. É exatamente essa faixa de custo que torna “gerar tudo do zero” mais barato do que encomendar fotos parciais e complementar com banco de imagens.

Para ver experimentos de ajuste de prompt linha a linha e seis receitas voltadas a estilo em vez de e-commerce, consulte o artigo complementar receitas de prompt do qwen-image-2.0. Este artigo foca em cenários de catálogo.

Schema de entrada do qwen-image-2.0 no hiapi

O qwen-image-2.0 roda na interface unificada /v1/tasks, que também é o único endpoint de imagem oferecido atualmente pelo hiapi. Antes de escrever qualquer código, há uma regra especial que vale acertar primeiro:

• O parâmetro de tamanho se chama size — não aspect_ratio, não resolution, nem image_size. Outros modelos no hiapi (nano-banana, linha flux) aceitam aspect_ratio; o qwen-image-2.0 não aceita.
• O separador dentro de size é *, não x. "size": "2688x1536" retorna 400; "size": "2688*1536" funciona corretamente.
• Apenas cinco valores de size são aceitos. Todos são 2K:

Proporção	Valor de size	Uso
16:9 (aprox. 1,75:1)	2688*1536	Imagem principal, banner, capa de listing
4:3 (aprox. 1,37:1)	2368*1728	Página dupla estilo revista, espaço publicitário de duas colunas
1:1	2048*2048	Foto de estúdio quadrada, miniatura de marketplace
3:4 (aprox. 0,73:1)	1728*2368	Páginas de produto mobile-first
9:16 (aprox. 0,57:1)	1536*2688	Capa de vídeo vertical, frame estático para TikTok/Reels

Se você enviar qualquer outro valor, a API retorna a lista literal de valores permitidos no erro:

{"code": 400, "message": "invalid input: size: value must be one of '2688*1536', '2368*1728', '2048*2048', '1728*2368', '1536*2688'"}

Trate essa mensagem de erro como a fonte autoritativa da verdade — se no futuro você vir um novo valor ali, significa que a plataforma expandiu o schema.

Uma requisição executável

Toda a superfície de chamada tem apenas dois endpoints: POST /v1/tasks para enfileirar, GET /v1/tasks/{taskId} para consultar. Abaixo está a requisição mínima que produz a foto de estúdio mostrada abaixo.

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.0",
    "input": {
      "prompt": "A clear glass cosmetic dropper bottle on a clean off-white seamless paper background, soft daylight from camera left, gentle elliptical shadow, the label reads 玫瑰精华水 in bold serif Chinese with a small line of English Rose Essence Water below, the liquid inside has a faint pink tint, studio product photography, sharp focus on the label, no other props, square 1:1 composition",
      "size": "2048*2048"
    }
  }'

Resposta:

{"code": 200, "data": {"taskId": "tk-hiapi-01KW8R..."}, "message": "success"}

Para consultar:

curl -s https://api.hiapi.ai/v1/tasks/tk-hiapi-01KW8R... \
  -H "Authorization: Bearer $HIAPI_TOKEN"

O campo status passa por handling → archiving → success. Em nossos testes, o tempo real total por imagem em 2K foi de 25–45 segundos. Quando o status é success, output[0].url guarda a imagem — mas aponta para temp.hiapi.ai e traz um timestamp Unix expireAt, então baixe imediatamente. Não a embuta em páginas nem fixe no banco de dados; ela retorna 404 em poucas horas.

Quando executado no endpoint ao vivo, esse prompt de estúdio gera um frasco de vidro com conta-gotas em que o rótulo renderiza com nitidez os caracteres chineses 玫瑰精华水 e, logo abaixo, o inglês Rose Essence Water em peso menor. O modelo posiciona as duas linhas de texto na área padrão do rótulo, sem nenhuma pista de layout no prompt — a formulação “the label reads X” já basta.

Um loop Python que transforma uma planilha de SKUs em fotos de estúdio enviadas

Este é o loop que executamos ao gerar as imagens desta página. Ele recebe um conjunto de tuplas (slug, prompt, size), envia concorrentemente com um limite modesto de concorrência, consulta cada tarefa até concluir, baixa o resultado e envia o webp para o seu próprio armazenamento. O padrão é deliberadamente sem graça — requests mais concurrent.futures — porque a parte interessante é o modelo.

import os, time, io, requests, concurrent.futures as cf
from PIL import Image

TOKEN = os.environ["HIAPI_TOKEN"]
BASE = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}


def submit(prompt, size):
    r = requests.post(BASE, headers=H, json={
        "model": "qwen-image-2.0",
        "input": {"prompt": prompt, "size": size},
    }, timeout=60)
    r.raise_for_status()
    return r.json()["data"]["taskId"]


def wait(task_id, deadline_s=240):
    deadline = time.time() + deadline_s
    while time.time() < deadline:
        r = requests.get(f"{BASE}/{task_id}", headers=H, timeout=30)
        d = r.json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {d.get('error')}")
        time.sleep(4)
    raise TimeoutError(f"task {task_id} not done in {deadline_s}s")


def render_one(item):
    slug, prompt, size = item
    task_id = submit(prompt, size)
    url = wait(task_id)
    png = requests.get(url, timeout=60).content
    buf = io.BytesIO()
    Image.open(io.BytesIO(png)).convert("RGB").save(buf, "WEBP", quality=88, method=6)
    return slug, buf.getvalue()


JOBS = [
    ("packshot-rose-water",  "A clear dropper bottle, label 玫瑰精华水…", "2048*2048"),
    ("packshot-tea-canister","A pale grey ceramic tea canister, label 龙井…", "2048*2048"),
    # … 200 more rows from your sheet …
]

with cf.ThreadPoolExecutor(max_workers=6) as pool:
    for slug, webp in pool.map(render_one, JOBS):
        with open(f"out/{slug}.webp", "wb") as f:
            f.write(webp)
        print(f"saved {slug}.webp ({len(webp)} bytes)")

Sobre esse código, algumas observações que não ficam evidentes por si só.

• max_workers=6 é o ponto ideal que observamos. Em 8–10, a profundidade da fila começa a se manifestar como latência extra em vez de throughput. O lado do modelo parece distribuir concorrência por conta de forma justa.
• Antes de armazenar, convertemos para webp com qualidade 88. O png 2K gerado por esse endpoint tem cerca de 3–4 MB; o webp fica em 200–400 KB e visualmente idêntico no tamanho de página de produto. A transferência é mais barata, e o modelo já codifica muita textura, que o JPEG processa mal.
• A URL temporária só pode ser baixada uma vez. Se sua etapa de upload falhar (falha no S3, oscilação de rede), você precisa renderizar novamente — não há segunda chance para obter a saída da mesma tarefa.

Seis padrões de prompt adequados ao e-commerce

Estes são os formatos de prompt que sobreviveram aos nossos testes internos de A/B contra alternativas mais verbosas. Foram escritos para falantes de inglês que usam rótulos de produto em chinês — o cenário transfronteiriço mais comum.

Padrão 1 — Foto de estúdio de item único com rótulo em chinês

A imagem padrão de produto. Especifique a cor de fundo em inglês simples, o texto do rótulo em chinês literal e a família tipográfica em inglês, e indique uma única fonte de luz.

A pale grey ceramic tea canister on a clean off-white seamless paper background. The label reads 龙井 in bold black serif Chinese with the small English subtitle Longjing Green Tea below. Soft daylight from camera right, gentle elliptical shadow, no other props. Sharp focus on the label, studio product photography, square 1:1 composition.

Os dois pontos que funcionam são “reads X in bold serif Chinese” (o qwen-image-2.0 coloca no local esperado do rótulo) e “sharp focus on the label” (faz o modelo tratar o texto como ponto focal, não como decoração).

Padrão 2 — Imagem de cena construída em torno de um prato vazio

Para fotografia de cena, descreva o cenário primeiro e coloque o produto por último, não o contrário. O modelo tende mais a derivar no cenário do que no produto, então ancore o cenário primeiro.

A wooden Japanese-style table near a wide window in late-morning daylight. The window casts a soft rectangle of light onto the table. In the center of the table is the pale grey ceramic tea canister from the previous shot, with a small wisp of steam rising from a cup beside it. Loose tea leaves are scattered to the right. Wabi-sabi aesthetic, soft shadows, shallow depth of field with focus on the canister. 16:9 widescreen composition.

Em nosso teste de renderização, a lata trazia os caracteres 龙井 e, logo abaixo, o inglês Longjing Green Tea — a mesma disciplina de rótulo da foto de estúdio — com o vapor, as folhas de chá espalhadas e a luz da janela apresentados exatamente como descrito.

Padrão 3 — Grade de variantes de cor em uma única renderização

Quando as variantes compartilham a mesma geometria de produto, você pode renderizar a grade inteira em uma única chamada em vez de três. Mais barato, e a iluminação de cada célula é consistente por construção.

Three pairs of low-top canvas sneakers shot from a slight top-down angle, arranged in one horizontal row on a clean light-grey seamless background. From left to right: dusty rose, sage green, ivory cream. Identical sneaker silhouette, identical lighting, identical shadow. Each pair faces the camera with toes pointing forward. Studio product photography, 1:1 composition, evenly spaced.

Esse padrão dispensa renderizar cada variante separadamente e tentar igualar a iluminação no pós-processamento. A restrição “identical sneaker silhouette, identical lighting, identical shadow” é a chave para manter a fileira uniforme.

Padrão 4 — Banner promocional bilíngue

Para campanhas de co-branding em Shopee, Lazada e Taobao, você geralmente precisa de título em chinês e subtítulo em inglês na mesma imagem. O qwen-image-2.0 é o único no hiapi que acerta ambos na mesma renderização.

A horizontal ecommerce promotional banner on a soft pink gradient background. The main headline reads 双十一大促 in large bold black sans-serif Chinese in the center-left. Below the Chinese headline in smaller dark grey English serif: Double 11 Sale — Up to 50% Off. To the right is a clear glass dropper bottle of pink serum with a small white label. Subtle confetti texture in the background, clean and modern, 16:9 widescreen.

O truque para tornar isso estável é colocar o chinês no início do prompt e dar a ele o qualificador “large bold”, depois dar ao inglês o qualificador “smaller”. Se você inverter a ordem, o modelo costuma deixar o inglês também em tamanho de título. O rótulo do produto dentro do banner é o ponto onde se pode relaxar — em nosso teste de renderização, o qwen escolheu para a garrafa o rótulo genérico “Vitamin C Serum”, porque não soletramos os caracteres; para campanhas de marca, ou inclua o texto literal do rótulo no prompt, ou componha o rótulo real no pós-processamento.

Padrão 5 — Card de listing para marketplace transfronteiriço

Para materiais compostos que se parecem com blocos de listing da Amazon ou Tmall — produto, título, preço, selo —, o prompt precisa soar como um briefing de layout, não de fotografia.

A square ecommerce listing card on a white background. In the top two-thirds, a clear glass dropper bottle of pink rose-essence water labeled 玫瑰精华水 / Rose Essence Water. In the bottom third, on the left, the price 99 元 in large bold black Chinese characters with a small English subtitle Rose Essence 30ml below. On the right, a small green badge that reads 新品 in white. Clean modern layout, soft drop shadow under the product, 4:3 composition.

Para listings, renderize em 4:3 (2368*1728) em vez de 1:1 — o espaço da imagem principal na maioria dos componentes de listing de marketplace é 4:3; usar quadrado gera um corte estranho.

Padrão 6 — Geração sob demanda para personalização

O último padrão muda a economia unitária. Quando cada renderização custa menos de três centavos, você pode parar de pré-renderizar banners para campanhas e renderizar por cliente no momento da solicitação — “Olá, Sra. Wang, seu combo mensal está pronto”, gravando o nome real do cliente no banner. Faça cache pelo hash do nome, defina TTL e você terá imagens de banner personalizadas com uma conta de CDN mínima.

A limitação é a latência. 25–45 segundos por renderização é lento demais para um fluxo de requisição síncrona, mas totalmente aceitável para envio de e-mail ou notificação push — gere na hora de enfileirar, incorpore na hora de enviar a mensagem.

O que o qwen-image-2.0 não faz bem

Por equilíbrio, ainda deixamos estas quatro tarefas para outros modelos no mesmo endpoint /v1/tasks.

• Fotografia à mão com motion blur. Fotos de estúdio são o ponto ideal. Se você precisa de algo que pareça não posado — estilo UGC, leve movimento, composição imperfeita —, experimente o nano-banana-pro, que entende melhor composições “casuais”.
• Variantes de produto idênticas em nível de pixel. O qwen-image-2.0 renderiza variantes semelhantes entre chamadas, mas se você precisa do mesmo frasco com conta-gotas exatamente idêntico sob cinco configurações de iluminação diferentes, precisa de um modelo condicionado por imagem de referência. Nenhum modelo puro de texto-para-imagem no hiapi garante consistência de pixel entre chamadas.
• Rostos fotorrealistas de corpo inteiro. Rostos em close ficam bem; corpo inteiro ou fotos em grupo tendem a suavizar detalhes faciais. Para e-commerce centrado em pessoas — prova de roupas, demonstrações de beleza —, combine o qwen-image-2.0 com um modelo de vídeo condicionado por referência para tomadas de ação.
• Retorno abaixo de um segundo. Se você precisa gerar imagens no loop interno de uma requisição síncrona (o usuário esperando diante da tela), 25–45 segundos é demais. O flux-schnell retorna em cerca de 5 segundos a $0,005 por imagem, mas não renderiza texto em chinês. Escolha primeiro pelo orçamento de latência.

Custo real de um lançamento de 200 SKUs

Com um caso representativo, calcule os números do fluxo de trabalho ponta a ponta.

Etapa	Quantidade	Preço unitário	Total
Imagem principal/foto de estúdio por SKU	200 × 1	$0,025	$5,00
Imagem de cena por SKU	200 × 1	$0,025	$5,00
Grade de variantes por SKU (cerca de 3 variantes em uma renderização)	200 × 1	$0,025	$5,00
Banner bilíngue por categoria (10 categorias)	10 × 1	$0,025	$0,25
Card de listing por SKU	200 × 1	$0,025	$5,00
Custo total de geração de imagens	810 renderizações	—	$20,25

Com a tabela de preços atual do hiapi, o orçamento total de imagens para um lançamento transfronteiriço de 200 SKUs fica em torno de $20. O mesmo trabalho em modelos premium (a partir de $0,04 por imagem) fica entre $30 e $140, com tempo de execução maior por imagem. É exatamente essa lacuna que o qwen-image-2.0 visa preencher: trabalho de e-commerce com percepção de chinês, em uma faixa de custo baixa o suficiente para você parar de contar renderizações.

Para onde ir a seguir

• Leia as receitas de prompt do qwen-image-2.0 para conhecer seis receitas orientadas a estilo, não específicas de e-commerce.
• Use a página de preços do hiapi como fonte da verdade para qualquer número de custo — o qwen-image-2.0 está atualmente em $0,025 por imagem, mas prevalece essa página.
• Para fluxos sensíveis à latência que não precisam de texto em chinês, troque para o flux-schnell mantendo o mesmo formato /v1/tasks — veja a comparação em Gerar imagens de produtos de e-commerce com FLUX.1 schnell.

O sentido de todo o endpoint unificado /v1/tasks é este: trocar de modelo é mudar uma string. Depois de montar o loop para o qwen-image-2.0, o mesmo script Python pode renderizar em qualquer modelo de imagem do hiapi apenas editando o campo "model" e ajustando ao schema de size desse modelo.