DE ▾
API-Schlüssel erhalten

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.

Browser-Panel, verbunden durch eine leuchtende Leitung mit einem Server-Würfel, der Chat-Blasen trägt, zeigt ein JS-Proxy-Design

Wichtige Punkte

  1. Das openai-npm-Paket funktioniert wie es ist: Ändere baseURL, apiKey und das Modell zu uncensored.
  2. Gib den Schlüssel niemals in Browser-Code ein. Rufe stattdessen eine kleine Serverroute auf.
  3. Streaming nutzt Server-Sent Events, und ein offener Stream belegt einen Concurrency-Slot.
  4. 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.

Fragen und Antworten

Kann ich die API direkt aus einer React- oder Vue-App aufrufen?

Technisch ja, aber der Schlüssel wäre für jeden Besucher sichtbar. Nutze eine kleine Serverroute, die den Schlüssel hinzufügt und die Anfrage weiterleitet.

Welches npm-Paket soll ich verwenden?

Das offizielle openai-Paket funktioniert. Setze baseURL auf den Endpunkt, verwende deinen Schlüssel als apiKey und das Modell uncensored. Einfaches fetch ist ebenfalls in Ordnung.

Läuft es auf Deno, Bun oder Cloudflare Workers?

Jede Laufzeit, die eine HTTPS-Anfrage mit einem Bearer-Header stellen kann, kann sie aufrufen. Das openai-Paket unterstützt mehrere Laufzeiten, also prüfe die Dokumentation für deine.

Wie kann ich Token auf die Seite streamen?

Stelle auf dem Server stream: true ein, leite jeden Chunk an den Browser weiter und lies ihn mit einem Fetch-Reader. Jeder offene Stream belegt einen Concurrency-Slot.

Ist dies die offizielle API von Character.ai?

Nein. Es ist ein unabhängiger OpenAI-kompatibler Dienst mit einem eigenen Schlüssel und einem Modell, der als Backend für deine eigenen Character-Apps angeboten wird.

Dein Schlüssel ist nur ein Formular entfernt

Erstelle ein Konto, kopiere den Schlüssel, ändere die Base URL. Das ist die gesamte Einrichtung.

API-Schlüssel erhalten