Visão geral

A API deixa qualquer programa (site, loja, bot, planilha, automação) conversar com um projeto que você criou no painel. O assistente responde com o nome, as instruções e a ordem de IAs configurados no projeto. Se uma IA falhar, a próxima assume sozinha.

Endereço base:

{BASE}/api/v1

Tudo é enviado e recebido em JSON (UTF-8).

Autenticação

Gere uma chave no painel: Projeto → Chaves de API → Gerar nova chave. Envie em todo pedido no cabeçalho:

Authorization: Bearer sk_live_SUA_CHAVE

Cada chave pertence a um projeto. Para usar outro projeto, gere uma chave nele.

POST/v1/chat

Envia mensagens e recebe a resposta do assistente.

Corpo — forma simples

{ "mensagem": "Vocês entregam no mesmo dia?" }

Corpo — com histórico (conversa)

Para o assistente lembrar do que já foi dito, envie as mensagens anteriores em ordem. role é "user" (cliente) ou "assistant" (respostas anteriores do assistente). Máximo de 40 mensagens e 8000 caracteres por mensagem.

{
  "mensagens": [
    { "role": "user", "content": "Oi, qual o prazo de entrega?" },
    { "role": "assistant", "content": "Olá! A entrega é imediata, logo após o pagamento." },
    { "role": "user", "content": "E se der problema?" }
  ]
}

Resposta (200)

{
  "resposta": "Se der qualquer problema, é só chamar nosso suporte...",
  "ia": "gemini",
  "modelo": "gemini-2.5-flash",
  "tokens": 312
}

GET/v1/projeto

Confere se a chave está funcionando e mostra a qual projeto ela pertence.

{ "id": "prj_ab12cd34ef", "nome": "Atendimento", "descricao": "", "assistente": "Luna" }

Exemplos

cURL (terminal)

curl -X POST {BASE}/api/v1/chat \
  -H "Authorization: Bearer sk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"mensagem": "Olá!"}'

JavaScript (Node.js 18+, no servidor)

const r = await fetch('{BASE}/api/v1/chat', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.MINHA_CHAVE,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ mensagem: 'Olá!' }),
});
const dados = await r.json();
if (!r.ok) throw new Error(dados.erro);
console.log(dados.resposta);

Python

import os, requests

r = requests.post(
    "{BASE}/api/v1/chat",
    headers={"Authorization": "Bearer " + os.environ["MINHA_CHAVE"]},
    json={"mensagem": "Olá!"},
    timeout=90,
)
r.raise_for_status()
print(r.json()["resposta"])

Bot do Discord (discord.js v14)

Responde quando alguém menciona o bot. Guarde a chave em variável de ambiente, nunca no código.

const { Client, GatewayIntentBits } = require('discord.js');
const bot = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent] });

bot.on('messageCreate', async (msg) => {
  if (msg.author.bot || !msg.mentions.has(bot.user)) return;
  const pergunta = msg.content.replace(/<@!?\d+>/g, '').trim();
  const r = await fetch('{BASE}/api/v1/chat', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.MINHA_CHAVE, 'Content-Type': 'application/json' },
    body: JSON.stringify({ mensagem: pergunta }),
  });
  const dados = await r.json();
  msg.reply(r.ok ? dados.resposta.slice(0, 1900) : 'Ops: ' + dados.erro);
});

bot.login(process.env.DISCORD_TOKEN);

Erros

Quando algo dá errado, a resposta vem com o código HTTP e um campo erro explicando em português:

{ "erro": "Chave de API inválida ou revogada." }

Limites

• 60 pedidos por minuto por chave.
• Pedidos por dia conforme o plano da conta (somando todos os projetos). Zera à meia-noite, horário de Brasília.
• Até 40 mensagens por pedido, 8000 caracteres cada.
• Cada resposta pode demorar até ~60 segundos se a IA estiver lenta: use timeout de 90 s.

Segurança

• Nunca coloque a chave em código que roda no navegador do visitante (HTML/JS do site): qualquer pessoa conseguiria copiá-la. Chame a API a partir do seu servidor.
• Guarde a chave em variável de ambiente (.env), não no código nem no GitHub.
• Vazou? No painel, clique em Revogar e gere outra. A antiga para de funcionar na hora.
• Use uma chave por lugar (site, bot, automação) para conseguir revogar só uma.