Character AI API in JS: Node en webapp instellen
Een character ai api js-setup komt neer op het officiële openai npm-pakket, een base URL en een serverroute die je sleutel buiten de browser houdt. Deze pagina toont de Node-code, een streaming Express-endpoint en de bijbehorende front-end fetch.
Bijgewerkt

Belangrijkste punten
- Het openai npm-pakket werkt direct: pas baseURL, apiKey en het model aan naar
uncensored. - Plaats de sleutel nooit in browsercode. Roep in plaats daarvan een klein serverendpoint aan.
- Streaming gebruikt server-sent events, en één open stream gebruikt één concurrency slot.
- Gewone fetch werkt ook als je geen afhankelijkheid wilt.
De korte versie
Je kunt het endpoint op drie manieren bereiken vanuit JavaScript: via het openai npm-pakket, met gewone fetch, of met elke bibliotheek die het OpenAI-chatformaat al ondersteunt. De base URL is https://api.characteraiapi.com/v1, de model-ID is uncensored en elk verzoek bevat Authorization: Bearer <key>. Heb je nog geen sleutel? De API-sleutel-pagina legt de registratie uit en biedt $0,50 proeftegoed.
Dit is een onafhankelijke dienst, geen product van Character.ai. Het draait één open-weight model dat is afgestemd op antwoorden zonder inhoudelijke weigeringen voor legaal gebruik door volwassenen, en het genereert geen afbeeldingen, audio of video. Voor een character-app is dat genoeg: jij schrijft het persona, slaat het gesprek op en bepaalt hoe het eruitziet.
Node met het openai-pakket
Maak een project, installeer het pakket en gebruik ES-modules. De voorbeelden gaan uit van Node 18 of nieuwer.
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"Een eerste script 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);Voer het uit met node chat.js. Het usage-object laat zien hoeveel prompt- en completion-tokens de call heeft gebruikt. Vermenigvuldig dit met $0,15 en $0,50 per miljoen om de exacte prijs te berekenen.
Plaats de sleutel nooit in browsercode
Het is verleidelijk om de sleutel in een React-component te plakken en de API vanaf de pagina aan te roepen. Doe dat niet. Elke bezoeker kan het netwerktabblad of de gebundelde bron openen en de sleutel kopiëren, waardoor je tegoed wordt leeggehaald. De oplossing is een dunne proxy op een server die jij beheert. De browser stuurt de boodschap van de gebruiker naar jouw route; jouw route bouwt de volledige lijst met berichten, voegt de sleutel toe en stuurt het verzoek door.
Dit geeft je ook een plek om dingen af te dwingen die de API niet kent: een persona die gebruikers niet kunnen overschrijven, een per-gebruiker berichtlimiet, en het inkorten van lange geschiedenissen. Een browser moet alleen de nieuwe tekst van de gebruiker en een gesprek-ID sturen, niet het systeemprompt.
Een streaming Express-endpoint
Hier is een kleine server met één route. Voor de demo slaan we sessies op in het geheugen; gebruik een database voor productie.
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);De slice houdt het systeembericht plus de laatste 20 berichten bij. Oudere wisselingen vallen eraf, wat de kosten stabiel houdt. Alleen de platte tekst van elke chunk versturen houdt de browserkant eenvoudig. Als je rijkere gebeurtenissen wilt, verstuur dan server-sent events en parse ze aan de clientkant.
Server-sent events voor rijkere streaming
Platte tekst versturen werkt voor een demo, maar echte chatinterfaces hebben meestal meer nodig dan tekst: een signaal als het antwoord compleet is, een foutmelding in het midden van een stream, of het tokengebruik aan het einde. Server-sent events geven je benoemde berichten over dezelfde HTTP-verbinding. Je route schrijft regels in het SSE-formaat, en de browser leest ze met een kleine 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();Elke token coderen als JSON voorkomt een klassieke bug: een token met een regeleinde zou de SSE-framing breken. Lees op de client het antwoordlichaam, split op een lege regel, verwijder het data: -voorvoegsel en parse de JSON. Het done-bericht zorgt ervoor dat de interface het invoervak weer activeert en de verzendknop weer inschakelt.
Verbinding verbreken afhandelen. Als de gebruiker het tabblad sluit, genereert het response-object op de server een close-gebeurtenis. Luister ernaar en onderbreek het upstream-verzoek, anders blijft je server tokens ophalen die niemand leest, en blijft een van je concurrency-slots bezet. De OpenAI SDK accepteert een AbortSignal in de request-opties voor dit doel.
De browserkant
De front-end roept jouw eigen route aan, nooit de API-host. Een gestreamde respons lezen met fetch kost een paar regels:
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; });Schakel de verzendknop uit terwijl een antwoord wordt gestreamd. Dit voorkomt dubbele inzendingen en respecteert de concurrency-limiet, omdat een gestreamd verzoek zijn slot bezet tot het einde.
Sessies correct opslaan
Een in-memory map verliest alles bij een procesherstart en breekt zodra je twee serverinstanties draait. Zet sessies om naar een database of key-value store zodra het prototype werkt. Sla de berichtlijst op als JSON-kolom, gesleuteld per gebruiker en karakter. Bij een binnenkomend verzoek laad je de lijst, voeg je de nieuwe gebruikersboodschap toe, roep je de API aan, voeg je het antwoord toe en schrijf je de lijst terug.
Bepaal vroeg wie eigenaar is van het systeemprompt. Houd het in je code of configuratie, niet in de opgeslagen lijst die de browser kan beïnvloeden. Als het persona met de geschiedenis wordt opgeslagen, kan een gebruiker proberen het te overschrijven door een verzoek te vervalsen. Bouw de berichtenarray op de server elke keer opnieuw op: het systeembericht uit de configuratie, gevolgd door de opgeslagen beurten.
Stel ook een per-gebruiker limiet in. Een publieke chatwidget zonder limieten nodigt uit tot scriptmatig misbruik, en elke token wordt aan jou verrekend. Een teller per gebruiker per uur, gecontroleerd voor het API-verzoek, is genoeg om te beginnen. Combineer dit met een bovengrens voor berichtlengte zodat één verzoek niet een megabyte tekst kan sturen. De API accepteert bodies tot 8 MB, maar je eigen limiet moet veel lager zijn, zoals 4.000 tekens per gebruikersbericht.
Gewone fetch, tools en JSON-modus
Als je geen afhankelijkheid wilt, werkt een rauw verzoek op dezelfde manier. Voer dit uit vanaf een server, een worker of een script, niet vanuit publieke pagina-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 werkt met dezelfde tools en tool_choice velden die de SDK verstuurt. Als het model tool_calls teruggeeft, voer je de functie uit en stuur je de output terug als bericht met role: "tool" en de bijpassende tool_call_id. In een spel is dit nuttig voor dobbelsteenworpen, inventarisopzoeken of het opzoeken van wat het karakter zich herinnert van de speler. Bij streaming komen tool calls als gedeeltelijke fragmenten binnen die je moet samenvoegen voordat je de argumenten parset.
Hosting, limieten en kosten
Streaming voegt enkele deploymentdetails toe die gewone JSON-routes niet hebben. Sommige hostingplatforms en proxies bufferen responsen of beperken hoe lang een verzoek open mag blijven. Als tokens in één keer aan het einde aankomen in plaats van één voor één, zit er een bufferinglaag tussen je server en de browser. Controleer de documentatie van je platform voor de optie die buffering voor een route uitschakelt, en voor eventuele tijdslimieten op functie-uitvoering, omdat een lang rollenspel-antwoord vele seconden kan duren.
Voor een reverse proxy zoals nginx is response buffering een veelvoorkomende boosdoener en heeft het een instelling om dit per locatie uit te schakelen. Voor serverless functies, zoek naar een streaming response-modus in de platformdocs. Als je host niet kan streamen, is een klein always-on Node-proces op een goedkope server een betrouwbaar alternatief.
Zet de secret tenslotte in de environment variable store van de host en houd het buiten de build-output. Front-end buildtools inline vaak elke variabele met een public prefix in de browserbundle, dus gebruik een naam zonder die prefix en lees hem alleen in servercode. Een snelle check is je gebouwde bestanden doorzoeken op de eerste paar tekens van de sleutel.
Limieten, retries en kosten
Een volledige sleutel staat 8 gelijktijdige verzoeken en 300 per minuut toe. Een proefsleutel staat 2 en 60 toe. Bij overschrijding van een limiet antwoordt de API met HTTP 429 en de code rate_limited of concurrency. Een tijdelijke overbelasting is ook een 429 en bevat Retry-After: 5. In JavaScript gooit de SDK een fout met status === 429; vang het, wacht en probeer het opnieuw. De SDK probeert ook standaard een paar keer opnieuw, wat je kunt afstellen met de maxRetries-optie op de client.
De kosten per beurt zijn eenvoudig te schatten. Een chat met 2.000 input-tokens en 250 output-tokens kost 2.000 x $0,15 / 1.000.000 = $0,0003 voor input en 250 x $0,50 / 1.000.000 = $0,000125 voor output, dus $0,000425. Duizend beurten zijn $0,425. Mislukte of geweigerde verzoeken worden niet in rekening gebracht. Zie de prijslijst voor opwaarderingen van $20 tot $500 en de bonusniveaus, en de documentatie voor de volledige parameterlijst.