API Character AI w JS: konfiguracja Node i aplikacji webowej
Konfiguracja API Character AI w JS sprowadza się do oficjalnego pakietu npm openai, bazowego URL i trasy serwerowej, która trzyma Twój klucz z dala od przeglądarki. Ta strona pokazuje kod Node, endpoint Express ze strumieniowaniem i fetch po stronie front-endu, który do niego pasuje.
Zaktualizowano

Kluczowe punkty
- Pakiet npm openai działa od razu: zmień baseURL, apiKey i model na
uncensored. - Nigdy nie wysyłaj klucza w kodzie przeglądarki. Zamiast tego wywołaj małą trasę serwerową.
- Strumieniowanie używa zdarzeń wysłanych przez serwer (SSE), a jedno otwarte strumieniowanie zajmuje jedno miejsce w limicie współbieżności.
- Zwykłe fetch też działa, jeśli wolisz brak zależności.
Krótka wersja
Możesz sięgać do endpointu z JavaScript na trzy sposoby: pakiet npm openai, zwykły fetch lub dowolna biblioteka obsługująca format czatu OpenAI. Base URL to https://api.characteraiapi.com/v1, ID modelu to uncensored, a każde zapytanie zawiera Authorization: Bearer <key>. Jeśli nie masz jeszcze klucza, strona klucza API wyjaśnia rejestrację i próbę za $0,50 aktywowaną jednym kliknięciem.
To niezależna usługa, nie produkt Character.ai. Uruchamia jeden model o otwartych wagach, dostrojony do odpowiadania bez odmów treści do zgodnego z prawem użytku przez dorosłych, i nie generuje obrazów, audio ani wideo. Dla aplikacji z postacią to wystarczy: piszesz osobowość, przechowujesz rozmowę i decydujesz, jak wygląda.
Node z pakietem openai
Stwórz projekt, zainstaluj pakiet i użyj modułów ES. Przykłady zakładają Node 18 lub nowszy.
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"Pierwszy skrypt w 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);Uruchom go poleceniem node chat.js. Obiekt usage pokazuje, ile tokenów promptu i completion użyło wywołanie, co możesz pomnożyć przez $0,15 i $0,50 za milion, aby zobaczyć dokładną cenę.
Nigdy nie umieszczaj klucza w kodzie przeglądarki
Pokusą jest wklejenie klucza do komponentu React i wywołanie API ze strony. Nie rób tego. Każdy odwiedzający może otworzyć kartę sieciową lub źródło spakowanego pliku i je skopiować, a następnie wydać Twoje saldo. Rozwiązaniem jest cienkie proxy na serwerze, który kontrolujesz. Przeglądarka wysyła wiadomość użytkownika do Twojej trasy; Twoja trasa buduje pełną listę wiadomości, dodaje klucz i przekazuje wywołanie.
Daje to też miejsce na wymuszenie rzeczy, których API nie zna: osobowości, której użytkownik nie może nadpisać, limitu wiadomości na użytkownika i przycinania długich historii. Przeglądarka powinna wysyłać tylko nowy tekst użytkownika i ID konwersacji, a nie prompt systemowy.
Endpoint Express ze strumieniowaniem
Oto mały serwer z jedną trasą. Trzyma sesje w pamięci dla demonstracji; użyj bazy danych dla czegokolwiek produkcyjnego.
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 zachowuje wiadomość systemową plus ostatnie 20 wiadomości. Starsze tury odpadają, co utrzymuje koszty na stałym poziomie. Wysyłanie tylko czystego tekstu każdego fragmentu upraszcza stronę przeglądarki. Jeśli chcesz bogatsze zdarzenia, wyślij zdarzenia wysyłane przez serwer i parsuj je po stronie klienta.
Zdarzenia wysłane przez serwer dla bogatszego strumieniowania
Wysyłanie surowego tekstu działa dla demonstracji, ale prawdziwe interfejsy czatu zwykle potrzebują więcej niż tekstu: sygnału, gdy odpowiedź jest kompletna, komunikatu o błędzie w środku strumienia lub użycia tokenów na końcu. Zdarzenia wysłane przez serwer dają Ci nazwane wiadomości przez to samo połączenie HTTP. Twoja trasa pisze linie w formacie SSE, a przeglądarka odczytuje je małym parserem.
// 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();Kodowanie każdego tokena jako JSON unika klasycznego błędu: token zawierający znak nowej linii złamałby ramkowanie SSE. Po stronie klienta odczytaj ciało odpowiedzi, podziel go po pustej linii, usuń prefiks data: i sparsuj JSON. Komunikat done informuje interfejs, aby włączyć ponownie pole wprowadzania i przycisk wysyłania.
Obsłuż rozłączenia. Gdy użytkownik zamknie kartę, obiekt odpowiedzi na serwerze emituje zdarzenie close. Nasłuchuj go i przerwij zapytanie do upstreamu, w przeciwnym razie twój serwer będzie ciągle pobierał tokeny, których nikt nie czyta, a strumień będzie zajmował jedno z miejsc w limicie współbieżności. SDK OpenAI akceptuje AbortSignal w opcjach żądania dla tego celu.
Strona przeglądarki
Front-end wywołuje Twoją trasę, a nie host API. Odczytanie strumieniowanej odpowiedzi za pomocą fetch zajmuje kilka linii:
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; });Wyłącz przycisk wysyłania, gdy odpowiedź jest strumieniowana. Zapobiega to podwójnym wysyłkom i respektuje limit współbieżności, ponieważ strumieniowane zapytanie zajmuje swoje miejsce, aż się skończy.
Prawidłowo przechowuj sesje
Mapa w pamięci traci wszystko przy restarcie procesu i łamie się, gdy uruchomisz dwie instancje serwera. Przenieś sesje do bazy danych lub magazynu klucz-wartość, gdy tylko prototyp zadziała. Przechowuj listę wiadomości jako kolumnę JSON, kluczowaną przez użytkownika i postać. Gdy przyjdzie zapytanie, załaduj listę, dołącz nową wiadomość użytkownika, wywołaj API, dołącz odpowiedź i zapisz listę z powrotem.
Zdecyduj wcześnie, kto jest właścicielem promptu systemowego. Trzymaj go w swoim kodzie lub konfiguracji, nie w przechowywanej liście, na którą przeglądarka może wpływać. Jeśli osobowość jest przechowywana z historią, użytkownik mógłby spróbować ją nadpisać, tworząc zapytanie. Odbuduj tablicę wiadomości na serwerze za każdym razem: wiadomość systemowa z konfiguracji, za nią zapisane tury.
Ustaw też limit na użytkownika. Publiczny widżet czatu bez limitów zaprasza do zautomatyzowanego nadużywania, a każdy token jest rozliczany do Ciebie. Licznik na użytkownika na godzinę, sprawdzany przed wywołaniem API, wystarczy na początek. Połącz go z górnym limitem długości wiadomości, aby jedno zapytanie nie mogło wysłać megabajta tekstu. API akceptuje ciała do 8 MB, ale Twój własny limit powinien być znacznie niższy, np. 4000 znaków na wiadomość użytkownika.
Zwykłe fetch, narzędzia i tryb JSON
Jeśli nie chcesz zależności, surowe wywołanie działa tak samo. Uruchom to z serwera, workera lub skryptu, nie z kodu publicznej strony.
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));Wywoływanie funkcji działa z tymi samymi polami tools i tool_choice, które wysyła SDK. Gdy model zwraca tool_calls, uruchom funkcję i wyślij wynik z powrotem jako wiadomość z role: "tool" i pasującym tool_call_id. W grze jest to przydatne do rzutów kostką, wyszukiwania w ekwipunku lub sprawdzenia, co postać pamięta o graczu. Podczas strumieniowania wywołania funkcji przychodzą jako fragmenty, które musisz połączyć przed sparsowaniem argumentów.
Hosting, limity i koszt
Strumieniowanie dodaje kilka szczegółów wdrożenia, których zwykłe trasy JSON nie mają. Niektóre platformy hostingu i proxy buforują odpowiedzi lub ograniczają, jak długo zapytanie może pozostać otwarte. Jeśli tokeny przychodzą jednym kawałkiem na końcu zamiast jeden po drugim, warstwa buforowania znajduje się między Twoim serwerem a przeglądarką. Sprawdź dokumentację swojej platformy dla opcji wyłączającej buforowanie dla trasy i dla dowolnego limitu czasu wykonania funkcji, ponieważ długa odpowiedź roleplay może trwać wiele sekund.
Dla proxy odwrotnego takiego jak nginx, buforowanie odpowiedzi jest częstą przyczyną i ma ustawienie do wyłączania na poziomie lokalizacji. Dla funkcji serverless szukaj trybu odpowiedzi strumieniowej w dokumentacji platformy. Jeśli Twój host nie może strumieniować, mały zawsze działający proces Node na tanim serwerze jest niezawodnym fallbackiem.
Na końcu umieść sekret w magazynie zmiennych środowiskowych hosta i trzymaj go z dala od wyniku buildu. Narzędzia buildu front-endu często wstawiają do pakietu przeglądarki każdą zmienną z publicznym prefiksem, więc użyj nazwy bez tego prefiksu i odczytuj ją tylko w kodzie serwera. Szybki check to wyszukanie w zbudowanych plikach pierwszych kilku znaków klucza.
Limity, ponowne próby i koszt
Pełny klucz pozwala na 8 równoległych zapytań i 300 na minutę. Klucz próbny pozwala na 2 i 60. Przekroczenie limitu powoduje odpowiedź API z HTTP 429 i kodem rate_limited lub concurrency. Tymczasowe przeciążenie to również 429 i zawiera Retry-After: 5. W JavaScript SDK rzuca błąd z status === 429; złap go, poczekaj i spróbuj ponownie. SDK również ponawia kilka razy domyślnie, co możesz dostosować opcją maxRetries po stronie klienta.
Koszt na turę łatwo oszacować. Czat z 2000 tokenami wejściowymi i 250 tokenami wyjściowymi kosztuje 2000 x $0,15 / 1 000 000 = $0,0003 za wejście i 250 x $0,50 / 1 000 000 = $0,000125 za wyjście, czyli $0,000425. Tysiąc tur to $0,425. Nieudane lub odrzucone zapytania nie są rozliczane. Zobacz stronę z cenami, aby doładować kredyty od $20 do $500 i poznać bonusowe poziomy, oraz dokumentację dla pełnej listy parametrów.