VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/AI Builder

Ajustes do AI Builder

Configura o provedor de IA e o gerador de imagens, revela chaves e testa a conexão.

Cada loja configura qual provedor de IA o AI Builder usa e, opcionalmente, um serviço de geração de imagens para os banners. As chaves são sensíveis: as respostas as devolvem mascaradas (sk-a••••••••7890) e existe uma rota específica, auditada, para revelar uma delas.

Reenviar o valor mascarado preserva a chave

Ao salvar, se uma chave vier com o caractere •, o servidor entende que você não a alterou e mantém a guardada. Então um formulário pode reenviar tudo que leu sem apagar as chaves.

Obter ajustes

Devolve os ajustes atuais com as chaves mascaradas.

GET/api/v1/admin/ai-builder/settingsAdmin

Obter os ajustes

Requer o privilégio manage_theme.

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/admin/ai-builder/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ajustes
json
{
  "settings": {
    "anthropic_api_key": "sk-a••••••••7890",
    "anthropic_model": "claude-haiku-4-5-20251001",
    "openai_compatible_url": "https://ia.minhaloja.com.br/v1",
    "openai_compatible_key": "1763••••••••58c1",
    "openai_compatible_model": "meu-modelo",
    "active_provider": "anthropic",
    "max_tokens": 16000,
    "temperature": 0.7,
    "enabled": true,
    "rate_limit_per_hour": 20,
    "max_file_size_mb": 20,
    "max_files_per_session": 5,
    "image_api_url": "https://imggen.exemplo.com/api/v1",
    "image_api_key": "abcd••••••••wxyz",
    "updated_at": "2026-07-19T19:06:04.752346Z"
  }
}

Campos da resposta

settingsobject

Ajustes.

anthropic_api_keystring
Chave do provedor Anthropic. Sempre mascarada nas respostas (4 primeiros e 4 últimos caracteres).
anthropic_modelstring
Modelo usado no provedor Anthropic.
openai_compatible_urlstring
Endereço do provedor compatível com a API da OpenAI (modelo próprio).
openai_compatible_keystring
Chave desse provedor (mascarada).
openai_compatible_modelstring
Modelo desse provedor.
active_providerstring
anthropicopenai_compatible
Provedor em uso: anthropic ou openai_compatible.
max_tokensinteger
Limite de tokens por resposta.
temperaturenumber
Criatividade da IA.
enabledboolean
false desliga o AI Builder: as mensagens recebem a resposta de que ele está desabilitado.
rate_limit_per_hourinteger
Limite informado de mensagens por hora. Hoje é apenas guardado.
max_file_size_mbinteger
Tamanho máximo informado de arquivo. Hoje é apenas guardado.
max_files_per_sessioninteger
Máximo informado de arquivos por sessão. Hoje é apenas guardado.
image_api_urlstring
Endereço do serviço de geração de imagens para os banners.
image_api_keystring
Chave desse serviço (mascarada).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to get settings","detail":"..."}

Salvar ajustes

Grava os ajustes por inteiro: todos os campos são gravados, então envie o objeto completo lido do GET (campos que faltarem voltam ao vazio ou a zero). Devolve os ajustes novos, com as chaves mascaradas.

PUT/api/v1/admin/ai-builder/settingsAdmin

Salvar os ajustes

Requer o privilégio manage_theme.

Corpo da requisição

anthropic_api_keystring
Chave do provedor Anthropic. Sempre mascarada nas respostas (4 primeiros e 4 últimos caracteres).
anthropic_modelstring
Modelo usado no provedor Anthropic.
openai_compatible_urlstring
Endereço do provedor compatível com a API da OpenAI (modelo próprio).
openai_compatible_keystring
Chave desse provedor (mascarada).
openai_compatible_modelstring
Modelo desse provedor.
active_providerstringobrigatório
anthropicopenai_compatible
Provedor em uso: anthropic ou openai_compatible.
max_tokensinteger
Limite de tokens por resposta.
temperaturenumber
Criatividade da IA.
enabledboolean
false desliga o AI Builder: as mensagens recebem a resposta de que ele está desabilitado.
rate_limit_per_hourinteger
Limite informado de mensagens por hora. Hoje é apenas guardado.
max_file_size_mbinteger
Tamanho máximo informado de arquivo. Hoje é apenas guardado.
max_files_per_sessioninteger
Máximo informado de arquivos por sessão. Hoje é apenas guardado.
image_api_urlstring
Endereço do serviço de geração de imagens para os banners.
image_api_keystring
Chave desse serviço (mascarada).

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/ai-builder/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anthropic_api_key": "sk-a••••••••7890",
    "anthropic_model": "claude-haiku-4-5-20251001",
    "openai_compatible_url": "https://ia.minhaloja.com.br/v1",
    "openai_compatible_key": "1763••••••••58c1",
    "openai_compatible_model": "meu-modelo",
    "active_provider": "anthropic",
    "max_tokens": 16000,
    "temperature": 0.7,
    "enabled": true,
    "rate_limit_per_hour": 20,
    "max_file_size_mb": 20,
    "max_files_per_session": 5,
    "image_api_url": "https://imggen.exemplo.com/api/v1",
    "image_api_key": "abcd••••••••wxyz"
  }'

Resposta

200Ajustes salvos
json
{
  "settings": {
    "anthropic_api_key": "sk-a••••••••7890",
    "anthropic_model": "claude-haiku-4-5-20251001",
    "openai_compatible_url": "https://ia.minhaloja.com.br/v1",
    "openai_compatible_key": "1763••••••••58c1",
    "openai_compatible_model": "meu-modelo",
    "active_provider": "anthropic",
    "max_tokens": 16000,
    "temperature": 0.7,
    "enabled": true,
    "rate_limit_per_hour": 20,
    "max_file_size_mb": 20,
    "max_files_per_session": 5,
    "image_api_url": "https://imggen.exemplo.com/api/v1",
    "image_api_key": "abcd••••••••wxyz",
    "updated_at": "2026-07-19T19:06:04.752346Z"
  }
}

Campos da resposta

settingsobject

Ajustes salvos (chaves mascaradas).

anthropic_api_keystring
Chave do provedor Anthropic. Sempre mascarada nas respostas (4 primeiros e 4 últimos caracteres).
anthropic_modelstring
Modelo usado no provedor Anthropic.
openai_compatible_urlstring
Endereço do provedor compatível com a API da OpenAI (modelo próprio).
openai_compatible_keystring
Chave desse provedor (mascarada).
openai_compatible_modelstring
Modelo desse provedor.
active_providerstring
anthropicopenai_compatible
Provedor em uso: anthropic ou openai_compatible.
max_tokensinteger
Limite de tokens por resposta.
temperaturenumber
Criatividade da IA.
enabledboolean
false desliga o AI Builder: as mensagens recebem a resposta de que ele está desabilitado.
rate_limit_per_hourinteger
Limite informado de mensagens por hora. Hoje é apenas guardado.
max_file_size_mbinteger
Tamanho máximo informado de arquivo. Hoje é apenas guardado.
max_files_per_sessioninteger
Máximo informado de arquivos por sessão. Hoje é apenas guardado.
image_api_urlstring
Endereço do serviço de geração de imagens para os banners.
image_api_keystring
Chave desse serviço (mascarada).
updated_atstring
Última alteração (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400active_provider diferente de anthropic e openai_compatible.{"error":"active_provider must be 'anthropic' or 'openai_compatible'"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to update settings","detail":"..."}

Revelar chave

Devolve o valor completo de uma chave, para o administrador copiá-la de novo. Cada chamada gera um registro de auditoria no servidor.

POST/api/v1/admin/ai-builder/settings/reveal-keyAdmin

Revelar uma chave

Requer o privilégio manage_theme.

Corpo da requisição

fieldstringobrigatório
anthropic_api_keyopenai_compatible_keyimage_api_key
Qual chave.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-builder/settings/reveal-key" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "anthropic_api_key"
  }'

Resposta

200Chave
json
{
  "field": "anthropic_api_key",
  "value": "sk-ant-...valor-completo..."
}

Campos da resposta

fieldstring
A chave pedida.
valuestring
O valor completo, em texto puro.

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
400field fora dos três valores aceitos.{"error":"invalid field","detail":"must be one of: anthropic_api_key, openai_compatible_key, image_api_key"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
500Falha de banco de dados ou do provedor de IA.{"error":"failed to get settings","detail":"..."}
Trate a resposta como segredo

Não registre a resposta em logs nem a mostre em telas compartilhadas.

Testar conexão

Faz uma chamada curta ao provedor com os ajustes que você enviar (ou, nos campos de chave mascarados, com os guardados) para validar chave, endereço e modelo antes de salvar. Não grava nada. Consome uma pequena quantidade de tokens.

POST/api/v1/admin/ai-builder/test-connectionAdmin

Testar a conexão com o provedor

Requer o privilégio manage_theme.

Corpo da requisição

anthropic_api_keystring
Chave do provedor Anthropic. Sempre mascarada nas respostas (4 primeiros e 4 últimos caracteres).
anthropic_modelstring
Modelo usado no provedor Anthropic.
openai_compatible_urlstring
Endereço do provedor compatível com a API da OpenAI (modelo próprio).
openai_compatible_keystring
Chave desse provedor (mascarada).
openai_compatible_modelstring
Modelo desse provedor.
active_providerstring
Provedor em uso: anthropic ou openai_compatible.
max_tokensinteger
Limite de tokens por resposta.
temperaturenumber
Criatividade da IA.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/ai-builder/test-connection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "anthropic_api_key": "sk-a••••••••7890",
    "anthropic_model": "claude-haiku-4-5-20251001",
    "active_provider": "anthropic",
    "max_tokens": 512,
    "temperature": 0.7
  }'

Resposta

200Conexão válida
json
{
  "ok": true,
  "message": "Connected successfully. Model: claude-haiku-4-5-20251001, Tokens used: 24"
}
200Conexão falhou
json
{
  "ok": false,
  "message": "connection failed: ..."
}

Campos da resposta

okboolean
true se a IA respondeu.
messagestring
Resumo do teste ou o motivo da falha.

Erros

StatusQuandoCorpo de exemplo
400Corpo JSON inválido.{"error":"invalid request body","detail":"unexpected EOF"}
401Sem token, token inválido ou expirado.{"error":"invalid or expired token"}
403Seu usuário não tem o privilégio manage_theme.{"error":"insufficient privileges","required":"manage_theme"}
Falha também é 200

Uma conexão que não funciona devolve 200 com ok: false. Olhe o campo ok, não o status.

Veja também

  • AI Builder: visão geral
  • Conversar com a IA
Anterior
Modelos de tema
Próxima
Gerar banners
Nesta página
  • Obter ajustes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Salvar ajustes
  • Exemplo de requisição
  • Resposta
  • Erros
  • Revelar chave
  • Exemplo de requisição
  • Resposta
  • Erros
  • Testar conexão
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também