API Character AI на JS: настройка Node и веб-приложения
Настройка API Character AI на JS сводится к официальному npm-пакету openai, базовому URL и маршруту сервера, который скрывает ваш API-ключ от браузера. На этой странице показан код Node.js, потоковый эндпоинт Express и соответствующий ему fetch на стороне клиента.
Обновлено

Ключевые моменты
- Пакет npm openai работает как есть: измените baseURL, apiKey и модель на
uncensored. - Никогда не отправляйте ключ в код браузера. Вместо этого вызовите небольшой маршрут сервера.
- Потоковая передача использует серверные события (SSE), и один открытый поток занимает один слот параллельных запросов.
- Обычный fetch также работает, если вы предпочитаете отсутствие зависимостей.
Краткая версия
Вы можете обратиться к эндпоинту из JavaScript тремя способами: с помощью npm-пакета openai, обычного fetch или любой библиотеки, которая уже поддерживает формат чата OpenAI. Базовый URL — https://api.characteraiapi.com/v1, идентификатор модели — 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 показывает, сколько промпт- и completion-токенов использовал вызов, что вы можете умножить на $0,15 и $0,50 за миллион, чтобы увидеть точную цену.
Никогда не помещайте ключ в код браузера
Соблазнительно вставить ключ в компонент 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), и разбирайте их на клиенте.
Серверные события для более богатой потоковой передачи
Отправка простого текста подходит для демонстрации, но реальным интерфейсам чата обычно нужно больше, чем текст: сигнал о завершении ответа, сообщение об ошибке в середине потока или использование токенов в конце. События, отправляемые сервером, дают вам именованные сообщения по тому же 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. Сообщение о завершении сообщает интерфейсу снова активировать поле ввода и кнопку отправки.
Обработка разрывов соединения. Когда пользователь закрывает вкладку, объект ответа на сервере генерирует событие close. Подписывайтесь на него и прерывайте исходящий запрос, иначе ваш сервер продолжит получать токены, которые никто не читает, и один из слотов параллельных запросов будет занят. SDK 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; });Отключите кнопку отправки, пока ответ находится в потоке. Это предотвращает двойную отправку и соблюдает лимит параллельных запросов, поскольку потоковый запрос занимает свой слот до самого конца.
Правильно храните сессии
Карта в памяти теряет все при перезапуске процесса и ломается, как только вы запустите два экземпляра сервера. Переместите сессии в базу данных или хранилище ключ-значение, как только прототип заработает. Храните список сообщений как JSON-колонку, с ключом по пользователю и персонажу. Когда поступает запрос, загрузите список, добавьте новое сообщение пользователя, вызовите API, добавьте ответ и запишите список обратно.
Решите заранее, кому принадлежит системный промпт. Храните его в своем коде или конфигурации, а не в сохраненном списке, на который может повлиять браузер. Если персонаж хранится вместе с историей, пользователь может попытаться перезаписать его, создав запрос. Собирайте массив сообщений на сервере каждый раз: системное сообщение из конфигурации, за которым следуют сохраненные реплики.
Также установите лимит на пользователя. Публичный виджет чата без лимитов приглашает к скриптовым злоупотреблениям, и каждый токен оплачивается вам. Счетчик на пользователя в час, проверяемый перед вызовом API, достаточен для начала. Сочетайте его с верхним пределом длины сообщения, чтобы один запрос не мог отправить мегабайт текста. API принимает тела до 8 МБ, но ваш собственный лимит должен быть намного ниже, например, 4 000 символов на сообщение пользователя.
Обычный fetch, инструменты и JSON-режим
Если вам не нужна зависимость, прямой вызов работает так же. Запустите это с сервера, воркера или скрипта, а не из кода публичной страницы.
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 x $0,15 / 1 000 000 = $0,0003 за вход и 250 x $0,50 / 1 000 000 = $0,000125 за выход, так что $0,000425. Тысяча ходов — $0,425. Неудачные или отклоненные запросы не оплачиваются. См. страницу цен для пополнений от $20 до $500 и бонусных уровней, и документацию для полного списка параметров.