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

要点
- openai npm 包开箱即用:更改 baseURL、apiKey 和模型为
uncensored。 - 切勿在浏览器代码中包含密钥。改为调用小型服务器路由。
- 流式输出使用服务器发送事件,一个打开的流占用一个并发槽位。
- 如果你偏好无依赖,原生 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 的充值和奖励层级,以及 文档 中的完整参数列表。