API atual/Referência completa/Venddor Intelligence: ferramentas de IA

Descrição de produto por IA

Sugere o texto de descrição de um produto a partir dos dados e das fotos dele, sem gravar nada.

É o botão "gerar descrição com IA" do cadastro de produto. A plataforma lê os dados do produto (nome, atributos, fotos) e devolve um texto. Nada é gravado: você mostra a sugestão, o administrador revisa e, se aceitar, salva com a API de produtos. O recurso depende da configuração de preenchimento por IA do catálogo estar ativa e liberar o campo descrição.

Devolve uma descrição para o produto indicado.

POST/api/v1/admin/intelligence/generate-descriptionAdmin

Sugerir a descrição de um produto

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um administrador (veja Tokens).

Content-Typestringobrigatório

application/json.

Corpo da requisição

product_iduuidobrigatório

Produto a descrever.

modestringpadrão: overwrite

overwriteappend

Como a interface pretende usar o texto. A plataforma só devolve o valor recebido no campo mode da resposta; a combinação com a descrição atual é feita por quem chama.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/generate-description" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
    "mode": "overwrite"
  }'

Resposta

200Descrição sugerida

json

{
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "mode": "overwrite",
  "description": "Mouse gamer com sensor óptico de 16.000 DPI, seis botões programáveis e iluminação RGB.",
  "tokens_in": 812,
  "tokens_out": 64
}

Campos da resposta

product_iduuid

Produto.

modestring

Valor recebido.

descriptionstring

Texto sugerido.

model_usedstring

Identificador do gerador usado. Informativo. Pode faltar.

tokens_ininteger

Tamanho da entrada. Informativo.

tokens_outinteger

Tamanho da saída. Informativo.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["manage_catalog","intelligence_use_chat"]}`
400	Corpo ilegível, `product_id` vazio ou `mode` inválido.	`{"error":"product_id is required"}` ou `{"error":"mode must be 'overwrite' or 'append'"}`
502	Falha do provedor de IA, ou resposta vazia.	`{"error":"AI provider error","detail":"..."}` ou `{"error":"AI returned empty description"}`
503	Preenchimento por IA não configurado.	`{"error":"AI provider not configured","detail":"Configure the AI provider in Modules ..."}`
500	Qualquer outra falha (por exemplo, o campo descrição não está liberado na configuração).	`{"error":"failed to generate description","detail":"..."}`

Veja também

Visão geral