إعداد واجهة برمجة تطبيقات Character AI في JS: Node وتطبيق الويب
يختزل إعداد واجهة برمجة تطبيقات Character AI في JS في حزمة npm الرسمية openai، و URL أساسي ومسار خادم يحافظ على مفتاحك بعيداً عن المتصفح. تعرض هذه الصفحة كود Node، ونقطة نهاية Express المتدفقة، وواجهة fetch الأمامية المقابلة لها.
محدّث

نقاط رئيسية
- تعمل حزمة npm الخاصة بـ openai كما هي: غيّر baseURL وapiKey والنموذج إلى
uncensored. - لا ترسل المفتاح أبداً في كود المتصفح. بل استدعِ مسار خادم صغير بدلاً من ذلك.
- يستخدم البث المتدفق الأحداث المرسلة من الخادم (SSE)، ويستخدم كل تدفق مفتوح خانة تزامن واحدة.
- يعمل fetch العادي أيضاً إذا كنت تفضل عدم وجود اعتماديات.
النسخة المختصرة
يمكنك الوصول إلى نقطة النهاية من JavaScript بثلاث طرق: حزمة openai npm، أو fetch الخام، أو أي مكتبة تدعم بالفعل نموذج دردشة OpenAI. عنوان URL الأساسي هو https://api.characteraiapi.com/v1، ومعرف النموذج هو uncensored، ويحمل كل طلب Authorization: Bearer <key>. إذا لم يكن لديك مفتاح API بعد، يشرح صفحة مفتاح 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. يُخبرك كائن الاستخدام بعدد رموز الموجّه ورموز الإكمال التي استخدمها الطلب، ويمكنك ضربها في $0.15 و$0.50 لكل مليون لمعرفة السعر الدقيق.
لا تضع المفتاح أبداً في كود المتصفح
من المغري لصق مفتاح API في مكون React واستدعاء API من الصفحة. لا تفعل ذلك. يمكن لكل زائر فتح علامة تبويب الشبكة أو الكود المدمج ونسخه، ثم ينفق رصيدك. الحل هو وسيط خفيف على خادم تتحكم به. يرسل المتصفح رسالة المستخدم إلى المسار الخاص بك؛ ويبني المسار الخاص بك قائمة الرسائل الكاملة، ويضيف المفتاح ويوجه الطلب.
يوفر لك هذا أيضاً مكاناً لفرض أشياء لا تعرفها الـ API: شخصية لا يمكن للمستخدمين الكتابة فوقها، وحد رسائل لكل مستخدم، واقتطاع السجلات الطويلة. يجب أن يرسل المتصفح فقط نص المستخدم الجديد ومعرف المحادثة، وليس موجّه النظام.
نقطة نهاية بث متدفق في 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 رسالة. تتساقط الأدوار القديمة، مما يحافظ على ثبات التكلفة. إرسال النص العاري لكل جزء فقط يبسط جانب المتصفح. إذا كنت تريد أحداثًا أكثر ثراءً، فأرسل الأحداث المرسلة من الخادم (SSE) بدلاً من ذلك وقم بتحليلها على جانب العميل.
الأحداث المرسلة من الخادم لبث أكثر ثراءً
إرسال النص الخام يعمل لعرض تجريبي، لكن واجهات الدردشة الحقيقية تحتاج عادةً إلى أكثر من النص: إشارة عند اكتمال الرد، أو رسالة خطأ في وسط البث المتدفق، أو استخدام الرموز في النهاية. تمنحك أحداث SSE رسائل مسماة عبر نفس اتصال 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();يؤدي ترميز كل رمز كـ JSON إلى تجنب خطأ كلاسيكي: رمز يحتوي على سطر جديد سيؤدي إلى كسر إطار SSE. على العميل، اقرأ جسم الاستجابة، افصل على سطر فارغ، أزل بادئة data: وقم بتحليل JSON. تخبر رسالة done الواجهة بتمكين مربع الإدخال مرة أخرى وإعادة تمكين زر الإرسال.
عالج انقطاعات الاتصال. عندما يغلق المستخدم علامة التبويب، يُصدر كائن الاستجابة على الخادم حدث close. استمع له وأبطل الطلب القادم من الأعلى، وإلا سيستمر خادمك في سحب رموز لا يقرأها أحد، وسيظل التدفق يحتفظ بخانة تزامن واحدة من فتحاتك. تقبل واجهة برمجة تطبيقات OpenAI إشارة 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; });عطّل زر الإرسال أثناء بث الرد. يمنع الإرسال المزدوج ويحترم حد الطلبات المتزامنة، لأن الطلب المتدفق يشغل خانته حتى ينتهي.
تخزين الجلسات بشكل صحيح
تفقد خريطة (Map) في الذاكرة كل البيانات عند إعادة تشغيل العملية، وتنكسر بمجرد تشغيل مثيلين للخادم. انقل الجلسات إلى قاعدة بيانات أو متجر مفاتيح-قيم بمجرد أن يعمل النموذج الأولي. احفظ قائمة الرسائل كعمود JSON، مُفهرجة حسب المستخدم والشخصية. عند وصول طلب، حمّل القائمة، أضف رسالة المستخدم الجديدة، استدعِ الـ API، أضف الرد واكتب القائمة مرة أخرى.
قرّر مبكراً من يملك موجّه النظام. احتفظ به في الكود أو التكوين الخاص بك، وليس في القائمة المخزنة التي يمكن للمتصفح التأثير عليها. إذا كانت الشخصية مخزنة مع السجل، يمكن للمستخدم محاولة تجاوزها عن طريق صياغة طلب. أعد بناء مصفوفة الرسائل على الخادم في كل مرة: رسالة النظام من التكوين، تليها الأدوار المخزنة.
اضبط أيضاً حداً لكل مستخدم. أداة دردشة عامة بدون حدود يدعو إلى الإساءة المبرمجة، وكل رمز يُحاسب عليك. عداد لكل مستخدم لكل ساعة، يُفحص قبل استدعاء الـ API، يكفي للبدء. ادمجه مع حد أعلى لطول الرسالة بحيث لا يمكن لطلب واحد إرسال ميجابايت واحد من النص. تقبل الـ 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));يعمل استدعاء الأدوات بنفس حقلي tools و tool_choice اللذين ترسلهما الـ SDK. عندما يُعيد النموذج tool_calls، شغّل الدالة وأرسل المخرجات مرة أخرى كرسالة مع role: "tool" ومع tool_call_id المطابق. في اللعبة، هذا مفيد لرمي النرد، أو استعلامات المخزون، أو استعلام ما تتذكره الشخصية عن اللاعب. عند البث المتدفق، تصل استدعاءات الأدوات كقطع جزئية يجب دمجها قبل تحليل الحجج.
الاستضافة، الحدود والتكلفة
يضيف البث المتدفق تفاصيل نشر قليلة لا توجد في المسارات التي تعتمد على JSON العادي. بعض منصات الاستضافة والوكلاء يخزّنون الاستجابات مؤقتاً أو يحدون من مدة بقاء الطلب مفتوحاً. إذا وصلت الرموز في كتلة واحدة في النهاية بدلاً من واحدة تلو الأخرى، فإن طبقة تخزين مؤقت تقع بين خادمك والمتصفح. تحقق من وثائق منصتك للخيار الذي يعطل التخزين المؤقت لمسار معين، وأي حد زمني لتنفيذ الدوال، لأن رد لعب الأدوار الطويل قد يستغرق عدة ثوانٍ.
بالنسبة لوكيل عكسي مثل nginx، فإن تخزين الاستجابة المؤقت هو سبب شائع وله إعداد لإيقافه لكل موقع. بالنسبة للدوال الخالية من الخادم، ابحث عن وضع استجابة البث المتدفق في وثائق المنصة. إذا لم يكن مضيفك قادراً على البث المتدفق، فإن عملية Node صغيرة دائمة التشغيل على خادم رخيص هي بديل موثوق.
أخيراً، ضع السر في مخزن متغيرات البيئة للمضيف واحتفظ به خارج مخرجات البناء. غالباً ما تقوم أدوات بناء الواجهة الأمامية بتضمين أي متغير يحمل بادئة عامة في حزمة المتصفح، لذا استخدم اسماً بدون تلك البادئة، واقرأه فقط في كود الخادم. فحص سريع هو البحث في ملفاتك المبنية عن الأحرف الأولى من المفتاح.
الحدود، إعادة المحاولة والتكلفة
المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 في الدقيقة. يسمح مفتاح التجربة بـ 2 و60. تجاوز الحد يجيب الـ API بـ HTTP 429 والرمز rate_limited أو concurrency. الحمل الزائد المؤقت هو أيضاً 429 ويتضمن Retry-After: 5. في JavaScript، ترمي الـ SDK خطأً مع status === 429؛ التقطه، انتظر، وحاول مرة أخرى. الـ SDK يعيد المحاولة أيضاً بضع مرات افتراضياً، وهو ما يمكنك ضبطه مع خيار maxRetries على العميل.
من السهل تقدير التكلفة لكل دور. محادثة تحتوي على 2,000 رمز إدخال و250 رمز إخراج تكلف 2,000 × $0.15 / 1,000,000 = $0.0003 للإدخال و250 × $0.50 / 1,000,000 = $0.000125 للإخراج، أي $0.000425. ألف دور تساوي $0.425. الطلبات الفاشلة أو المرفوضة لا تُحسب تكلفتها. انظر صفحة التسعير لشحن الرصيد من $20 إلى $500 وطبقات المكافآت، والوثائق لقائمة المعاملات الكاملة.