Processar imagens de produtos de e-commerce com o DeepSeek V4.1 Flash via API hiapi

O DeepSeek V4.1 Flash não gera imagens de produto — veja abaixo o que ele realmente faz bem na stack de e-commerce

Se você chegou aqui pela palavra "imagens de produto", o DeepSeek V4.1 Flash não consegue gerá-las — é um modelo puramente textual, sem nenhuma saída de imagem, áudio ou vídeo. Mas um catálogo de e-commerce depende muito mais de texto do que de imagem: cada Listing precisa de descrição, cada imagem precisa de texto alternativo, cada dúvida do cliente precisa de resposta, cada canal de anúncio precisa de versões diferentes do mesmo argumento de venda. É exatamente nesse nível que o modelo se destaca, e ele é singularmente barato e flexível nessa tarefa — suporta tanto /v1/chat/completions quanto /v1/responses, então você não precisa reconstruir a integração em torno de um único formato de requisição. Este guia cobre a parte textual do fluxo de trabalho de imagens de produto: geração em lote de descrições com saída estruturada, perguntas e respostas de suporte ao cliente e variações de copy multicanal — com exemplos reais de requisição baseados na API hiapi. Se você precisa das imagens em si, combine-o com um modelo de imagem como o GPT Image 2 e deixe o DeepSeek V4.1 Flash cuidar de todo o texto em torno da imagem.

Por que a interface dupla de API importa

A maioria dos modelos de nível de raciocínio no hiapi escolhe um único caminho — Chat Completions ou Responses — e segue com ele. O DeepSeek V4.1 Flash suporta nativamente POST /v1/chat/completions e POST /v1/responses, o que significa que você pode conectá-lo à sua integração existente sem construir um novo cliente específico para este modelo. Os pontos a seguir valem em ambos os endpoints:

• reasoning_effort tem cinco níveis reais. O texto da página de preços menciona apenas none, high e max, mas o modelo também aceita low e medium em requisições reais — todos os cinco níveis são válidos. Para tarefas curtas e determinísticas como copy de Listing, none ou low já bastam; reserve high/max para cenários que exigem julgamento, como respostas de suporte sensíveis a políticas.
• A saída estruturada se comporta de forma diferente entre endpoints. Para este modelo, usar response_format: {"type": "json_schema", ...} em /v1/chat/completions não retorna resultados validados pelo schema — use response_format: {"type": "json_object"} e descreva a estrutura no prompt. Se você precisa forçar a validação por schema, envie a mesma requisição para /v1/responses com text.format.type=json_schema, que respeita essa configuração.
• Chamada de funções e streaming funcionam como esperado em /v1/chat/completions — tools, tool_choice e stream: true se comportam igual a qualquer outro modelo de chat compatível com OpenAI no hiapi, então seu código existente de chamada de ferramentas não precisa de ajustes.

A Base URL é https://api.hiapi.ai/v1, usando a mesma chave dos seus outros modelos hiapi. Os formatos completos de requisição/resposta dos dois endpoints estão na página do modelo.

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

O encaixe mais direto é transformar fichas técnicas em escala em copy de Listing alinhada à sua marca, em um formato que seu CMS importa diretamente sem pós-processamento. No Chat Completions, o modo json_object combinado com um schema explícito no prompt faz isso de forma confiável:

import json
import requests

resp = requests.post(
    "https://api.hiapi.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {HIAPI_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "deepseek-v4.1-flash",
        "reasoning_effort": "none",
        "response_format": {"type": "json_object"},
        "messages": [
            {
                "role": "system",
                "content": (
                    "You write concise, factual e-commerce listing copy. "
                    "Never invent specs that aren't in the input. "
                    "Respond with JSON matching this shape: "
                    '{"title": str, "short_description": str, '
                    '"long_description": str, "bullet_points": [str]}'
                ),
            },
            {
                "role": "user",
                "content": (
                    "Product: ceramic pour-over coffee dripper, 400ml, "
                    "matte white, dishwasher safe, fits standard filters. "
                    "Write listing copy for this product."
                ),
            },
        ],
    },
)
listing = json.loads(resp.json()["choices"][0]["message"]["content"])

Rode isso para cada SKU no seu banco de produtos e você obtém copy consistente sem editar texto manualmente em janelas de chat. Se você quer que a resposta dispare um erro explícito quando o formato estiver errado, em vez de depender da aderência do modelo ao prompt, envie a requisição equivalente para /v1/responses com text.format.type=json_schema — esse caminho valida a saída contra o seu schema antes de retornar.

Caso de uso 2: perguntas e respostas de suporte ao cliente baseadas na sua própria documentação

Para um assistente de suporte, ambos os endpoints exigem que você reenvie a conversa em andamento — nenhum dos dois mantém estado entre chamadas por padrão, então o histórico da conversa é gerenciado pela sua aplicação, não pelo fornecedor. Isso é útil se você precisa mascarar, ramificar ou restaurar conversas a partir do seu próprio banco de dados, em vez de confiar no armazenamento de sessão do fornecedor.

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/chat/completions",
        headers={"Authorization": f"Bearer {HIAPI_KEY}", "Content-Type": "application/json"},
        json={
            "model": "deepseek-v4.1-flash",
            "reasoning_effort": "low",
            "messages": history,
        },
    )
    answer = resp.json()["choices"][0]["message"]["content"]
    history.append({"role": "assistant", "content": answer})
    return answer

Para qualquer ação que precise verificar status de pedido ou disparar uma devolução, declare-a como função em tools — o modelo retorna um item tool_calls, seu backend o executa, e então você anexa uma mensagem role: "tool" com o resultado e chama novamente. Assim o modelo nunca toca diretamente seu banco de dados de pedidos, e ele funciona igual a qualquer outro modelo de chat compatível com OpenAI no hiapi.

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

O mesmo conjunto de fatos de produto precisa de formulações diferentes na página de produto, na linha de assunto de e-mail e em um título de anúncio de 30 caracteres. Com stream: true em /v1/chat/completions, você gera várias variações de canal em uma única requisição e as renderiza conforme chegam, em vez de esperar a resposta completa — útil se isso alimenta uma prévia em tempo real em uma ferramenta interna. Aqui também mantenha reasoning_effort em none ou low; casar o tom de um copy curto não exige raciocínio mais pesado, e isso mantém a latência baixa quando os profissionais de marketing iteram em tempo real.

Quanto custa

O DeepSeek V4.1 Flash cobra por token de forma uniforme, sem degraus que exijam planejamento prévio:

Entrada	Saída	Entrada em cache
$0.44 / 1M tokens	$1.32 / 1M tokens	$0.014 / 1M tokens

Para os casos acima — uma única descrição de produto, uma rodada de conversa de suporte, um lote de variações de canal — cada chamada custa apenas uma fração de centavos. A tarifa de entrada em cache vale a pena usar de forma consciente: se o seu prompt de sistema é longo e se repete em milhares de chamadas de SKU, mantenha-o byte a byte idêntico entre as requisições para que ele se qualifique à tarifa de cache. As tarifas são baseadas em uso e podem mudar — antes de assumir tarefas de grande volume, consulte hiapi.ai/pricing.

Como isso se relaciona com o resto da sua stack

Nada disso substitui o modelo de imagem propriamente dito — o DeepSeek V4.1 Flash não tem acesso a /v1/tasks e não consegue produzir saída visual. Se o seu fluxo de trabalho precisa de fotografia de produto ou imagens de lifestyle para acompanhar esse copy, trata-se de uma chamada separada a um modelo de imagem como o GPT Image 2, e os dois não compartilham formato de requisição nem endpoint. Se você já leu o guia de e-commerce do GPT-6 Astra, a forma deste problema é idêntica — a diferença é que o DeepSeek V4.1 Flash oferece escolha de endpoint e uma curva de custo plana, em vez de uma curva de custo escalonada.

FAQ

O DeepSeek V4.1 Flash consegue gerar imagens de produto? Não. É um modelo puramente textual, sem saída de imagem, áudio ou vídeo, acessível via /v1/chat/completions ou /v1/responses. Combine-o com um modelo de imagem para cuidar da parte visual do seu Listing de produto.

Para este modelo, devo usar Chat Completions ou Responses? Ambos funcionam — escolha o que corresponde à sua integração existente. O único caso em que faz diferença é forçar saída estruturada: a validação json_schema funciona em /v1/responses, mas não em /v1/chat/completions, onde você deve usar o modo json_object.

O que reasoning_effort faz e qual nível devo usar? Ele controla quanto raciocínio interno o modelo faz antes de responder, trocando latência e custo por qualidade de julgamento. Todos os cinco níveis (none, low, medium, high, max) são válidos em requisições reais, embora a página de preços liste apenas três. Para tarefas curtas e determinísticas como geração de descrições, use none ou low; reserve high ou max para respostas de suporte que envolvam julgamento.

O streaming pode ser usado junto com chamada de ferramentas? Sim — stream: true e tools funcionam de forma independente em /v1/chat/completions e podem ser combinados na mesma requisição, igual a qualquer outro modelo de chat compatível com OpenAI no hiapi.

Preciso reenviar a conversa completa a cada rodada de suporte? Sim, em ambos os endpoints. Nenhum dos dois mantém estado de conversa entre chamadas por padrão, então sua aplicação precisa reenviar o histórico necessário a cada vez. Isso aumenta o custo de tokens de entrada reenviados, mas significa que você controla qual contexto incluir e pode mascarar ou ramificar a conversa a partir do seu próprio banco de dados.

A tarifa de entrada em cache é automática? Ela só se aplica automaticamente quando a parte inicial da requisição (normalmente o prompt de sistema) é byte a byte idêntica entre chamadas. Verifique cached_tokens no objeto usage da resposta em vez de assumir que o desconto foi aplicado.