PT ▾
Obter chave de API

API Character AI em JS: Configuração para Node e Web App

Uma configuração de api character ai js depende do pacote npm openai oficial, uma URL base e uma rota de servidor que mantém sua chave fora do navegador. Esta página mostra o código Node, um endpoint de streaming Express e o fetch front-end correspondente.

Painel do navegador conectado por um tubo brilhante a um cubo de servidor com bolhas de chat, mostrando um design de proxy JS

Pontos principais

  1. O pacote npm openai funciona como está: altere baseURL, apiKey e o modelo para uncensored.
  2. Nunca envie a chave no código do navegador. Chame uma rota de servidor pequena.
  3. O streaming usa eventos enviados pelo servidor, e um stream aberto usa um slot de concorrência.
  4. Fetch puro também funciona se você preferir sem dependência.

O resumo

Você pode acessar o endpoint via JavaScript de três formas: o pacote npm openai, o fetch puro ou qualquer biblioteca que já suporte o formato de chat da OpenAI. A base URL é https://api.characteraiapi.com/v1, o ID do modelo é uncensored e toda requisição inclui Authorization: Bearer <key>. Se você ainda não tem uma chave, a página da chave de API explica o cadastro e o teste grátis de $0,50.

Este é um serviço independente, não o produto Character.ai. Ele executa um modelo de pesos abertos ajustado para responder sem recusas de conteúdo para uso adulto legal, e não gera imagens, áudio ou vídeo. Para um app de personagem, isso é suficiente: você define a persona, armazena a conversa e decide a aparência.

Node com o pacote openai

Crie um projeto, instale o pacote e use módulos ES. Os exemplos assumem Node 18 ou mais recente.

mkdir persona-chat && cd persona-chat
npm init -y
npm pkg set type=module
npm install openai express
export API_KEY="paste-your-key-here"

Um primeiro script em chat.js:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.characteraiapi.com/v1",
  apiKey: process.env.API_KEY,
});

const completion = await client.chat.completions.create({
  model: "uncensored",
  messages: [
    { role: "system", content: "You are Juno, a sarcastic lighthouse keeper. Stay in character." },
    { role: "user", content: "A boat is signalling in the fog. Thoughts?" },
  ],
  temperature: 0.9,
});

console.log(completion.choices[0].message.content);
console.log(completion.usage);

Execute-o com node chat.js. O objeto usage informa quantos tokens de prompt e completion a chamada usou, que você pode multiplicar por $0,15 e $0,50 por milhão para ver o preço exato.

Nunca coloque a chave no código do navegador

É tentador colar a chave em um componente React e chamar a API da página. Não faça isso. Todo visitante pode abrir a aba de rede ou o código bundle e copiá-la, gastando seu saldo. A solução é um proxy fino em um servidor que você controla. O navegador envia a mensagem do usuário para sua rota; sua rota constrói a lista completa de mensagens, adiciona a chave e encaminha a chamada.

Isso também oferece um local para impor regras que a API não conhece: uma persona que os usuários não podem sobrescrever, um limite de mensagens por usuário e o corte de históricos longos. O navegador deve enviar apenas o novo texto do usuário e um ID de conversa, não o prompt do sistema.

Um endpoint de streaming Express

Aqui está um servidor pequeno com uma rota. Ele mantém sessões na memória para a demonstração; use um banco de dados para qualquer uso real.

import express from "express";
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.characteraiapi.com/v1",
  apiKey: process.env.API_KEY,
});

const PERSONA = "You are Juno, a sarcastic lighthouse keeper. Stay in character, two to four sentences.";
const sessions = new Map();

const app = express();
app.use(express.json({ limit: "100kb" }));
app.use(express.static("public"));

app.post("/api/chat", async (req, res) => {
  const { id, text } = req.body;
  if (!id || !text) return res.status(400).json({ error: "id and text required" });

  const history = sessions.get(id) ?? [{ role: "system", content: PERSONA }];
  history.push({ role: "user", content: text });

  res.setHeader("Content-Type", "text/plain; charset=utf-8");

  try {
    const stream = await client.chat.completions.create({
      model: "uncensored",
      messages: [history[0], ...history.slice(-20)],
      stream: true,
    });
    let reply = "";
    for await (const chunk of stream) {
      const piece = chunk.choices[0]?.delta?.content ?? "";
      if (piece) {
        reply += piece;
        res.write(piece);
      }
    }
    history.push({ role: "assistant", content: reply });
    sessions.set(id, history);
    res.end();
  } catch (err) {
    res.status(err.status === 429 ? 429 : 500).end("error");
  }
});

app.listen(3000);

O slice mantém a mensagem do sistema mais as últimas 20 mensagens. As rodadas antigas caem, mantendo o custo estável. Enviar apenas o texto puro de cada chunk mantém o lado do navegador simples. Se quiser eventos mais ricos, envie eventos enviados pelo servidor e analise-os no cliente.

Eventos enviados pelo servidor para streaming mais rico

Enviar texto bruto funciona para uma demonstração, mas interfaces de chat reais geralmente precisam de mais do que texto: um sinal quando a resposta estiver completa, uma mensagem de erro no meio de um streaming ou o uso de tokens no final. Eventos enviados pelo servidor fornecem mensagens nomeadas pela mesma conexão HTTP. Sua rota grava linhas no formato SSE, e o navegador as lê com um pequeno parser.

// server: inside the route, after setting headers
res.setHeader("Content-Type", "text/event-stream");
res.setHeader("Cache-Control", "no-cache");

for await (const chunk of stream) {
  const piece = chunk.choices[0]?.delta?.content ?? "";
  if (piece) res.write(`data: ${JSON.stringify({ token: piece })}\n\n`);
}
res.write(`data: ${JSON.stringify({ done: true })}\n\n`);
res.end();

Codificar cada token como JSON evita um bug clássico: um token que contém uma quebra de linha quebraria o enquadramento SSE. No cliente, leia o corpo da resposta, divida por uma linha em branco, remova o prefixo data: e analise o JSON. A mensagem done diz à interface para habilitar a caixa de entrada novamente e reabilitar o botão enviar.

Trate desconexões. Quando o usuário fecha a aba, o objeto de resposta no servidor emite o evento close. Ouça-o e cancele a requisição upstream; caso contrário, seu servidor continua consumindo tokens que ninguém lê e o stream ocupa um dos seus slots de concorrência. O SDK da OpenAI aceita um AbortSignal nas opções de requisição para esse fim.

O lado do navegador

O front-end chama sua rota, nunca o host da API. Ler resposta em streaming com fetch requer poucas linhas:

const id = crypto.randomUUID();

async function send(text, onToken) {
  const res = await fetch("/api/chat", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ id, text }),
  });
  if (!res.ok) throw new Error("request failed: " + res.status);

  const reader = res.body.getReader();
  const decoder = new TextDecoder();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    onToken(decoder.decode(value, { stream: true }));
  }
}

send("Is the lamp lit?", (t) => { document.querySelector("#out").textContent += t; });

Desative o botão enviar enquanto uma resposta está sendo transmitida. Isso evita duplos envios e respeita o limite de concorrência, porque uma requisição transmitida ocupa seu slot até o fim.

Armazene sessões corretamente

Um mapa na memória perde tudo quando o processo reinicia e falha assim que você executa duas instâncias de servidor. Mova sessões para um banco de dados ou armazenamento de chave-valor assim que o protótipo funcionar. Armazene a lista de mensagens como uma coluna JSON, com chave por usuário e personagem. Quando uma requisição chegar, carregue a lista, anexe a nova mensagem do usuário, chame a API, anexe a resposta e salve a lista de volta.

Decida cedo quem é o proprietário do prompt do sistema. Mantenha-o no seu código ou configuração, não na lista armazenada que o navegador pode influenciar. Se a persona for armazenada junto com o histórico, um usuário poderia tentar sobrescrevê-la criando uma requisição. Reconstrua o array de mensagens no servidor toda vez: a mensagem de sistema da configuração, seguida pelas rodadas armazenadas.

Defina também um limite por usuário. Um widget de chat público sem limites convida abuso automatizado, e cada token é cobrado para você. Um contador por usuário por hora, verificado antes da chamada à API, é suficiente para começar. Combine-o com um limite superior no comprimento da mensagem para que uma requisição não envie um megabyte de texto. A API aceita corpos de até 8 MB, mas seu próprio limite deve ser muito menor, como 4.000 caracteres por mensagem do usuário.

Fetch puro, ferramentas e modo JSON

Se você não quiser dependências, uma chamada bruta funciona da mesma maneira. Execute isso de um servidor, um worker ou um script, não do código de uma página pública.

const r = await fetch("https://api.characteraiapi.com/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "uncensored",
    response_format: { type: "json_object" },
    messages: [
      { role: "system", content: "Reply with JSON only: {\"mood\": string, \"line\": string}" },
      { role: "user", content: "Juno sees a light on the water." },
    ],
  }),
});
const data = await r.json();
console.log(JSON.parse(data.choices[0].message.content));

A chamada de funções funciona com os mesmos campos tools e tool_choice que o SDK envia. Quando o modelo retorna tool_calls, execute a função e envie a saída de volta como uma mensagem com role: "tool" e o tool_call_id correspondente. Em um jogo, isso é útil para rolagens de dados, consultas de inventário ou uma consulta sobre o que o personagem lembra do jogador. Ao fazer streaming, as chamadas de funções chegam como fragmentos parciais que você deve unir antes de analisar os argumentos.

Hospedagem, limites e custo

O streaming adiciona alguns detalhes de implantação que rotas JSON puras não têm. Algumas plataformas de hospedagem e proxies bufferizam respostas ou limitam quanto tempo uma requisição pode permanecer aberta. Se os tokens chegarem em um bloco no final em vez de um por um, uma camada de buffer está entre seu servidor e o navegador. Verifique a documentação da sua plataforma para a opção que desativa o buffer para uma rota, e para qualquer limite de tempo na execução de funções, já que uma resposta de roleplay longa pode durar vários segundos.

Para um proxy reverso como nginx, o buffer de resposta é um culpado comum e tem uma configuração para desativar por local. Para funções serverless, procure um modo de resposta streaming na documentação da plataforma. Se seu host não puder transmitir, um pequeno processo Node sempre ativo em um servidor barato é um fallback confiável.

Finalmente, coloque o segredo no armazenamento de variáveis de ambiente do host e mantenha-o fora da saída de build. Ferramentas de build front-end frequentemente embutem qualquer variável que tenha um prefixo público no bundle do navegador, então use um nome sem esse prefixo e leia-o apenas no código do servidor. Uma verificação rápida é buscar seus arquivos construídos pelos primeiros caracteres da chave.

Limites, retentativas e custo

Uma chave completa permite 8 requisições simultâneas e 300 por minuto. Uma chave de teste permite 2 e 60. Ao ultrapassar o limite, a API responde com HTTP 429 e o código rate_limited ou concurrency. Uma sobrecarga temporária também é 429 e inclui Retry-After: 5. Em JavaScript, o SDK lança um erro com status === 429; capture-o, aguarde e tente novamente. O SDK também tenta novamente algumas vezes por padrão, o que você pode ajustar com a opção maxRetries no cliente.

O custo por turno é fácil de estimar. Um chat com 2.000 tokens de entrada e 250 tokens de saída custa 2.000 x $0,15 / 1.000.000 = $0,0003 para entrada e 250 x $0,50 / 1.000.000 = $0,000125 para saída, totalizando $0,000425. Mil turnos custam $0,425. Requisições com falha ou recusadas não são cobradas. Consulte a página de preços para recargas de $20 a $500 e os níveis de bônus, e a documentação para a lista completa de parâmetros.

Perguntas e respostas

Posso chamar a API diretamente de um app React ou Vue?

Tecnicamente sim, mas a chave ficaria visível para todos os visitantes. Use uma rota de servidor pequena que adiciona a chave e encaminha a requisição.

Qual pacote npm devo usar?

O pacote openai oficial funciona. Defina baseURL para o endpoint, use sua chave como apiKey e o modelo uncensored. Fetch puro também funciona.

Funciona no Deno, Bun ou Cloudflare Workers?

Qualquer runtime que possa fazer uma requisição HTTPS com um cabeçalho Bearer pode chamá-la. O pacote openai suporta vários runtimes, então verifique a documentação para o seu.

Como faço para transmitir tokens para a página?

Defina stream: true no servidor, encaminhe cada chunk para o navegador e leia-o com um leitor fetch. Cada stream aberto ocupa um slot de concorrência.

Esta é a API oficial do Character.ai?

Não. É um serviço independente compatível com OpenAI, com sua própria chave e um único modelo, oferecido como backend para seus próprios aplicativos de personagens.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API