Gerar imagens de produtos de e-commerce com gpt-image-2/text-to-image via API HiAPI

Por que usar text-to-image para visuais de produtos de e-commerce

As imagens de produto são um dos maiores gargalos do pipeline de catálogo. Um único SKU normalmente precisa de uma imagem limpa para listagem, uma imagem de contexto de uso, um recorte para banner e várias variantes para redes sociais — e, quando a embalagem muda, cada uma delas precisa ser refotografada ou retrabalhada. Modelos de text-to-image oferecem às equipes de desenvolvedores uma forma programável de preencher esses espaços usando os dados que já existem.

Vale a pena distinguir os casos de uso realistas dos irrealistas:

• Variantes complementares. Gerar fundos de contexto de uso, sazonais ou situacionais ao redor de um produto para o qual você já tem imagem de referência, em vez de agendar uma sessão de estúdio para cada posição de veiculação.
• Andaimes de catálogo. Gerar imagens de rascunho no início do lançamento para que as equipes de operações de produto e de marketing possam revisar o layout e os recortes antes que o material final esteja pronto.
• Localização e personalização. Substituir cenário, estação ou estilo por meio de variáveis de prompt, mantendo a descrição do produto fixa.
• Placeholders e materiais de teste. Gerar imagens de preenchimento determinísticas para ambientes de pré-lançamento, para que os templates de loja possam ser testados com conteúdo que parece real.

O que o text-to-image não substitui é o registro autoritativo do produto. Os visuais gerados nunca devem inventar funcionalidades, materiais, cores ou acessórios que o produto real não possui. Trate o modelo como uma camada de renderização sobre os dados do produto, não como a fonte da verdade sobre o produto. Se a imagem gerada exibe um acabamento ou componente inexistente, isso é um defeito, não uma licença criativa.

O restante deste guia se baseia nesse enquadramento: seus dados de produto e a fotografia de referência existente continuam sendo a fonte da verdade, e o modelo gera, ao redor deles, a camada de contexto e a camada de composição. Com essa fronteira definida, as questões de integração da API se tornam diretas — um template de requisição, um conjunto de variáveis de prompt por SKU e uma saída que você possa validar.

Como o gpt-image-2/text-to-image se encaixa no fluxo de trabalho da HiAPI

Na HiAPI, o gpt-image-2/text-to-image é um endpoint de modelo único, posicionado atrás da mesma interface unificada de API que você usa para outras tarefas de geração. Você não precisa de uma integração separada por fornecedor, de um armazenamento separado de credenciais nem de SDKs diferentes por modalidade — seu aplicativo envia requisições à HiAPI e recebe as imagens geradas na resposta.

O modelo mental mínimo tem três partes:

Requisição

Uma requisição de text-to-image carrega seu prompt e os parâmetros que controlam a imagem, sendo o mais importante a proporção. Tudo o que o modelo entende sobre a saída desejada vem do prompt, então o prompt é a interface de verdade — parametrizá-lo de forma limpa é o trabalho de engenharia.

Identificador do modelo

Você especifica o modelo pelo nome na requisição: gpt-image-2/text-to-image. Manter o identificador do modelo como valor de configuração, em vez de literal fixo no código, permite trocá-lo ou fazer testes A/B com facilidade no futuro, sem tocar nos pontos de chamada.

Resposta

A chamada retorna os dados da imagem gerada. Como você a trata — gravando em object storage, transmitindo para um worker ou retornando uma URL temporária — depende do seu pipeline, mas a forma da integração permanece a mesma: montar a requisição, enviá-la, persistir o resultado e registrar os metadados.

Antes de escrever código, defina três coisas: onde ficam os prompts (use templates com variáveis, não concatenação de strings espalhada pelo código), onde ficam as saídas e como é o seu passo de validação. Equipes que pulam o terceiro item acabam revisando manualmente cada imagem gerada, o que desde o início anula o propósito da geração automatizada.

Projetar prompts para saídas fiéis ao produto

Imagens de catálogo consistentes vêm de uma estrutura de prompt consistente. Em vez de escrever uma descrição totalmente nova para cada SKU, defina um template com slots fixos e substitua apenas os valores que realmente variam. Uma estrutura que funciona bem no trabalho com produtos tem cinco partes, nesta ordem:

1. Sujeito

Diga o que é o produto de forma simples e específica: categoria, formato e qualquer material ou acabamento que o produto realmente tenha. Extraia esses valores do registro do produto, e não os reescreva à mão — é isso que mantém os SKUs comparáveis.

2. Cenário

Descreva o ambiente em que o produto está: fundo de estúdio em cor sólida, bancada de cozinha, superfície externa. O cenário deve ser a principal fonte de variação em grande parte do catálogo, porque é barato de alterar e não traz risco de distorcer o produto.

3. Iluminação

Especifique a luz: luz do dia difusa e suave, luz principal de estúdio direcional com luz de preenchimento, luz interna quente. A iluminação tem impacto enorme na qualidade percebida e é um dos itens mais fáceis de padronizar em todo o catálogo para obter consistência visual.

4. Composição

Indique a posição do produto no quadro, o tamanho relativo e o ângulo de captura. Frontal e centralizado, perspectiva de três quartos, recorte próximo da superfície superior. É aqui que você codifica os requisitos de layout da loja apresentados na próxima seção.

5. Estilo

Encerre com a intenção de renderização: fotografia comercial limpa de produto, estilo editorial minimalista, tons neutros suaves. Os descritores de estilo devem ser curtos e consistentes em um lote de imagens.

Algumas regras práticas evitam a maioria das saídas ruins:

• Não adicione detalhes que o produto não tem. Não invente logotipos, botões extras ou acessórios. Se um detalhe não está nos seus dados de produto, ele não deve aparecer no prompt.
• Mantenha as negações explícitas, mas curtas. "Sem sobreposição de texto, sem objetos extras, sem reflexo de pessoas" é mais confiável do que uma longa lista de proibições.
• Fixe o template, varie as variáveis. Se a redação do prompt for diferente para cada SKU, suas saídas variarão por motivos que você não conseguirá depurar.
• Versione o template. Armazene a versão do template junto com cada material gerado, para poder rastrear a saída até o prompt que a produziu.

Um template mínimo tem o seguinte aspecto, com os slots entre colchetes preenchidos a partir dos dados do produto:

[descrição do produto], [cenário], [iluminação],
[composição e ângulo], [descritor de estilo],
sem sobreposição de texto, sem objetos extras

Escolher a proporção para o layout da loja

Escolha a proporção com base na posição de veiculação, e não o contrário. Se você gera uma imagem quadrada e depois a recorta em um banner largo, perde o controle da composição — o modelo compôs para o quadrado e o recorte decide o resto. Gerar na proporção de destino é o que faz as instruções de composição do seu prompt realmente funcionarem.

Primeiro mapeie os slots de imagem da loja e depois atribua as proporções:

Quadrada (1:1)

A escolha padrão para blocos de grade de produtos, listagens de marketplaces e qualquer layout que use grade uniforme de cards. Composições centralizadas e frontais funcionam melhor aqui, porque o quadro é simétrico e os recortes em cenários de carregamento tardio costumam ser pequenos.

Vertical (4:5, 2:3)

Comum em imagens principais de detalhe do produto, feeds com prioridade para mobile e layouts de catálogo impresso. O quadro vertical dá espaço de respiro a produtos alongados e deixa espaço acima ou abaixo do sujeito para que o frontend sobreponha elementos de operações de produto.

Horizontal (16:9, 3:2)

Banners de categoria, posições de primeira dobra, cabeçalhos de e-mail e capas de coleção. Quadros horizontais servem melhor a cenas do que a objetos isolados — o produto em contexto, com espaço livre de um lado, é mais legível do que um objeto centralizado num quadro amplo e vazio.

Alto e estreito (9:16, formato de story 4:5)

Formatos de story e posições promocionais verticais. A composição aqui deve ser explicitamente vertical: sujeito posicionado mais abaixo ou centralizado, bastante espaço no topo e sem elementos horizontais amplos.

Duas observações de fluxo de trabalho. Primeiro, gere por posição de veiculação, em vez de redimensionar uma imagem-mãe para cada posição — as cláusulas de composição do prompt devem mudar com a proporção, o que significa requisições separadas. Segundo, mantenha para cada SKU uma imagem-mãe padrão quadrada ou vertical, para arquivo e para posições que você ainda não mapeou, e trate as proporções derivadas como saídas regeneráveis, não como materiais a serem armazenados.

Depois que seu mapa de posições de veiculação para proporções existe, ele deve ficar na configuração, junto com os templates de prompt. As operações de produto mudam o layout, você altera um valor e a próxima geração para aquela posição usa o novo quadro — sem alteração de código.

Fazer uma requisição funcional de text-to-image via HiAPI

Com o template e as proporções definidos, a requisição em si é mecânica. O fluxo de trabalho abaixo é algo que você constrói uma vez e reutiliza em cada SKU.

Passo 1 — Montar o prompt

Carregue o template, preencha o slot do sujeito a partir do registro do produto e preencha os slots de cenário, iluminação, composição e estilo a partir da configuração da posição de veiculação de destino. Registre a versão do template e os valores das variáveis junto com a requisição, para que a saída seja reproduzível.

Passo 2 — Definir o quadro

Passe a proporção correspondente à posição de veiculação de destino. A redação de composição no prompt e a proporção devem ser coerentes — a cláusula "produto centralizado, bastante espaço no topo" produz resultados diferentes em um quadro 16:9 e em um 4:5.

Passo 3 — Enviar a requisição

Envie a requisição de text-to-image ao modelo gpt-image-2/text-to-image pela API HiAPI, autenticando com suas credenciais HiAPI. Trate o identificador do modelo, a proporção e o template de prompt como entradas de configuração, para que o mesmo caminho de código atenda cada SKU e cada posição de veiculação.

Enviar requisição POST ao endpoint de geração de imagens da HiAPI
  model:  gpt-image-2/text-to-image
  prompt: <template montado>
  aspect_ratio: <proporção correspondente à posição de veiculação de destino>

Antes de conectar isso ao seu serviço, consulte a documentação da HiAPI para conhecer o caminho exato do endpoint, o formato do cabeçalho de autenticação e os nomes dos parâmetros — esses detalhes são o contrato, e copiá-los de posts de blog é exatamente o começo da deriva de integração.

Passo 4 — Tratar a resposta

Receba a imagem gerada e persista-a imediatamente. Grave o binário no seu object storage, com a chave codificando SKU, posição de veiculação e versão do template, e registre uma linha na tabela de materiais com os metadados da requisição: texto do prompt, proporção, modelo e timestamp. Fazer isso dentro do handler da requisição, e não em uma tarefa paralela, mantém o material junto à sua origem.

Passo 5 — Validar a saída

Antes que a imagem gerada chegue à loja, passe-a por um passo de revisão. Verifique no mínimo: a imagem corresponde ao registro do produto, o quadro está na proporção solicitada e não há detalhes inventados ou artefatos de texto. Automatize o que for possível (verificação de proporção, checagens básicas de sanidade da imagem) e, durante o período inicial, coloque o restante em uma fila de revisão humana.

Passo 6 — Retornar a referência

Entregue à loja uma chave de armazenamento ou URL estável, e não o payload bruto da resposta. Seu frontend não deve saber nem se importar que a imagem veio de uma requisição de geração; ele deve ver o mesmo contrato de material que vê para qualquer outra imagem de catálogo.

Escalar a geração em todo o catálogo de produtos

Uma requisição funcional é uma demonstração; um pipeline de catálogo é uma fila. A transição entre os dois está principalmente em isolamento e observabilidade.

Transformar cada SKU em um job

Empacote o fluxo de requisição em um job com entradas explícitas — SKU, posição de veiculação, versão do template — e saídas explícitas — chave do material armazenado, status, metadados da requisição. A falha do job de um SKU não deve bloquear o lote inteiro. As novas tentativas devem ser seguras: como cada execução é parametrizada, repetir um job com falha produz um resultado comparável, e não um material duplicado e misterioso.

Separar a autoria de prompt da execução

Os templates de prompt e o mapa de posições de veiculação para proporções devem ser dados, versionados e revisados, e não código enterrado em um worker. Isso permite que as equipes de operações de produto e de marketing iterem redação e composição sem fazer deploy, e permite comparar versões de template no mesmo conjunto de SKUs quando a qualidade da saída mudar.

Disciplina de orçamento e taxa

O custo de geração cresce com o tráfego, então acompanhe quantas requisições são emitidas por lote e escolha as posições de veiculação de forma consciente — não gere por padrão todas as proporções para todos os SKUs. A cobrança segue o uso do endpoint de geração, e as tarifas atuais ficam no painel de preços da sua conta HiAPI, não neste guia. Vale construir desde cedo um modo de simulação que apenas monta e registra o prompt sem enviá-lo; ele detecta erros de template antes que gerem custo.

Auditar o que você gerou

Anexe os metadados da requisição permanentemente a cada material. Quando alguém de operações de produto perguntar por que um produto parece errado em uma posição de veiculação, você quer poder recuperar o prompt exato, a proporção e a versão do template em uma única consulta, e não reconstruí-los a partir de logs.

Definir critérios de aceitação antecipadamente

Antes da geração em massa, defina o que significa "bom o bastante para a loja": fidelidade do produto em relação ao registro, quadro correto, ausência de texto falso, iluminação consistente dentro de um lote. Codifique as verificações que podem ser automatizadas e trate a fila de revisão humana como uma etapa que diminui aos poucos, e não como um fardo permanente.

Depois de acertar os templates, o mapa de proporções e o encapsulamento dos jobs, escalar para o catálogo inteiro passa a ser trabalho de throughput, não de redesenho. Comece com um único SKU e uma única posição de veiculação, confirme o fluxo de requisição de ponta a ponta e então expanda o job por todo o catálogo.