Character AI API in JS: Node- und Web-App-Einrichtung
Eine Character-AI-API-JS-Einrichtung reduziert sich auf das offizielle openai-npm-Paket, eine Base URL und eine Serverroute, die deinen Schlüssel aus dem Browser fernhält. Diese Seite zeigt den Node-Code, einen Streaming-Express-Endpunkt und das dazugehörige Frontend-Fetch.
Aktualisiert

Wichtige Punkte
- Das openai-npm-Paket funktioniert wie es ist: Ändere baseURL, apiKey und das Modell zu
uncensored. - Gib den Schlüssel niemals in Browser-Code ein. Rufe stattdessen eine kleine Serverroute auf.
- Streaming nutzt Server-Sent Events, und ein offener Stream belegt einen Concurrency-Slot.
- Einfaches fetch funktioniert ebenfalls, wenn du keine Abhängigkeit bevorzugst.
Die Kurzversion
Du kannst den Endpunkt auf drei Wegen aus JavaScript heraus erreichen: über das openai-npm-Paket, plain fetch oder jede Bibliothek, die bereits das OpenAI-Chat-Format spricht. Die Base URL ist https://api.characteraiapi.com/v1, die Modell-ID ist uncensored, und jede Anfrage enthält Authorization: Bearer <key>. Falls du noch keinen API-Schlüssel hast, erklärt die API-Schlüssel-Seite die Anmeldung und das kostenfreie Testguthaben von $0,50.
Dies ist ein unabhängiger Dienst, nicht das Character.ai-Produkt. Es läuft ein Open-Weight-Modell, das darauf abgestimmt ist, ohne Inhaltsablehnungen für die rechtmäßige Nutzung durch Erwachsene zu antworten, und es generiert keine Bilder, Audio oder Video. Für eine Charakter-App reicht das: Du schreibst die Persona, speicherst die Konversation und entscheidest, wie sie aussieht.
Node mit dem openai-Paket
Erstelle ein Projekt, installiere das Paket und verwende ES-Module. Die Beispiele setzen Node 18 oder neuer voraus.
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"Ein erstes Skript in 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);Führe es mit node chat.js aus. Das usage-Objekt zeigt dir, wie viele Prompt- und Completion-Token der Aufruf verwendet hat, was du mit $0,15 und $0,50 pro Million multiplizieren kannst, um den genauen Preis zu sehen.
Gib den Schlüssel niemals in Browser-Code ein
Es ist verlockend, den Schlüssel in eine React-Komponente einzufügen und die API von der Seite aus aufzurufen. Tu das nicht. Jeder Besucher kann den Netzwerk-Tab oder den gebündelten Quellcode öffnen und ihn kopieren, und dann dein Guthaben ausgeben. Die Lösung ist ein dünner Proxy auf einem Server, den du kontrollierst. Der Browser sendet die Nachricht des Benutzers an deine Route; deine Route erstellt die vollständige Nachrichtenliste, fügt den Schlüssel hinzu und leitet den Aufruf weiter.
Dies gibt dir auch einen Ort, um Dinge durchzusetzen, die die API nicht kennt: eine Persona, die Benutzer nicht überschreiben können, ein pro Benutzer begrenztes Nachrichtenlimit und das Beschneiden langer Verläufe. Ein Browser sollte immer nur den neuen Benutzertext und eine Konversations-ID senden, nicht den System-Prompt.
Ein Streaming-Express-Endpunkt
Hier ist ein kleiner Server mit einer Route. Er hält Sitzungen im Speicher für die Demo; nutze für echte Anwendungen eine Datenbank.
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);Der Slice hält die Systemnachricht plus die letzten 20 Nachrichten. Alte Nachrichten fallen weg, was die Kosten stabil hält. Das Senden nur des reinen Textes jedes Chunks hält die Browserseite einfach. Wenn du reichere Ereignisse möchtest, sende Server-Sent Events und parse sie auf dem Client.
Server-Sent Events für reicheres Streaming
Rohtext zu senden funktioniert für eine Demo, aber echte Chat-Schnittstellen benötigen meist mehr als Text: ein Signal, wenn die Antwort abgeschlossen ist, eine Fehlermeldung mitten im Stream oder die Token-Nutzung am Ende. Server-Sent Events geben dir benannte Nachrichten über dieselbe HTTP-Verbindung. Deine Route schreibt Zeilen im SSE-Format, und der Browser liest sie mit einem kleinen Parser.
// 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();Die Kodierung jedes Tokens als JSON vermeidet einen klassischen Fehler: Ein Token, das einen Zeilenumbruch enthält, würde sonst die SSE-Rahmenstruktur zerstören. Lies auf dem Client den Antwortkörper, teile an einer Leerzeile, entferne das data: -Präfix und parse das JSON. Die done-Nachricht weist die Schnittstelle an, das Eingabefeld wieder zu aktivieren und die Senden-Schaltfläche zu reaktivieren.
Behandle Verbindungsabbrüche. Wenn der Benutzer den Tab schließt, emittiert das Response-Objekt auf dem Server ein close-Ereignis. Höre darauf und breche die Upstream-Anfrage ab, sonst zieht dein Server weiter Token ab, die niemand liest, und der Stream belegt einen deiner Concurrency-Slots. Das OpenAI SDK akzeptiert ein AbortSignal in den Anfrageoptionen zu diesem Zweck.
Die Browserseite
Das Frontend ruft deine eigene Route auf, niemals den API-Host. Das Lesen einer gestreamten Antwort mit fetch benötigt wenige Zeilen:
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; });Deaktiviere die Senden-Schaltfläche, während eine Antwort gestreamt wird. Dies verhindert doppelte Übermittlungen und respektiert das Concurrency-Limit, da eine gestreamte Anfrage ihren Slot bis zum Ende belegt.
Speichere Sitzungen ordnungsgemäß
Eine im Arbeitsspeicher gespeicherte Map verliert bei einem Neustart des Prozesses alle Daten und bricht zusammen, sobald du zwei Server-Instanzen ausführst. Verschiebe die Sessions in eine Datenbank oder ein Key-Value-Store, sobald der Prototyp funktioniert. Speichere die Nachrichtenliste als JSON-Spalte, gruppiert nach Benutzer und Charakter. Wenn eine Anfrage eingeht, lade die Liste, hänge die neue Nachricht des Benutzers an, rufe die API auf, hänge die Antwort an und schreibe die Liste zurück.
Entscheide früh, wem der System-Prompt gehört. Halte ihn in deinem Code oder deiner Konfiguration, nicht in der gespeicherten Liste, die der Browser beeinflussen kann. Wenn die Persona mit dem Verlauf gespeichert wird, könnte ein Benutzer versuchen, sie zu überschreiben, indem er eine Anfrage erstellt. Baue das Nachrichtenarray auf dem Server jedes Mal neu auf: die Systemnachricht aus der Konfiguration, gefolgt von den gespeicherten Nachrichten.
Setze auch ein pro Benutzer begrenztes Limit. Ein öffentliches Chat-Widget ohne Limits lädt zu skriptbasiertem Missbrauch ein, und jedes Token wird dir berechnet. Ein Zähler pro Benutzer pro Stunde, geprüft vor dem API-Aufruf, reicht zum Starten. Kombiniere es mit einer Obergrenze für die Nachrichtengröße, damit eine Anfrage nicht ein Megabyte Text senden kann. Die API akzeptiert Körper bis zu 8 MB, aber dein eigenes Limit sollte weit niedriger sein, z. B. 4.000 Zeichen pro Benutzernachricht.
Einfaches Fetch, Tools und JSON-Modus
Wenn du keine Abhängigkeit möchtest, funktioniert eine rohe Anfrage auf dieselbe Weise. Führe dies auf einem Server, einem Worker oder einem Skript aus, nicht in öffentlichem Seiten-Code.
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));Tool Calling funktioniert mit denselben tools- und tool_choice-Feldern, die das SDK sendet. Wenn das Modell tool_calls zurückgibt, führe die Funktion aus und sende die Ausgabe als Nachricht mit role: "tool" und der passenden tool_call_id zurück. In einem Spiel ist dies nützlich für Würfelwürfe, Inventarabfragen oder eine Suche nach dem, was der Charakter über den Spieler weiß. Beim Streaming kommen Tool-Aufrufe als teilweise Fragmente an, die du vor dem Parsen der Argumente zusammenfügen musst.
Hosting, Limits und Kosten
Streaming fügt einige Bereitstellungsdetails hinzu, die reine JSON-Routen nicht haben. Einige Hosting-Plattformen und Proxies puffern Antworten oder begrenzen, wie lange eine Anfrage offen bleiben darf. Wenn Token am Ende in einem Block statt einzeln ankommen, sitzt eine Pufferschicht zwischen deinem Server und dem Browser. Prüfe die Dokumentation deiner Plattform für die Option, die das Buffern für eine Route deaktiviert, und für jede Zeitschranke für die Funktionsausführung, da eine lange Rollenspiel-Antwort viele Sekunden dauern kann.
Für einen Reverse-Proxy wie nginx ist Antwort-Puffern ein häufiger Übeltäter und hat eine Einstellung zum Ausschalten pro Location. Für serverless Funktionen suche nach einem Streaming-Antwortmodus in der Plattformdokumentation. Wenn dein Host nicht streamen kann, ist ein kleiner Always-On-Node-Prozess auf einem günstigen Server ein zuverlässiger Fallback.
Lege das Geheimnis schließlich im Umgebungsvariablen-Speicher des Hosts ab und halte es aus der Build-Ausgabe. Frontend-Build-Tools inline oft jede Variable, die ein öffentliches Präfix trägt, in das Browser-Bundle, also verwende einen Namen ohne dieses Präfix und lies ihn nur im Server-Code. Ein schneller Check ist, deine gebauten Dateien nach den ersten wenigen Zeichen des Schlüssels zu durchsuchen.
Limits, Wiederholungen und Kosten
Ein vollständiger Schlüssel erlaubt 8 gleichzeitige Anfragen und 300 pro Minute. Ein Test-Schlüssel erlaubt 2 und 60. Über einem Limit antwortet die API mit HTTP 429 und dem Code rate_limited oder concurrency. Eine temporäre Überlastung ist ebenfalls eine 429 und enthält Retry-After: 5. In JavaScript wirft das SDK einen Fehler mit status === 429; fange ihn ab, warte und versuche es erneut. Das SDK wiederholt auch standardmäßig ein paar Male, was du mit der maxRetries-Option auf dem Client anpassen kannst.
Die Kosten pro Durchlauf lassen sich leicht abschätzen. Ein Chat mit 2.000 Input-Token und 250 Output-Token kostet 2.000 × $0,15 / 1.000.000 = $0,0003 für Input und 250 × $0,50 / 1.000.000 = $0,000125 für Output, also $0,000425. Tausend Durchläufe kosten $0,425. Fehlgeschlagene oder abgelehnte Anfragen werden nicht berechnet. Sieh dir die Preisliste für Aufladungen von $20 bis $500 und die Bonusstufen an, und die Dokumentation für die vollständige Parameterliste.