API Character AI in JS: configurazione Node e app Web
Una configurazione api character ai js si riduce al pacchetto npm openai ufficiale, un URL base e un endpoint server che tiene la chiave fuori dal browser. Questa pagina mostra il codice Node, un endpoint streaming Express e il fetch frontend associato.
Aggiornato

Punti chiave
- Il pacchetto npm openai funziona così com'è: cambia baseURL, apiKey e il modello in
uncensored. - Non spedire mai la chiave nel codice browser. Chiama invece un piccolo endpoint server.
- Lo streaming usa eventi server-sent e uno stream aperto usa uno slot di concorrenza.
- Anche fetch semplice funziona se preferisci non avere dipendenze.
La versione breve
Puoi raggiungere l'endpoint da JavaScript in tre modi: il pacchetto npm openai, fetch semplice o qualsiasi libreria che già supporta il formato chat OpenAI. L'URL di base è https://api.characteraiapi.com/v1, l'ID del modello è uncensored e ogni richiesta include Authorization: Bearer <key>. Se non hai ancora una chiave, la pagina della chiave API spiega la registrazione e la prova gratuita da $0,50 con un clic.
Questo è un servizio indipendente, non il prodotto Character.ai. Esegue un modello a pesi aperti ottimizzato per rispondere senza rifiuti di contenuti per uso adulto legale, e non genera immagini, audio o video. Per un'app di personaggi è sufficiente: scrivi la personalità, memorizza la conversazione e decidi come appare.
Node con il pacchetto openai
Crea un progetto, installa il pacchetto e usa i moduli ES. Gli esempi assumono Node 18 o superiore.
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 primo 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);Eseguilo con node chat.js. L'oggetto di utilizzo ti dice quanti token di prompt e di completion ha utilizzato la chiamata, che puoi moltiplicare per $0,15 e $0,50 per milione per vedere il prezzo esatto.
Non mettere mai la chiave nel codice browser
È allettante incollare la chiave in un componente React e chiamare l'API dalla pagina. Non farlo. Ogni visitatore può aprire la scheda di rete o il codice del bundle e copiarla, e poi spendere il tuo saldo. La soluzione è un proxy sottile su un server che controlli. Il browser invia il messaggio dell'utente al tuo endpoint; il tuo endpoint costruisce l'elenco completo dei messaggi, aggiunge la chiave e inoltra la chiamata.
Questo ti dà anche un punto in cui imporre cose che l'API non conosce: una personalità che gli utenti non possono sovrascrivere, un limite di messaggi per utente e il troncamento delle cronologie lunghe. Un browser dovrebbe inviare solo il nuovo testo utente e un ID conversazione, non il prompt di sistema.
Un endpoint streaming Express
Ecco un piccolo server con un endpoint. Mantiene le sessioni in memoria per la demo; usa un database per qualsiasi cosa reale.
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);La slice mantiene il messaggio di sistema più gli ultimi 20 messaggi. I turni più vecchi vengono scartati, il che mantiene il costo costante. Inviare solo il testo puro di ogni chunk mantiene il lato browser semplice. Se vuoi eventi più ricchi, invia eventi server-sent e analizzali sul client.
Eventi server-sent per uno streaming più ricco
Inviare testo puro funziona per una demo, ma le interfacce chat reali di solito hanno bisogno di più del testo: un segnale quando la risposta è completa, un messaggio di errore nel mezzo di uno stream o l'uso di token alla fine. Gli eventi server-sent ti danno messaggi nominati sulla stessa connessione HTTP. Il tuo endpoint scrive righe nel formato SSE e il browser le legge con un piccolo 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();Codificare ogni token come JSON evita un bug classico: un token che contiene un a capo interromperebbe il framing SSE. Sul client, leggi il corpo della risposta, dividi su una riga vuota, rimuovi il prefisso data: ed esegui il parsing del JSON. Il messaggio done indica all'interfaccia di riattivare la casella di immissione e riabilitare il pulsante di invio.
Gestisci le disconnessioni. Quando l'utente chiude la scheda, l'oggetto di risposta sul server emette un evento close. Ascoltalo e interrompi la richiesta upstream, altrimenti il tuo server continua a prelevare token che nessuno legge e lo streaming tiene occupato uno dei tuoi slot di concorrenza. L'SDK OpenAI accetta un AbortSignal nelle opzioni di richiesta per questo scopo.
Il lato browser
Il frontend chiama il tuo endpoint, mai l'host API. Leggere una risposta in streaming con fetch richiede poche righe:
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; });Disabilita il pulsante invia mentre una risposta è in streaming. Previene sottomissioni doppie e rispetta il limite di concorrenza, perché una richiesta in streaming occupa il suo slot fino alla fine.
Gestisci correttamente le sessioni
Una mappa in memoria perde tutto al riavvio del processo e si rompe non appena avvii due istanze del server. Sposta le sessioni in un database o in un archivio chiave-valore non appena il prototipo funziona. Memorizza l'elenco dei messaggi come colonna JSON, indicizzata per utente e personaggio. Quando arriva una richiesta, carica l'elenco, aggiungi il nuovo messaggio dell'utente, chiama l'API, aggiungi la risposta e scrivi di nuovo l'elenco.
Decidi presto chi possiede il prompt di sistema. Tienilo nel tuo codice o nella configurazione, non nell'elenco memorizzato che il browser può influenzare. Se la personalità è archiviata con la cronologia, un utente potrebbe provare a sovrascriverla modificando una richiesta. Ricrea l'array dei messaggi sul server ogni volta: il messaggio di sistema dalla configurazione, seguito dai turni memorizzati.
Imposta anche un limite per utente. Un widget chat pubblico senza limiti invita agli abusi automatizzati, e ogni token è fatturato a te. Un contatore per utente all'ora, controllato prima della chiamata API, è sufficiente per iniziare. Combinalo con un limite superiore sulla lunghezza del messaggio in modo che una richiesta non possa inviare un megabyte di testo. L'API accetta corpi fino a 8 MB, ma il tuo limite dovrebbe essere molto più basso, come 4.000 caratteri per messaggio utente.
Fetch puro, strumenti e modalità JSON
Se non vuoi dipendenze, una chiamata grezza funziona allo stesso modo. Esegui questo da un server, un worker o uno script, non dal codice di una pagina pubblica.
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));La chiamata di funzioni funziona con gli stessi campi tools e tool_choice che invia l'SDK. Quando il modello restituisce tool_calls, esegui la funzione e invia l'output di nuovo come messaggio con role: "tool" e il corrispondente tool_call_id. In un gioco è utile per i lanci di dadi, le ricerche nell'inventario o una ricerca di ciò che il personaggio ricorda del giocatore. Durante lo streaming, le chiamate di funzioni arrivano come frammenti parziali che devi unire prima di eseguire il parsing degli argomenti.
Hosting, limiti e costi
Lo streaming aggiunge alcuni dettagli di distribuzione che gli endpoint JSON semplici non hanno. Alcune piattaforme di hosting e proxy bufferizzano le risposte o limitano per quanto tempo una richiesta può rimanere aperta. Se i token arrivano in un unico blocco alla fine invece che uno alla volta, uno strato di buffering si trova tra il tuo server e il browser. Controlla la documentazione della tua piattaforma per l'opzione che disabilita il buffering per un endpoint, e per qualsiasi limite di tempo sull'esecuzione delle funzioni, poiché una lunga risposta di roleplay può durare diversi secondi.
Per un proxy inverso come nginx, il buffering della risposta è una causa comune e ha un'impostazione per disabilitarlo per ogni location. Per le funzioni serverless, cerca una modalità di risposta in streaming nella documentazione della piattaforma. Se il tuo host non può fare streaming, un piccolo processo Node sempre attivo su un server economico è un fallback affidabile.
Infine, inserisci il segreto nell'archivio delle variabili di ambiente dell'host e tienilo fuori dall'output della build. Gli strumenti di build front-end spesso incorporano qualsiasi variabile che ha un prefisso pubblico nel bundle del browser, quindi usa un nome senza quel prefisso e leggilo solo nel codice del server. Un controllo rapido è cercare nei file compilati i primi caratteri della chiave.
Limiti, retry e costi
Una chiave completa permette 8 richieste concorrenti e 300 al minuto. Una chiave trial permette 2 e 60. Oltre un limite l'API risponde con HTTP 429 e il codice rate_limited o concurrency. Un sovraccarico temporaneo è anche un 429 e include Retry-After: 5. In JavaScript l'SDK genera un errore con status === 429; catturalo, aspetta e riprova. L'SDK ritenta anche alcune volte per impostazione predefinita, che puoi regolare con l'opzione maxRetries sul client.
Il costo per turno è facile da stimare. Una chat con 2.000 token di input e 250 token di output costa 2.000 x $0,15 / 1.000.000 = $0,0003 per input e 250 x $0,50 / 1.000.000 = $0,000125 per output, quindi $0,000425. Mille turni sono $0,425. Le richieste fallite o rifiutate non sono addebitate. Vedi la pagina prezzi per le ricariche da $20 a $500 e i livelli bonus, e la documentazione per l'elenco completo dei parametri.