ES ▾
Obtener clave de API

API de Character AI en JS: configuración en Node y aplicación web

Una configuración de character ai api js se reduce al paquete npm openai oficial, una URL base y una ruta de servidor que mantiene tu clave fuera del navegador. Esta página muestra el código Node, un endpoint de streaming Express y el fetch de front-end que lo acompaña.

Panel del navegador enlazado por una tubería brillante a un cubo de servidor con burbujas de chat, mostrando un diseño de proxy JS

Puntos clave

  1. El paquete npm openai funciona tal cual: cambia baseURL, apiKey y el modelo a uncensored.
  2. Nunca envíes la clave en el código del navegador. Llama a una ruta de servidor pequeña en su lugar.
  3. El streaming usa eventos enviados por el servidor, y un streaming abierto usa una ranura de concurrencia.
  4. Fetch plano también funciona si prefieres no depender de nada.

La versión corta

Puedes acceder al endpoint desde JavaScript de tres formas: el paquete npm openai, fetch sin envoltorios, o cualquier librería que ya hable el formato de chat de OpenAI. La URL base es https://api.characteraiapi.com/v1, el ID del modelo es uncensored y cada petición lleva Authorization: Bearer <key>. Si aún no tienes una clave, la página de clave de API explica el registro y la prueba de $0,50 con un solo clic.

Este es un servicio independiente, no el producto Character.ai. Ejecuta un modelo de pesos abiertos que está ajustado para responder sin rechazos de contenido para uso adulto legal, y no genera imágenes, audio ni video. Para una aplicación de personaje esto es suficiente: tú escribes la personalidad, almacenas la conversación y decides cómo se ve.

Node con el paquete openai

Crea un proyecto, instala el paquete y usa módulos ES. Los ejemplos asumen Node 18 o superior.

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 primer script en 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);

Ejecútalo con node chat.js. El objeto usage te dice cuántos tokens de prompt y completion usó la llamada, que puedes multiplicar por $0,15 y $0,50 por millón para ver el precio exacto.

Nunca pongas la clave en el código del navegador

Es tentador pegar la clave en un componente React y llamar a la API desde la página. No lo hagas. Cada visitante puede abrir la pestaña de red o el código empaquetado y copiarla, y luego gastar tu saldo. La solución es un proxy delgado en un servidor que controlas. El navegador envía el mensaje del usuario a tu ruta; tu ruta construye la lista completa de mensajes, añade la clave y reenvía la llamada.

Esto también te da un lugar para aplicar cosas que la API no conoce: una personalidad que los usuarios no pueden sobrescribir, un límite de mensajes por usuario y recorte de historiales largos. Un navegador solo debe enviar el nuevo texto del usuario y un ID de conversación, no el prompt del sistema.

Un endpoint de streaming Express

Aquí hay un servidor pequeño con una ruta. Mantiene sesiones en memoria para la demo; usa una base de datos para algo real.

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);

El slice mantiene el mensaje del sistema más los últimos 20 mensajes. Los turnos antiguos se descartan, lo que mantiene el coste estable. Enviar solo el texto plano de cada fragmento mantiene el lado del navegador simple. Si quieres eventos más ricos, envía eventos enviados por el servidor en su lugar y analízalos en el cliente.

Eventos enviados por el servidor para streaming más rico

Enviar texto plano funciona para una demo, pero las interfaces de chat reales suelen necesitar más que texto: una señal cuando la respuesta está completa, un mensaje de error en medio de un streaming, o el uso de tokens al final. Los eventos enviados por el servidor te dan mensajes con nombre sobre la misma conexión HTTP. Tu ruta escribe líneas en formato SSE, y el navegador las lee con un analizador pequeño.

// 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();

Codificar cada token como JSON evita un error clásico: un token que contenga un salto de línea rompería el enmarcado SSE. En el cliente, lee el cuerpo de la respuesta, divide por una línea en blanco, elimina el prefijo data: y analiza el JSON. El mensaje done indica a la interfaz que vuelva a habilitar la caja de entrada y re-habilite el botón de enviar.

Maneja las desconexiones. Al cerrar la pestaña, el objeto de respuesta en el servidor emite un evento close. Escúchalo y aborta la petición upstream; de lo contrario, tu servidor sigue consumiendo tokens que nadie lee y ocupa una ranura de concurrencia. El SDK de OpenAI acepta un AbortSignal en las opciones de la petición para esto.

El lado del navegador

El frontend llama a tu ruta, nunca al host de la API. Leer una respuesta en streaming con fetch requiere pocas líneas:

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; });

Desactiva el botón de enviar mientras una respuesta está en streaming. Evita envíos dobles y respeta el límite de concurrencia, porque una petición transmitida ocupa su ranura hasta que termina.

Almacena sesiones correctamente

Un mapa en memoria pierde todo cuando el proceso se reinicia y se rompe en cuanto ejecutas dos instancias de servidor. Mueve las sesiones a una base de datos o un almacén clave-valor tan pronto como el prototipo funcione. Almacena la lista de mensajes como una columna JSON, indexada por usuario y personaje. Cuando llegue una petición, carga la lista, añade el nuevo mensaje del usuario, llama a la API, añade la respuesta y escribe la lista de nuevo.

Decide temprano quién posee el prompt del sistema. Mantenlo en tu código o configuración, no en la lista almacenada que el navegador puede influenciar. Si la personalidad se almacena con el historial, un usuario podría intentar sobrescribirla elaborando una petición. Reconstruye el array de mensajes en el servidor cada vez: el mensaje del sistema de la configuración, seguido de los turnos almacenados.

También establece un límite por usuario. Un widget de chat público sin límites invita al abuso automatizado, y cada token se te cobra. Un contador por usuario por hora, verificado antes de la llamada a la API, es suficiente para empezar. Combínalo con un límite superior en la longitud de mensajes para que una petición no pueda enviar un megabyte de texto. La API acepta cuerpos de hasta 8 MB, pero tu propio límite debería ser mucho menor, como 4.000 caracteres por mensaje de usuario.

Fetch plano, herramientas y modo JSON

Si quieres no depender de nada, una llamada cruda funciona de la misma manera. Ejecuta esto desde un servidor, un worker o un script, no desde código de página pública.

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));

Las llamadas a funciones funcionan con los mismos campos tools y tool_choice que envía el SDK. Cuando el modelo devuelve tool_calls, ejecuta la función y envía el resultado de vuelta como un mensaje con role: "tool" y el tool_call_id coincidente. En un juego, esto es útil para tiradas de dados, búsquedas en el inventario o una consulta de lo que el personaje recuerda del jugador. Cuando se transmite, las llamadas a funciones llegan como fragmentos parciales que debes unir antes de analizar los argumentos.

Alojamiento, límites y coste

El streaming añade algunos detalles de implementación que las rutas JSON planas no tienen. Algunas plataformas de alojamiento y proxies almacenan en búfer las respuestas o limitan cuánto tiempo puede permanecer abierta una petición. Si los tokens llegan de golpe al final en lugar de uno por uno, una capa de almacenamiento intermedio está entre tu servidor y el navegador. Consulta la documentación de tu plataforma para la opción que desactiva el almacenamiento intermedio para una ruta, y para cualquier límite de tiempo en la ejecución de funciones, ya que una respuesta larga de roleplay puede durar muchos segundos.

Para un proxy inverso como nginx, el almacenamiento intermedio de respuesta es un culpable común y tiene una configuración para desactivarlo por ubicación. Para funciones serverless, busca un modo de respuesta de streaming en la documentación de la plataforma. Si tu host no puede transmitir, un pequeño proceso Node siempre activo en un servidor barato es una alternativa confiable.

Finalmente, pon el secreto en la tienda de variables de entorno del host y mantenlo fuera de la salida de compilación. Las herramientas de compilación de front-end a menudo incrustan cualquier variable que tenga un prefijo público en el paquete del navegador, así que usa un nombre sin ese prefijo, y léelo solo en el código del servidor. Una verificación rápida es buscar en tus archivos compilados los primeros caracteres de la clave.

Límites, reintentos y coste

Una clave completa permite 8 peticiones simultáneas y 300 por minuto. Una clave de prueba permite 2 y 60. Al superar un límite, la API responde con HTTP 429 y el código rate_limited o concurrency. Una sobrecarga temporal también es un 429 e incluye Retry-After: 5. En JavaScript, el SDK lanza un error con status === 429; atrápalo, espera y vuelve a intentarlo. El SDK también reintenta un par de veces por defecto, lo que puedes ajustar con la opción maxRetries en el cliente.

Estimar el coste por turno es fácil. Un chat con 2.000 tokens de entrada y 250 de salida cuesta 2.000 x $0,15 / 1.000.000 = $0,0003 para entrada y 250 x $0,50 / 1.000.000 = $0,000125 para salida, es decir, $0,000425. Mil turnos cuestan $0,425. Las peticiones fallidas o rechazadas no se cobran. Consulta la página de precios para recargas de $20 a $500 y los niveles de bonificación, y la documentación para la lista completa de parámetros.

Preguntas y respuestas

¿Puedo llamar a la API directamente desde una aplicación React o Vue?

Técnicamente sí, pero la clave sería visible para todos los visitantes. Usa una ruta de servidor pequeña que añada la clave y reenvíe la petición.

¿Qué paquete npm debo usar?

El paquete oficial openai funciona. Configura baseURL al endpoint, usa tu clave como apiKey y el modelo uncensored. El fetch nativo también es válido.

¿Funciona en Deno, Bun o Cloudflare Workers?

Cualquier entorno que pueda hacer una petición HTTPS con un encabezado Bearer puede llamarlo. El paquete openai admite varios entornos, así que consulta su documentación para el tuyo.

¿Cómo transmito tokens a la página?

Configura stream: true en el servidor, reenvía cada fragmento al navegador y léelo con un lector de fetch. Cada streaming abierto ocupa una ranura de concurrencia.

¿Es esta la API oficial de Character.ai?

No. Es un servicio independiente compatible con OpenAI con su propia clave y un único modelo, ofrecido como backend para tus propias aplicaciones de personajes.

Tu clave está a un formulario de distancia

Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.

Obtener clave de API