Gerar imagens de produtos de e-commerce com qwen-image-2.1-pro: uso da API e receitas de prompts

Por que vale a pena escolher o qwen-image-2.1-pro para imagens de produtos de e-commerce

O trabalho com imagens de e-commerce raramente envolve uma única tarefa. Pode ser uma sessão de catálogo para um novo SKU, um recorte para a página de produto de um marketplace, uma imagem de estilo de vida para uma landing page e um banner com um selo promocional — tudo geralmente para entregar na mesma semana. O que torna o qwen-image-2.1-pro digno de avaliação é que, quando seu fluxo precisa produzir todos esses conteúdos a partir dos mesmos dados de produto, ele consegue realizar geração, edição de ativos existentes, saída em PNG transparente e renderização de texto na imagem em um único modelo, em vez de depender de uma cadeia de ferramentas especializadas.

Três tipos de tarefa cobrem a maior parte do volume de trabalho:

• Recorte transparente — o produto é isolado de forma limpa sobre um fundo transparente e pode ser colocado diretamente em qualquer espaço do CMS.
• Composição de cena — o produto é colocado em um ambiente de estilo de vida ou estúdio verossímil, gerado a partir de uma descrição textual mais uma imagem de referência.
• Layout com texto — rótulos, selos e banners em que o texto precisa estar legível e posicionado corretamente.

Onde ele não substitui o estúdio: imagens principais com requisitos rígidos de iluminação de marca e qualquer ativo cuja geometria do produto seja regulamentada (por exemplo, embalagens reguladas). Trate a geração como um meio de ampliar a cobertura e acelerar a iteração, e mantenha as etapas de aprovação humana — é exatamente para isso que serve o processo de revisão descrito mais adiante neste guia.

A razão prática para decidir isso cedo é a arquitetura de prompts. Se você souber desde o início que o mesmo modelo vai atender recortes, cenas e layouts com texto, poderá criar um pequeno conjunto de templates de prompt versionados, em vez de escrever prompts improvisados a cada requisição. Essa decisão não custa nada no início e evita retrabalho de reescrita mais tarde.

Requisições executáveis: curl e Python

Antes de projetar prompts, obtenha uma imagem com sucesso. Na HiAPI, o formato de requisição é consistente entre os modelos: uma API key, um nome de modelo e os parâmetros de entrada no corpo da requisição. O parâmetro mínimo necessário para o qwen-image-2.1-pro é o prompt e, se a tarefa for uma edição em vez de uma geração nova, também a imagem de entrada que você deseja editar.

curl

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "Foto de produto em estúdio de uma caneca de café de cerâmica preta fosca, ângulo de três quartos, luz principal suave e difusa vinda da esquerda, leve reflexo sobre fundo contínuo cinza-claro, sem texto",
    "size": "1024x1024"
  }'

Python requests

import os
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "qwen-image-2.1-pro",
        "prompt": "Foto de produto em estúdio de uma caneca de café de cerâmica preta fosca, "
                  "ângulo de três quartos, luz principal suave e difusa vinda da esquerda, "
                  "leve reflexo sobre fundo contínuo cinza-claro, sem texto",
        "size": "1024x1024",
    },
    timeout=120,
)
resp.raise_for_status()
print(resp.json())

Vale a pena cultivar dois hábitos nesta fase. Primeiro, leia a API key de uma variável de ambiente e nunca a codifique diretamente — você logo estará executando isso a partir de tarefas em lote. Segundo, mantenha o corpo completo da resposta nos logs, incluindo quaisquer campos de uso retornados pelo endpoint; é isso que você usará depois para medir o "custo por ativo aprovado", em vez de adivinhar.

Execute uma requisição com um prompt genérico como o acima primeiro. Confirme que você recebeu a imagem e que a estrutura da resposta corresponde ao que o código downstream espera. Só então passe às receitas — o design de prompts é um trabalho lento, e você não vai querer descobrir problemas de pipeline no meio do caminho.

Receitas de prompts para PNG transparente e cenas de produto

Prompts improvisados tendem a variar. Equipes de catálogo obtêm resultados consistentes mantendo um pequeno conjunto de templates com espaços variáveis explícitos, versionando-os no repositório junto com o código que chama a API e substituindo apenas os espaços por SKU a cada vez.

Receita 1: recorte transparente

Recorte do produto {product_name}, {distinguishing_detail}, totalmente isolado sobre fundo transparente.
Vista {view_angle}, produto centralizado e completamente enquadrado, com uma pequena margem ao redor.
Iluminação de estúdio suave e uniforme, sem sombras duras projetadas no fundo, apenas uma leve sombra de contato logo abaixo do produto.
Fotorrealista, bordas nítidas, sem texto, sem adereços, sem elementos de fundo.

Espaços: {product_name} ("uma caneca de café de cerâmica preta fosca"), {distinguishing_detail} ("espessura visível da borda e uma alça pequena"), {view_angle} ("três quartos", "frontal", "vista superior"). Mantenha as cláusulas de transparência e "sem sombras projetadas no fundo" exatamente como estão; essas duas linhas fazem a maior parte do trabalho em tarefas de recorte.

Receita 2: cena de estilo de vida

Foto de produto de estilo de vida de {product_name} em {scene_description}.
O produto é o protagonista: foco nítido, proporções corretas, {brand_color_note}.
{lighting_note}. Profundidade de campo rasa, fundo suavemente desfocado.
Estilo natural e editorial. Sem texto, sem logotipos, sem marcas visíveis no fundo.

Espaços: {scene_description} ("bancada de cozinha clara e minimalista, com um guardanapo de linho e uma janela de manhã"), {brand_color_note} ("cores inalteradas, sem desvio de tom aplicado"), {lighting_note} ("luz da manhã quente e direcionada vinda da direita").

Receita 3: imagem principal de estúdio

Foto de produto em estúdio de {product_name}, vista {view_angle}.
{background_description}. Luz principal vinda de {key_light_direction}, preenchimento suave, reflexos controlados.
Fotorrealista, com detalhes ricos de material e textura da superfície. Sem texto.

Duas regras mantêm a biblioteca de templates saudável. Nunca edite o template diretamente no script — modifique o arquivo do template, aumente o número da versão e gere novamente. E registre qual versão da receita produziu cada ativo aprovado, para que, quando um template mudar, você possa julgar se as aprovações antigas ainda são válidas.

Editar imagens de produto existentes

As requisições de edição são onde ocorre a maioria dos problemas de qualidade, porque prompts vagos fazem o modelo regenerar o produto em vez de modificar o ambiente ao redor dele. Divida cada prompt de edição explicitamente em três partes:

1. O que mudar — a cena, o fundo, a iluminação ou um adereço adicionado.
2. O que preservar — a forma, as proporções, o padrão do rótulo, o material e a cor do produto.
3. O que evitar — texto novo, logotipos novos, geometria distorcida, partes duplicadas.

Um template utilizável:

Edite esta foto de produto.
Alterar: substitua o fundo por {new_background}; ajuste a iluminação para {new_lighting}.
Preservar: a forma exata, as proporções, o material da superfície e qualquer padrão do rótulo do produto, completamente inalterados.
Não: adicionar texto, adicionar logotipos, alterar a cor do produto ou modificar sua geometria.
Resultado fotorrealista, parecendo uma foto de uma sessão contínua.

Exemplo de preenchimento: {new_background} = "fundo contínuo cinza-quente limpo", {new_lighting} = "luz difusa suave vinda de cima, com um gradiente suave atrás do produto".

As cláusulas de preservação não são garantia. Edições longas — substituir o fundo, ajustar a iluminação e adicionar um adereço em um único prompt — dão ao modelo mais espaço para se desviar do próprio produto. Divida: faça primeiro a substituição de fundo, revise-a e depois aplique alterações secundárias como edições posteriores sobre o resultado intermediário aprovado. Cada etapa é uma comparação que o revisor consegue realmente julgar.

Além disso, mantenha uma imagem de referência padrão para cada SKU. Quando o revisor estiver em dúvida se o produto mudou, a referência é a fonte da verdade, não a geração anterior.

Renderização de texto e controle de layout

Texto na imagem é o recurso que mais decepciona quando o prompt é casual. O texto que precisa aparecer no ativo final deve estar entre aspas, posicionado e restringido.

Banner de e-commerce para {product_name}.
Layout: produto no terço direito, bloco de texto no terço esquerdo, com margem generosa.
Texto: renderize exatamente "{headline}" como título principal em fonte sans-serif em negrito, e abaixo dele renderize exatamente "{subline}" em peso mais leve.
Estilo: {color_scheme}, limpo e moderno, alto contraste para legibilidade.
Nenhum texto em qualquer outro lugar da imagem. Todas as palavras escritas exatamente como estão.

Por que cada linha importa:

• Texto entre aspas com uma instrução explícita de "exatamente" reduz reescritas e palavras inventadas.
• Posição e proporção ("terço direito", "terço esquerdo") impedem que o modelo enterre o produto sob o título.
• "Nenhum texto em qualquer outro lugar da imagem" é a cláusula que suprime um modo de falha comum: texto de preenchimento plausível aparecendo nos cantos.
• Um título curto e um subtítulo curto são muito mais confiáveis do que um parágrafo de texto. Se o seu layout precisar de um bloco de copy, gere a imagem sem esse copy primeiro e depois componha o texto no CMS ou na ferramenta de design.

Para selos e etiquetas (marcas "New", indicadores de tamanho), trate-os como seus próprios mini-prompts, em vez de anexá-los à imagem principal — um pequeno prompt de selo contendo uma única palavra entre aspas é muito mais fácil de verificar na revisão do que um banner inteiro. Sempre verifique a ortografia em resolução total antes da aprovação; erros de texto são baratos de detectar e caros quando chegam ao ar.

Revisar a saída: ciclo de comparação e aprovação

Ativos gerados não devem ser publicados na loja sem revisão humana. O ciclo mais barato e confiável é a comparação antes/depois por ativo: coloque a foto de entrada (ou a especificação, no caso de uma geração nova) ao lado da saída gerada e registre a versão da receita de prompt e os valores das variáveis.

Um ciclo prático para equipes pequenas:

1. Gere um pequeno lote — alguns variantes por SKU, não o catálogo inteiro.
2. Monte uma tabela de comparação lado a lado: fonte à esquerda, candidato à direita, prompt registrado abaixo.
3. Revise com uma lista de verificação curta e fixa: forma do produto inalterada, padrão do rótulo intacto, fundo limpo, texto escrito corretamente, margem suficiente.
4. Marque cada candidato como aprovado ou rejeitado e registre a versão da receita que produziu o resultado aprovado.
5. Só então expanda para o lote inteiro, reutilizando a receita aprovada. Se a receita mudar após a aprovação, trate as aprovações existentes como provisórias até que sejam verificadas novamente.

Mantenha a lista de verificação curta e idêntica todas as vezes. Uma lista consistente de quatro itens encontra mais problemas do que um formulário longo aplicado de forma irregular. Guarde também os candidatos rejeitados — eles são a evidência de por que uma versão da receita foi descartada e evitam que a próxima pessoa redescubra a mesma falha.

Esse ciclo também é o seu mecanismo de controle de custos. Como a aprovação está vinculada à receita, você pode calcular quantas gerações cada ativo aprovado exigiu e iterar sobre o template que consumiu mais tentativas.

Considerações de custo, latência e processamento em lote

Planeje com base em suas próprias medições, não em suposições. Para os modelos de imagem na HiAPI, a cobrança é por imagem de saída, então a variável que domina o gasto é "tentativas por ativo aprovado" — que depende inteiramente da qualidade do prompt e do rigor da revisão. O preço atual por imagem está na página de preços do site; não fixe números no código ou em documentos de orçamento.

Um método de trabalho razoável:

• Meça a linha de base. Execute dez SKUs com a receita aprovada, conte o total de gerações e o total de aprovações e derive as tentativas por ativo aprovado. Essa proporção diz mais do que qualquer benchmark.
• Itere individualmente, processe em lote após a aprovação. A iteração de prompts deve ser feita uma imagem por vez. Depois que a receita for aprovada, processe em lote com concorrência moderada e uma estratégia de repetição que registre falhas em vez de cobrar novamente em silêncio.
• Trate a latência como parâmetro de agendamento. A geração de imagens é medida em segundos, não em milissegundos. Inicie jobs de forma assíncrona, grave os resultados em uma fila e deixe os revisores processá-los a partir da fila, em vez de bloquear a cada chamada.
• Orçe pela proporção, não pelo preço unitário. Com as tentativas por ativo aprovado em mãos, a estimativa do catálogo é uma aritmética simples baseada em suas próprias medições.

Um último hábito de higiene: versione suas receitas e registre a versão da receita em cada requisição. Custa apenas um campo, mas transforma "por que este ativo parecia diferente no mês passado?" de uma investigação em uma consulta.

Construa o fluxo mínimo que permite executar recortes, cenas e layouts com texto via API, mantenha a biblioteca de prompts versionada e deixe que o ciclo de revisão — e não a esperança — decida o que vai ao ar.