中文 ▾
获取 API 密钥

JS 版 Character AI API:Node 与 Web 应用配置

Character AI API JS 配置主要涉及官方 openai npm 包、基础 URL 以及一个将密钥保留在服务器端的服务器路由。本页面展示了 Node 代码、流式 Express 接口及其对应的前端 fetch 代码。

浏览器面板通过发光管道连接到带有聊天气泡的服务器立方体,展示 JS 代理设计

要点

  1. openai npm 包开箱即用:更改 baseURL、apiKey 和模型为 uncensored。
  2. 切勿在浏览器代码中包含密钥。改为调用小型服务器路由。
  3. 流式输出使用服务器发送事件,一个打开的流占用一个并发槽位。
  4. 如果你偏好无依赖,原生 fetch 也可以。

简短说明

你可以通过三种方式使用 JavaScript 访问该接口:openai npm 包、原生 fetch,或任何已支持 OpenAI 聊天格式的库。Base URL 为 https://api.characteraiapi.com/v1,模型 ID 为 uncensored,每个请求都携带 Authorization: Bearer <key>。如果你还没有密钥,API 密钥页面说明了注册和一键 $0.50 试用。

这是一个独立服务,并非 Character.ai 产品。它运行一个开放权重模型,该模型针对合法成人用途进行了调整,可在无内容审查的情况下回答,且不生成图像、音频或视频。对于角色应用来说这就足够了:你编写人设,存储对话,并决定其外观。

使用 openai 包的 Node

创建项目,安装包并使用 ES 模块。示例假设使用 Node 18 或更高版本。

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"

第一个脚本 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);

使用 node chat.js 运行它。usage 对象会告诉你调用使用了多少提示词和补全 token,你可以将其乘以每百万 token $0.15 和 $0.50 来计算确切价格。

切勿将密钥放入浏览器代码中

将密钥粘贴到 React 组件中并从页面调用 API 很有诱惑力。不要这样做。每个访问者都可以打开网络选项卡或打包后的源代码并复制它,从而消耗你的余额。解决方法是在你控制的服务器上设置一个轻量代理。浏览器将用户的消息发送给你的路由;你的路由构建完整的消息列表,添加密钥并转发请求。

这也为你提供了一个执行 API 无法知晓的约束的地方:用户无法覆盖的人设、每个用户的消息限制,以及长历史记录的截断。浏览器应仅发送新的用户文本和会话 ID,而不是系统提示词。

流式 Express 接口

这里有一个带有单个路由的小型服务器。它在内存中保留会话用于演示;在实际应用中请使用数据库。

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);

切片保留了系统消息加上最后 20 条消息。旧的对话轮次会被丢弃,从而保持成本稳定。仅发送每个数据块的纯文本使浏览器端更简单。如果你想要更丰富的事件,请发送服务器发送事件并在客户端解析它们。

用于更丰富流式输出的服务器发送事件

发送纯文本适用于演示,但真实的聊天界面通常需要的不仅仅是文本:回复完成的信号、流式传输过程中的错误消息,或结束时的 token 使用情况。服务器发送事件通过相同的 HTTP 连接提供命名消息。你的路由以 SSE 格式写入行,浏览器使用小型解析器读取它们。

// 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();

将每个 token 编码为 JSON 可避免一个经典错误:包含换行符的 token 否则会破坏 SSE 框架。在客户端,读取响应体,按空行分割,剥离 data: 前缀并解析 JSON。done 消息告诉界面再次启用输入框并重新启用发送按钮。

处理断开连接。当用户关闭标签页时,服务器上的响应对象会触发 close 事件。监听它并中止上游请求,否则你的服务器会继续拉取无人读取的 token,并且该流会占用一个并发槽位。OpenAI SDK 在请求选项中接受 AbortSignal 以实现此目的。

浏览器端

前端调用你自己的路由,而不是 API 主机。使用 fetch 读取流式响应只需几行代码:

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; });

在回复流式传输时禁用发送按钮。这可以防止重复提交并尊重并发限制,因为流式请求会占用其槽位直到结束。

正确存储会话

内存映射会在进程重启时丢失所有内容,并且在运行两个服务器实例时就会失效。一旦原型工作,就将会话移动到数据库或键值存储中。将消息列表存储为 JSON 列,以用户和角色为键。当请求到达时,加载列表,附加新的用户消息,调用 API,附加回复并将列表写回。

尽早决定谁拥有系统提示词。将其保留在你的代码或配置中,而不是在浏览器可以影响的存储列表中。如果人设与历史记录一起存储,用户可能会尝试通过构造请求来覆盖它。每次在服务器端重建消息数组:来自配置的系统消息,后跟存储的对话轮次。

还要设置每个用户的限制。没有限制的公共聊天小部件会招致脚本滥用,每个 token 都会向你收费。每个用户每小时的计数器,在 API 调用之前进行检查,就足以开始。将其与消息长度的上限结合使用,以便一个请求不能发送1 MB 的文本。API 接受最多 8 MB 的请求体,但你自己的限制应低得多,例如每个用户消息 4,000 个字符。

原生 fetch、工具和 JSON 模式

如果你不想引入依赖,原始调用以相同的方式工作。从服务器、worker 或脚本运行此代码,而不是从公共页面代码运行。

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));

工具调用使用与 SDK 发送的相同 tools 和 tool_choice 字段。当模型返回 tool_calls 时,运行函数并将输出作为带有 role: "tool" 和匹配的 tool_call_id 的消息发送回去。在游戏中,这对于掷骰子、库存查找或查找角色对玩家记忆的内容很有用。流式传输时,工具调用作为部分片段到达,必须在解析参数之前将它们连接起来。

托管、限制和成本

流式传输增加了一些纯 JSON 路由没有的部署细节。一些托管平台和代理会缓冲响应或限制请求保持打开的时间。如果 token 在最后一次性到达而不是逐个到达,则缓冲层位于你的服务器和浏览器之间。查阅你平台的文档,查找禁用路由缓冲的选项,以及函数执行的时间限制,因为长角色扮演回复可能运行数秒。

对于 nginx 等反向代理,响应缓冲是常见原因,并具有按位置关闭的设置。对于无服务器函数,请在平台文档中查找流式响应模式。如果你的主机无法流式传输,廉价服务器上的小型常驻 Node 进程是一个可靠的回退方案。

最后,将密钥放在主机的环境变量存储中,并将其排除在构建输出之外。前端构建工具通常会将任何带有公共前缀的变量内联到浏览器包中,因此使用不带该前缀的名称,并仅在服务器代码中读取它。一个快速的检查是在构建后的文件中搜索密钥的前几个字符。

限制、重试和成本

完整密钥允许8个并发请求和每分钟300次请求。试用密钥允许2个并发和每分钟60次。超出限制时,API返回HTTP 429及代码rate_limited或concurrency。临时过载也会返回429并包含Retry-After: 5。在JavaScript中,SDK会抛出包含status === 429的错误;捕获它,等待并重试。SDK默认会重试几次,你可以通过客户端的maxRetries选项进行调整。

每轮成本很容易估算。一次包含 2,000 个输入 token 和 250 个输出 token 的聊天,输入成本为 2,000 x $0.15 / 1,000,000 = $0.0003,输出成本为 250 x $0.50 / 1,000,000 = $0.000125,总计 $0.000425。一千轮的成本为 $0.425。失败或被拒绝的请求不收费。参见 定价页面 了解从 $20 到 $500 的充值和奖励层级,以及 文档 中的完整参数列表。

问答

我可以从 React 或 Vue 应用中直接调用 API 吗?

技术上可以,但密钥会对所有访问者可见。使用一个添加密钥并转发请求的小型服务器路由。

我应该使用哪个 npm 包?

官方 openai 包即可。将 baseURL 设置为接口,使用你的密钥作为 apiKey,并指定模型 uncensored。使用原生 fetch 也可以。

它能在 Deno、Bun 或 Cloudflare Workers 上运行吗?

任何能发起带有 Bearer 头的 HTTPS 请求的运行时都可以调用它。openai 包支持多种运行时,请查阅其文档以获取你使用的运行时信息。

如何将 token 流式输出到页面?

在服务器端设置 stream: true,将每个 chunk 转发到浏览器,并使用 fetch reader 读取。每个打开的流会占用一个并发请求槽位。

这是 Character.ai 的官方 API 吗?

不是。这是一个独立的 OpenAI 兼容服务,拥有自己的 API 密钥和单一模型,作为你自有角色应用的后端提供。

只差一张表单,即可获得密钥

创建账户,复制密钥,更改基础 URL。这就是全部设置。

获取 API 密钥