API Character AI en JS : configuration Node et application Web
Une configuration API Character AI en JS repose sur le paquet npm openai officiel, une URL de base et un endpoint serveur qui garde votre clé hors du navigateur. Cette page montre le code Node, un endpoint Express en streaming et le fetch front-end associé.
Mis à jour

Points clés
- Le paquet npm openai fonctionne tel quel : modifiez baseURL, apiKey et le modèle vers
uncensored. - Ne livrez jamais la clé dans le code navigateur. Appelez plutôt un endpoint serveur léger.
- Le streaming utilise les événements envoyés par le serveur, et un stream ouvert utilise un slot de concurrence.
- Un fetch brut fonctionne aussi si vous préférez sans dépendance.
Le résumé
Accédez à l'endpoint en JS via le package openai, fetch ou toute lib compatible OpenAI. Base URL : https://api.characteraiapi.com/v1, modèle uncensored, Authorization: Bearer <key>. Sans clé, la page clé API explique l'inscription et l'essai à $0,50.
C'est un service indépendant, pas le produit Character.ai. Il exécute un modèle à poids ouverts ajusté pour répondre sans refus de contenu pour un usage adulte légal, et il ne génère pas d'images, d'audio ou de vidéo. Pour une application de personnage, cela suffit : vous écrivez le persona, stockez la conversation et décidez de son apparence.
Node avec le package openai
Créez un projet, installez le paquet et utilisez les modules ES. Les exemples supposent Node 18 ou plus récent.
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"Un premier script dans 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);Exécutez-le avec node chat.js. L'objet d'utilisation vous indique le nombre de tokens de prompt et de tokens de complétion utilisés par l'appel, que vous pouvez multiplier par 0,15 $ et 0,50 $ par million pour connaître le prix exact.
Ne jamais mettre la clé dans le code navigateur
Il est tentant de coller la clé dans un composant React et d'appeler l'API depuis la page. Ne le faites pas. Chaque visiteur peut ouvrir l'onglet réseau ou le code bundle et la copier, puis dépenser votre solde. La solution est un proxy léger sur un serveur que vous contrôlez. Le navigateur envoie le message de l'utilisateur à votre endpoint ; votre endpoint construit la liste complète des messages, ajoute la clé et transmet la requête.
Cela vous donne aussi un endroit pour imposer des règles que l'API ne connaît pas : un persona que les utilisateurs ne peuvent pas écraser, une limite de messages par utilisateur, et le troncage des historiques trop longs. Un navigateur ne doit envoyer que le nouveau texte utilisateur et un ID de conversation, pas le prompt système.
Un endpoint Express en streaming
Voici un petit serveur avec un seul endpoint. Il garde les sessions en mémoire pour la démo ; utilisez une base de données pour toute application réelle.
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);Le slice garde le message système plus les 20 derniers messages. Les anciens tours tombent, ce qui maintient le coût stable. Envoyer uniquement le texte brut de chaque chunk simplifie le côté navigateur. Si vous voulez des événements plus riches, envoyez des événements envoyés par le serveur et analysez-les côté client.
Événements envoyés par le serveur pour un streaming plus riche
Envoyer du texte brut fonctionne pour une démo, mais les interfaces de chat réelles ont souvent besoin de plus que du texte : un signal quand la réponse est terminée, un message d'erreur au milieu d'un stream, ou l'usage de tokens à la fin. Les événements envoyés par le serveur vous donnent des messages nommés sur la même connexion HTTP. Votre endpoint écrit des lignes au format SSE, et le navigateur les lit avec un petit analyseur.
// 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();Encoder chaque token en JSON évite un bug classique : un token contenant un saut de ligne casserait autrement le cadre SSE. Côté client, lisez le corps de la réponse, divisez sur une ligne vide, supprimez le préfixe data: et analysez le JSON. Le message done indique à l'interface de réactiver le champ de saisie et le bouton d'envoi.
Gérez les déconnexions. À la fermeture de l'onglet, l'objet réponse émet l'événement close. Écoutez-le et annulez la requête amont pour libérer un slot de concurrence. Le SDK OpenAI accepte un AbortSignal dans les options.
Le côté navigateur
Le front appelle votre route, pas l'hôte API. Lire un flux avec fetch prend quelques lignes :
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; });Désactivez le bouton d'envoi pendant qu'une réponse est en streaming. Cela empêche les doubles soumissions et respecte la limite de concurrence, car une requête streamée occupe son slot jusqu'à sa fin.
Gérer correctement les sessions
Une map en mémoire perd tout au redémarrage du processus et casse dès que vous exécutez deux instances de serveur. Déplacez les sessions vers une base de données ou un stockage clé-valeur dès que le prototype fonctionne. Stockez la liste des messages comme une colonne JSON, indexée par utilisateur et personnage. Quand une requête arrive, chargez la liste, ajoutez le nouveau message utilisateur, appelez l'API, ajoutez la réponse et réécrivez la liste.
Décidez tôt qui possède le prompt système. Gardez-le dans votre code ou configuration, pas dans la liste stockée que le navigateur peut influencer. Si le persona est stocké avec l'historique, un utilisateur pourrait essayer de l'écraser en fabriquant une requête. Reconstruisez le tableau de messages sur le serveur à chaque fois : le message système depuis la config, suivi des tours stockés.
Définissez aussi une limite par utilisateur. Un widget de chat public sans limites invite aux abus scriptés, et chaque token vous est facturé. Un compteur par utilisateur par heure, vérifié avant l'appel API, suffit pour commencer. Combinez-le avec une limite supérieure de longueur de message pour qu'une requête ne puisse pas envoyer un mégaoctet de texte. L'API accepte des corps jusqu'à 8 Mo, mais votre propre limite devrait être bien inférieure, comme 4 000 caractères par message utilisateur.
Fetch brut, outils et mode JSON
Si vous ne voulez aucune dépendance, un appel brut fonctionne de la même manière. Exécutez-le depuis un serveur, un worker ou un script, et non depuis du code de page publique.
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));L'appel d'outils utilise les champs tools et tool_choice du SDK. Si le modèle renvoie tool_calls, exécutez la fonction et renvoyez le résultat avec role: "tool" et tool_call_id. Utile pour les jets de dés ou l'inventaire. En streaming, les appels d'outils sont fragmentés et doivent être assemblés avant analyse.
Hébergement, limites et coût
Le streaming ajoute quelques détails de déploiement que les routes JSON brutes n'ont pas. Certaines plateformes d'hébergement et proxies mettent les réponses en mémoire tampon ou limitent la durée d'ouverture d'une requête. Si les tokens arrivent en un bloc à la fin au lieu d'un par un, une couche de mise en tampon se trouve entre votre serveur et le navigateur. Vérifiez la documentation de votre plateforme pour l'option qui désactive la mise en tampon pour un endpoint, et pour toute limite de temps d'exécution de fonction, car une longue réponse de jeu de rôle peut durer plusieurs secondes.
Pour un proxy inverse comme nginx, la mise en tampon des réponses est une cause fréquente et a un paramètre pour la désactiver par emplacement. Pour les fonctions serverless, cherchez un mode de réponse streamée dans la documentation de la plateforme. Si votre hôte ne peut pas streamer, un petit processus Node toujours actif sur un serveur bon marché est un fallback fiable.
Enfin, mettez le secret dans le magasin de variables d'environnement de l'hôte et gardez-le hors des sorties de build. Les outils de build front-end intègrent souvent toute variable ayant un préfixe public dans le bundle navigateur, donc utilisez un nom sans ce préfixe, et lisez-le uniquement dans le code serveur. Une vérification rapide consiste à rechercher dans vos fichiers construits les premiers caractères de la clé.
Limites, tentatives et coût
Une clé payante permet 8 requêtes simultanées et 300 par minute. Une clé d'essai permet 2 et 60. Au-delà d'une limite, l'API répond avec un HTTP 429 et le code rate_limited ou concurrency. Une surcharge temporaire est également un 429 et inclut Retry-After: 5. En JavaScript, le SDK lève une erreur avec status === 429 ; capturez-la, attendez, et réessayez. Le SDK réessaie également quelques fois par défaut, ce que vous pouvez ajuster avec l'option maxRetries sur le client.
Le coût par tour est simple à estimer. 2 000 tokens d'entrée et 250 de sortie coûtent 2 000 x $0,15 / 1 000 000 = $0,0003 en entrée et 250 x $0,50 / 1 000 000 = $0,000125 en sortie, soit $0,000425. Mille tours coûtent $0,425. Les requêtes échouées ne sont pas facturées. Voir la page tarifaire pour les recharges de $20 à $500 et les paliers bonus, et la documentation pour la liste complète des paramètres.