API Character AI trong JS: Thiết lập Node và Ứng dụng Web
Thiết lập api character ai js bao gồm gói npm openai chính thức, một base URL và một tuyến máy chủ giữ khóa của bạn khỏi trình duyệt. Trang này hiển thị mã Node, một endpoint streaming Express và fetch phía front-end tương ứng.
Cập nhật

Điểm chính
- Gói npm openai hoạt động ngay lập tức: thay đổi baseURL, apiKey và mô hình thành
uncensored. - Không bao giờ gửi khóa trong mã trình duyệt. Hãy gọi một tuyến máy chủ nhỏ thay thế.
- Streaming sử dụng sự kiện gửi qua máy chủ (SSE), và một luồng mở chiếm một khe đồng thời.
- Fetch thuần cũng hoạt động nếu bạn muốn không phụ thuộc vào thư viện.
Tóm tắt nhanh
Bạn có thể gọi endpoint từ JavaScript theo ba cách: gói npm openai, hàm fetch thuần, hoặc bất kỳ thư viện nào đã hỗ trợ định dạng chat OpenAI. Base URL là https://api.characteraiapi.com/v1, model ID là uncensored, và mọi yêu cầu đều mang Authorization: Bearer <key>. Nếu bạn chưa có khóa API, trang khóa API giải thích cách đăng ký và dùng thử $0,50 chỉ với một cú nhấp chuột.
Đây là một dịch vụ độc lập, không phải sản phẩm Character.ai. Nó chạy một mô hình trọng số mở được tinh chỉnh để trả lời mà không từ chối nội dung cho người lớn hợp pháp, và không tạo hình ảnh, âm thanh hoặc video. Đối với ứng dụng nhân vật, điều này là đủ: bạn viết persona, lưu trữ cuộc trò chuyện và quyết định giao diện.
Node với gói openai
Tạo dự án, cài đặt gói và sử dụng mô-đun ES. Các ví dụ giả định Node 18 trở lên.
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"Một tập lệnh đầu tiên trong 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);Chạy nó bằng node chat.js. Đối tượng usage cho bạn biết số token prompt và completion mà lệnh gọi đã sử dụng, bạn có thể nhân chúng với $0,15 và $0,50 trên mỗi triệu để xem giá chính xác.
Không bao giờ đặt khóa trong mã trình duyệt
Rất dễ muốn dán khóa vào thành phần React và gọi API từ trang. Đừng làm vậy. Mọi khách truy cập đều có thể mở tab mạng hoặc mã nguồn đã đóng gói và sao chép nó, sau đó tiêu tốn số dư của bạn. Giải pháp là một proxy mỏng trên máy chủ do bạn kiểm soát. Trình duyệt gửi tin nhắn của người dùng đến tuyến của bạn; tuyến của bạn xây dựng danh sách tin nhắn đầy đủ, thêm khóa và chuyển tiếp lệnh gọi.
Điều này cũng cung cấp cho bạn một nơi để thực thi các quy tắc mà API không biết: một nhân vật mà người dùng không thể ghi đè, giới hạn tin nhắn trên mỗi người dùng và cắt ngắn lịch sử dài. Trình duyệt chỉ nên gửi văn bản người dùng mới và ID cuộc trò chuyện, không phải prompt hệ thống.
Một endpoint Express truyền phát
Đây là một máy chủ nhỏ với một tuyến. Nó lưu trữ phiên trong bộ nhớ cho bản demo; hãy dùng cơ sở dữ liệu cho bất kỳ ứng dụng thực tế nào.
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ạn slice giữ lại tin nhắn hệ thống cộng với 20 tin nhắn cuối cùng. Các lượt cũ bị loại bỏ, giúp chi phí ổn định. Gửi chỉ văn bản thuần của từng chunk giúp phía trình duyệt đơn giản. Nếu bạn muốn các sự kiện phong phú hơn, hãy gửi sự kiện gửi qua máy chủ (SSE) thay thế và phân tích cú pháp chúng ở phía máy khách.
Sự kiện gửi qua máy chủ cho streaming phong phú hơn
Gửi văn bản thô hoạt động cho bản demo, nhưng các giao diện trò chuyện thực sự thường cần nhiều hơn văn bản: một tín hiệu khi phản hồi hoàn tất, một thông báo lỗi ở giữa luồng, hoặc sử dụng token ở cuối. Sự kiện gửi qua máy chủ (SSE) cung cấp các tin nhắn có tên trên cùng kết nối HTTP. Tuyến của bạn ghi các dòng theo định dạng SSE, và trình duyệt đọc chúng bằng một trình phân tích cú pháp nhỏ.
// 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();Mã hóa mỗi token dưới dạng JSON tránh một lỗi kinh điển: một token chứa dấu ngắt dòng sẽ phá vỡ khung SSE. Ở phía máy khách, đọc body phản hồi, chia trên dòng trống, bỏ tiền tố data: và phân tích cú pháp JSON. Tin nhắn done cho giao diện biết kích hoạt lại hộp nhập và kích hoạt lại nút gửi.
Xử lý ngắt kết nối. Khi người dùng đóng tab, đối tượng phản hồi trên máy chủ phát ra sự kiện close. Hãy lắng nghe sự kiện này và hủy yêu cầu upstream, nếu không máy chủ của bạn sẽ tiếp tục lấy token mà không ai đọc, và luồng sẽ giữ một slot đồng thời của bạn. SDK OpenAI chấp nhận AbortSignal trong tùy chọn yêu cầu cho mục đích này.
Phía trình duyệt
Giao diện người dùng gọi tuyến của bạn, không bao giờ gọi máy chủ API. Đọc phản hồi được truyền phát bằng fetch chỉ cần vài dòng:
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; });Vô hiệu hóa nút gửi trong khi phản hồi đang được truyền phát. Điều này ngăn gửi trùng lặp và tôn trọng giới hạn đồng thời, vì một yêu cầu streaming chiếm slot của nó cho đến khi kết thúc.
Lưu trữ phiên đúng cách
Bản đồ trong bộ nhớ mất mọi thứ khi quy trình khởi động lại và nó bị hỏng ngay khi bạn chạy hai phiên bản máy chủ. Chuyển phiên vào cơ sở dữ liệu hoặc kho lưu trữ khóa-giá trị ngay khi prototype hoạt động. Lưu danh sách tin nhắn dưới dạng cột JSON, được khóa theo người dùng và nhân vật. Khi có yêu cầu, tải danh sách, thêm tin nhắn người dùng mới, gọi API, thêm phản hồi và ghi lại danh sách.
Quyết định sớm ai sở hữu prompt hệ thống. Giữ nó trong mã hoặc cấu hình của bạn, không phải trong danh sách lưu trữ mà trình duyệt có thể ảnh hưởng. Nếu nhân vật được lưu trữ cùng lịch sử, người dùng có thể cố gắng ghi đè nó bằng cách tạo yêu cầu. Xây dựng lại mảng tin nhắn trên máy chủ mỗi lần: tin nhắn hệ thống từ cấu hình, theo sau là các lượt đã lưu trữ.
Cũng đặt giới hạn trên mỗi người dùng. Một widget trò chuyện công cộng không có giới hạn dễ bị lạm dụng bởi bot, và mọi token đều được tính phí cho bạn. Bộ đếm trên mỗi người dùng mỗi giờ, được kiểm tra trước khi gọi API, là đủ để bắt đầu. Kết hợp nó với giới hạn trên độ dài tin nhắn để một yêu cầu không thể gửi một megabyte văn bản. API chấp nhận body lên đến 8 MB, nhưng giới hạn của riêng bạn nên thấp hơn nhiều, chẳng hạn như 4.000 ký tự trên mỗi tin nhắn người dùng.
Fetch thuần, công cụ và chế độ JSON
Nếu bạn không muốn dùng thư viện phụ thuộc, một lệnh gọi thô hoạt động theo cách tương tự. Chạy điều này từ máy chủ, worker hoặc tập lệnh, không phải từ mã trang công khai.
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));Gọi hàm hoạt động với các trường tools và tool_choice giống như SDK gửi. Khi mô hình trả về tool_calls, hãy chạy hàm và gửi kết quả lại dưới dạng tin nhắn với role: "tool" và tool_call_id tương ứng. Trong trò chơi, tính năng này hữu ích để tung xúc xắc, tra cứu kho đồ hoặc tìm hiểu những gì nhân vật nhớ về người chơi. Khi truyền phát, các lệnh gọi công cụ đến dưới dạng các mảnh riêng lẻ mà bạn phải ghép lại trước khi phân tích cú pháp đối số.
Hosting, giới hạn và chi phí
Streaming thêm một số chi tiết triển khai mà các tuyến JSON thuần không có. Một số nền tảng hosting và proxy đệm phản hồi hoặc giới hạn thời gian yêu cầu có thể mở. Nếu token đến cùng một lúc ở cuối thay vì từng cái một, một lớp đệm nằm giữa máy chủ của bạn và trình duyệt. Hãy kiểm tra tài liệu nền tảng của bạn cho tùy chọn vô hiệu hóa đệm cho một tuyến, và bất kỳ giới hạn thời gian nào đối với việc thực thi hàm, vì một phản hồi roleplay dài có thể chạy trong nhiều giây.
Đối với proxy ngược như nginx, đệm phản hồi là một nguyên nhân phổ biến và có một cài đặt để tắt theo vị trí. Đối với các hàm serverless, hãy tìm chế độ phản hồi streaming trong tài liệu nền tảng. Nếu máy chủ của bạn không thể streaming, một quy trình Node luôn chạy trên máy chủ giá rẻ là một giải pháp dự phòng đáng tin cậy.
Cuối cùng, đặt bí mật vào kho biến môi trường của máy chủ và giữ nó khỏi kết quả build. Các công cụ build front-end thường nhúng mọi biến có tiền tố công khai vào bundle trình duyệt, vì vậy hãy dùng tên không có tiền tố đó và chỉ đọc nó trong mã máy chủ. Một cách kiểm tra nhanh là tìm kiếm các tệp đã build của bạn để tìm vài ký tự đầu tiên của khóa.
Giới hạn, thử lại và chi phí
Một khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 mỗi phút. Một khóa dùng thử cho phép 2 và 60. Vượt quá giới hạn, API trả về HTTP 429 và mã rate_limited hoặc concurrency. Quá tải tạm thời cũng là 429 và bao gồm Retry-After: 5. Trong JavaScript, SDK ném lỗi với status === 429; hãy bắt lỗi, đợi và thử lại. SDK cũng tự động thử lại vài lần theo mặc định, điều này bạn có thể điều chỉnh bằng tùy chọn maxRetries trên client.
Chi phí mỗi lượt dễ ước tính. Một cuộc trò chuyện với 2.000 token đầu vào và 250 token đầu ra tốn 2.000 x $0,15 / 1.000.000 = $0,0003 cho đầu vào và 250 x $0,50 / 1.000.000 = $0,000125 cho đầu ra, tổng cộng $0,000425. Một nghìn lượt là $0,425. Các yêu cầu thất bại hoặc bị từ chối không bị tính phí. Xem trang giá cả để nạp tiền từ $20 đến $500 và các cấp độ bonus, cũng như tài liệu để xem danh sách đầy đủ các tham số.