繁中 ▾
取得 API 金鑰

JS 版 Character AI API:Node 與網頁應用程式設定

Character AI API 的 JavaScript 設定主要依賴官方的 openai npm 套件、Base URL,以及一個將金鑰保留在伺服器端而不暴露於瀏覽器的伺服器路由。本頁展示了 Node.js 程式碼、用於串流輸出的 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 產品。它運行一個開放權重模型,該模型針對合法成人用途調整為無內容拒絕地回答,且不生成圖片、音訊或影片。對於角色應用程式來說這已足夠:你撰寫人格、儲存對話並決定其外觀。

Node 搭配 openai 套件

建立專案、安裝套件並使用 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,你可以將其乘以每百萬 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);

slice 保留系統訊息加上最後 20 則訊息。舊的對話輪次會被捨棄,這能保持成本穩定。只發送每個 chunk 的純文字可讓瀏覽器端保持簡單。如果你想要更豐富的事件,請改為發送伺服器發送事件並在客戶端解析它們。

用於更豐富串流的伺服器發送事件

發送純文字適用於示範,但實際的聊天介面通常需要的不只是文字:回覆完成的訊號、串流中間的錯誤訊息,或結尾的 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,將每個區塊轉發至瀏覽器,並使用 fetch reader 讀取。每個開啟的串流會佔用一個並行請求槽位。

這是 Character.ai 的官方 API 嗎?

不是。這是一項獨立的 OpenAI 相容服務,擁有自己的金鑰與單一模型,作為你自有角色應用程式的後端提供。

只差一張表單,即可取得金鑰

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。

取得 API 金鑰