Gerar imagens de produtos de e-commerce com gpt-6-astra via API hiapi

O GPT-6 Astra não gera imagens — veja para que ele realmente serve no stack de e-commerce

Se você veio aqui esperando que o GPT-6 Astra desenhasse fotos de produtos, ele não faz isso — é um modelo puramente textual e de raciocínio, acessado pelo endpoint /v1/responses, que não produz imagens, áudio ou vídeo. Mas, para equipes de e-commerce, isso não é um beco sem saída. Cada imagem de produto vive dentro de uma página, e essa página ainda precisa de descrições, textos alternativos (alt text), respostas ao atendimento e três versões dos mesmos argumentos de venda para três canais de anúncio — e é exatamente para essa camada que o GPT-6 Astra foi feito. Este guia cobre a parte textual do fluxo de trabalho de imagens de produto: geração de descrições em lote, extração de dados estruturados para listagens de produtos e perguntas e respostas de clientes — com exemplos reais de requisições para a Responses API. Se você precisa da foto em si, combine-o com um modelo de imagem como o GPT Image 2 e deixe o GPT-6 Astra cuidar de todo o texto que envolve a foto.

Por que usar a Responses API e não a Chat Completions

O GPT-6 Astra é exposto apenas por POST /v1/responses — a mesma família de endpoints que a OpenAI usa para seus modelos de raciocínio mais recentes — e não pelo formato mais antigo do Chat Completions. Se você for integrá-lo a um pipeline de produtos, três diferenças importam:

• Use input em vez de messages. Você passa um array de itens de entrada, não uma lista de messages. Adapte seu cliente de Chat Completions em vez de reaproveitar, sem alterações, o código que monta a requisição.
• Na prática, o padrão é stream=true, com store=false. O modelo emite eventos response.output_text.delta à medida que o texto chega e emite response.output_item.done quando um item estruturado é concluído. Com store=false, nada é retido no servidor entre chamadas — se você estiver conduzindo uma conversa de atendimento com múltiplos turnos, precisa reenviar você mesmo os turnos anteriores de usuário/assistente no próximo array input.
• Use reasoning.effort em vez de temperature. Essa integração não tem ajustes de temperature, top_p ou max_output_tokens. Você controla a qualidade/latência da saída por reasoning.effort, com valores low, medium, high, xhigh ou max (não existe none — o raciocínio não pode ser desligado). Para tarefas curtas e determinísticas como geração de descrições, low ou medium costuma bastar; reserve high e acima para cenários que exigem discernimento, como redigir respostas de atendimento que envolvam questões sensíveis de política.

A URL base é https://api.hiapi.ai/v1, e a chave é a mesma dos seus outros modelos hiapi.

Caso de uso 1: geração em lote de descrições de produtos com saída estruturada

O encaixe mais direto com o e-commerce é transformar em larga escala tabelas de especificações em textos de anúncio alinhados ao tom da marca. Em vez de depois analisar o texto livre devolvido pelo modelo, use text.format.type=json_schema para que cada resposta volte no formato que seu CMS consegue ingerir diretamente — título, descrição curta, descrição longa e lista de tópicos, tudo em uma única chamada.

import json
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/responses",
    headers={
        "Authorization": f"Bearer {HIAPI_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-6-astra",
        "store": False,
        "reasoning": {"effort": "low"},
        "input": [
            {
                "role": "system",
                "content": "You write concise, factual e-commerce listing copy. "
                            "Never invent specs that aren't in the input.",
            },
            {
                "role": "user",
                "content": "Product: ceramic pour-over coffee dripper, 400ml, "
                            "matte white, dishwasher safe, fits standard filters. "
                            "Write listing copy for this product.",
            },
        ],
        "text": {
            "format": {
                "type": "json_schema",
                "name": "listing_copy",
                "schema": {
                    "type": "object",
                    "properties": {
                        "title": {"type": "string"},
                        "short_description": {"type": "string"},
                        "long_description": {"type": "string"},
                        "bullet_points": {
                            "type": "array",
                            "items": {"type": "string"},
                        },
                    },
                    "required": [
                        "title",
                        "short_description",
                        "long_description",
                        "bullet_points",
                    ],
                    "additionalProperties": False,
                },
            }
        },
    },
    stream=False,
)
data = resp.json()

Execute esse código por SKU no seu banco de dados de produtos e você obtém textos consistentes e validados pelo schema, em vez de prosa copiada e colada de uma janela de chat. Faça o prompt de sistema proibir rigidamente a invenção de especificações — se você deixar solto, o modelo escreverá com prazer e riqueza de detalhes sobre recursos que você nem forneceu.

Caso de uso 2: perguntas e respostas de suporte ao cliente com base em documentos próprios

Para um assistente de atendimento, o padrão-chave é o loop de reenvio com store=false. A cada turno, você reenvia no input a conversa atual mais qualquer resultado de ferramenta; o que você não envia, o modelo simplesmente não lembra. Essa é uma troca intencional — o custo é que reenviar tokens de entrada sai um pouco mais caro, mas significa que o estado da conversa pertence à sua aplicação, e não ao fornecedor (útil se você precisar anonimizar, ramificar ou restaurar conversas a partir do seu próprio banco de dados).

history = [
    {"role": "system", "content": "Answer only from the provided product FAQ context. "
                                    "If the answer isn't in context, say so and offer to escalate."},
]

def ask(user_message: str, faq_context: str) -> str:
    history.append({"role": "user", "content": f"Context:\n{faq_context}\n\nQuestion: {user_message}"})
    resp = requests.post(
        "https://api.hiapi.ai/v1/responses",
        headers={"Authorization": f"Bearer {HIAPI_KEY}", "Content-Type": "application/json"},
        json={
            "model": "gpt-6-astra",
            "store": False,
            "reasoning": {"effort": "medium"},
            "input": history,
        },
    )
    answer = resp.json()["output"][-1]["content"][0]["text"]
    history.append({"role": "assistant", "content": answer})
    return answer

Para qualquer ação que precise consultar o status de um pedido ou acionar uma devolução, declare-a como função em tools — o modelo devolve um function_call, seu backend o executa e, em seguida, antes que o modelo continue, você devolve o resultado via function_call_output com o mesmo call_id. Isso garante que o modelo nunca toque diretamente no seu banco de dados de pedidos.

Caso de uso 3: variações de copy de marketing para diferentes canais

O mesmo conjunto de fatos sobre um produto exige formulações diferentes na página do produto, no título de um e-mail e em um título de anúncio de 30 caracteres. Como o GPT-6 Astra emite eventos response.output_text.delta em streaming, você pode gerar várias variações de canal em uma única chamada e renderizá-las à medida que chegam, sem esperar pela resposta completa — útil se isso for alimentar uma pré-visualização em tempo real de uma ferramenta interna. Aqui também mantenha reasoning.effort em low; combinar o tom de textos curtos não exige raciocínio mais forte e mantém a latência baixa enquanto os profissionais de marketing iteram em tempo real.

Como os custos são calculados

O GPT-6 Astra é cobrado por token e tem um degrau rígido de faixa, e não um acréscimo marginal — vale a pena entender isso antes de processar em lote um catálogo grande de produtos em uma única requisição:

Faixa	Entrada	Saída	Entrada em cache	Gravação em cache
Padrão (≤272.000 tokens de entrada/requisição)	$2,50 / 1 milhão de tokens	$12,50 / 1 milhão de tokens	$0,25 / 1 milhão de tokens	$3,125 / 1 milhão de tokens
Contexto longo (>272.000 tokens de entrada/requisição)	$5,00 / 1 milhão de tokens	$18,75 / 1 milhão de tokens	$0,50 / 1 milhão de tokens	$6,25 / 1 milhão de tokens

O limite é verificado sobre a entrada total da requisição — incluindo leituras e gravações de cache — e, assim que é ultrapassado, a requisição inteira passa a ser cobrada pela tarifa de contexto longo, e não apenas os tokens que excedem 272.000. Para os casos de uso acima (geração de descrição de um item, um turno de atendimento, uma variação de copy), você está muito longe dessa linha; ela só pesa quando você enfia um catálogo inteiro ou um documento longo em uma única chamada. Antes de se comprometer com tarefas em lote, consulte hiapi.ai/pricing para obter as tarifas atuais, pois elas são baseadas em uso e podem mudar.

Como isso se encaixa no restante do stack

Nada disso substitui um modelo de imagem de verdade — o GPT-6 Astra não tem acesso a /v1/tasks nem consegue produzir saída visual. Se o seu fluxo de trabalho precisa de fotografia de produto ou imagens de lifestyle para acompanhar esses textos, isso exige uma chamada separada a um modelo de imagem como o GPT Image 2, e os formatos de requisição e endpoints dos dois não são interoperáveis. Para detalhes completos de configuração, incluindo o ID do modelo e o formato exato da requisição, consulte o guia da API do GPT-6 Astra e a página do modelo.

Perguntas frequentes

O GPT-6 Astra consegue gerar imagens de produtos? Não. É um modelo puramente textual acessado via /v1/responses, que não produz imagens, áudio ou vídeo. Combine-o com um modelo de imagem para a parte visual das listagens de produtos.

Qual é a diferença entre input e o array messages que eu usava no Chat Completions? input é o campo de requisição que a Responses API usa para turnos de conversa e conteúdo — não é um substituto direto de messages, portanto o código do cliente de Chat Completions precisa ser adaptado, e não apenas ter o nome do campo trocado.

Para tarefas simples como geração de descrições, eu preciso desligar o raciocínio? Você não pode desligá-lo — não existe reasoning.effort=none. Para tarefas de geração curtas e de baixo risco, use low; é o mais rápido e o mais barato das cinco faixas.

store=false significa que vou perder o histórico da conversa? Não, significa que a plataforma não o armazena por você. Sua aplicação reenvia no próximo array input os turnos de que precisa, o que lhe dá controle sobre qual contexto incluir (e também permite anonimizar ou ramificar conversas), ao custo de pagar por esses tokens novamente como entrada.

Repetir o mesmo prompt de sistema em muitas chamadas de descrição de produtos garante desconto de cache? Não é garantido. Acertos de cache dependem da política e do momento do servidor, e não apenas da repetição literal — verifique cached_tokens no objeto usage da resposta, em vez de presumir que o desconto se aplica.

O que acontece se eu colocar um catálogo inteiro em uma única requisição? Se o total de tokens de entrada (incluindo qualquer conteúdo em cache) ultrapassar 272.000, a requisição inteira — entrada, saída e uso de cache — é cobrada pela tarifa de contexto longo, e não apenas a parte que excede o limite. Para a maioria das chamadas de item único ou de conversa única isso não se aplica, mas vale conferir a contagem de tokens antes de enfiar um catálogo grande em uma única chamada.