API de Character AI: Cambia tu cliente en tres líneas

Requisitos previos

Antes de escribir código, necesitas una cuenta activa en characteraiapi.com. Visita la página Obtener clave de API y regístrate solo con un correo electrónico y contraseña. No se requiere tarjeta de crédito para comenzar, y las cuentas nuevas reciben $0,50 en crédito de prueba válido por 7 días. Una vez registrado, tu clave de API se muestra inmediatamente. Mantén esta clave segura, ya que autentica todas las peticiones al endpoint. También necesitarás un SDK de un lenguaje compatible instalado en tu entorno de desarrollo. El endpoint character ai api acepta parámetros estándar de OpenAI, por lo que cualquier cliente compatible con OpenAI puede funcionar con cambios mínimos.

Instalar el SDK

Para proyectos en Python, instala el paquete oficial de OpenAI usando pip. Esta biblioteca maneja automáticamente la serialización JSON y las peticiones HTTP. Para aplicaciones en Node.js, usa npm para agregar el paquete openai. Ambas bibliotecas admiten las funciones de streaming y llamadas a herramientas descritas más adelante en esta guía. Asegúrate de que la versión de tu SDK sea lo suficientemente reciente para admitir Server-Sent Events (SSE) para streaming de tokens en tiempo real. Si usas un cliente HTTP personalizado en lugar de un SDK, debes manejar manualmente la carga útil JSON y el análisis del flujo SSE según la especificación de la API de OpenAI.

Autenticación

Toda petición a la API debe incluir tu clave de API en el encabezado Authorization. Usa el formato Bearer YOUR_API_KEY. La URL base para todas las peticiones es https://api.characteraiapi.com/v1. Al usar un SDK, configura la configuración base_url con este valor y proporciona tu clave mediante el parámetro api_key. Si pierdes tu clave o sospechas una filtración, puedes regenerarla desde el panel; la clave antigua se revocará inmediatamente. Solo se permite una clave activa por cuenta. Asegúrate de usar la URL base correcta, ya que las peticiones al endpoint estándar de OpenAI fallarán con un error 404 o 401.

Completado de chat básico

La funcionalidad principal se sirve a través del endpoint /v1/chat/completions. Envía una petición POST con un nombre de modelo de uncensored y tu historial de mensajes. El modelo responde con salida de texto sin aplicar filtros de contenido estándar para contenido adulto legal. A continuación se muestra un ejemplo de curl que demuestra una petición simple de completado de texto.

Copycurl https://api.characteraiapi.com/v1/chat/completions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Write a blunt product review of a cheap VPN."}]
  }'

Esta petición devuelve un objeto de completado que contiene el texto generado. Puedes ajustar parámetros como temperature para controlar la aleatoriedad o max_tokens para limitar la longitud de la salida. El modelo admite una ventana de contexto de 100.000 tokens, lo que permite procesar un historial de conversación sustancial o documentos largos en una sola petición.

Respuestas en streaming

Para una mejor experiencia de usuario, habilita el streaming estableciendo stream: true en tu petición. La API devuelve Server-Sent Events (SSE) que contienen fragmentos de tokens parciales a medida que se generan. Esto reduce la latencia percibida para aplicaciones de chatbot. Usa el parámetro stream_options si deseas recibir las estadísticas de uso finales en el último evento. El streaming es particularmente útil para el roleplay de personajes en tiempo real, donde mostrar texto palabra por palabra mejora la inmersión. Asegúrate de que el código de tu cliente maneje correctamente el formato SSE para analizar cada fragmento secuencialmente.

Copystream = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Tell the story in second person."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Límites de peticiones y errores

La API impone un límite de 300 peticiones por minuto por clave. Si lo excedes, recibirás un error 429 Too Many Requests. Los cuerpos de las peticiones tienen un límite de 8 MB. Los errores comunes incluyen 401 para una clave inválida o ausente, y 402 si tu crédito prepago se agota. Puedes recargar desde $10 usando criptomonedas (USDT o USDC), con créditos adicionales disponibles para depósitos más grandes. A diferencia de algunos proveedores, no hay tarifas ocultas ni bloqueos de suscripción; pagas solo por los tokens que consumes. Los precios son transparentes: $0.25 por cada 1M de tokens de entrada y $1.00 por cada 1M de tokens de salida. Asegúrate de que tu lógica de manejo de errores reintente en caso de 429 con retroceso exponencial.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.characteraiapi.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Summarise this thread without softening it."}],
)
print(resp.choices[0].message.content)

Node.js

Copyimport OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://api.characteraiapi.com/v1", apiKey: process.env.API_KEY });

const resp = await client.chat.completions.create({
  model: "uncensored",
  messages: [{ role: "user", content: "Draft a villain monologue for my game." }],
});
console.log(resp.choices[0].message.content);