ES ▾
Obtener clave de API

API de Character AI en Python: configuración del SDK de OpenAI

Para usar un flujo de trabajo de Character AI API en Python, instala el paquete oficial openai, apunta su URL base a un endpoint compatible con OpenAI y establece el modelo en uncensored. El resto de esta página crea un pequeño chat de personaje sobre esa base, con historial, streaming, reintentos y seguimiento de costes.

Terminal en una plataforma de streaming de burbujas de chat en cubos vinculados, representando un cliente de chat en Python

Puntos clave

  1. Dos valores cambian en el SDK estándar: base_url y api_key.
  2. El comportamiento del personaje proviene del mensaje del sistema más del historial que reenvías en cada turno.
  3. Streaming, llamadas a funciones y modo JSON funcionan todos a través del mismo cliente.
  4. Maneja HTTP 429 con una espera breve y limita las peticiones simultáneas a 8 con una clave completa.

Instalar y conectar

No hay una biblioteca de cliente especial. Las apps de Character en Python usan el mismo paquete openai que todo lo demás. Instálalo y guarda tu clave en una variable de entorno.

pip install openai
export API_KEY="paste-your-key-here"

Obtén una clave de la página de clave de API primero. Las cuentas nuevas pueden reclamar $0,50 de crédito de prueba allí con un clic, sin necesidad de tarjeta. Luego crea el cliente:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.characteraiapi.com/v1",
    api_key=os.environ["API_KEY"],
)

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)
print(resp.usage)

Si eso imprime un saludo y un objeto de uso, la conexión es buena. El servicio expone POST /v1/chat/completions y GET /v1/models. Cualquier cosa que no sea chat de texto, como imágenes, embeddings o ajuste fino, no está disponible.

Un bucle de chat de personaje con memoria

La API es sin estado. No recuerda el último turno, por lo que tu programa debe enviar toda la conversación cada vez. Para un personaje significa un mensaje del sistema seguido de mensajes alternos de usuario y asistente. Este bucle los mantiene en una lista.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])

PERSONA = (
    "You are Mara, a dry-witted ship engineer in a space opera. "
    "Stay in character, answer in two to four sentences, and never mention being an AI."
)
history = [{"role": "system", "content": PERSONA}]

while True:
    user = input("you> ").strip()
    if user in {"quit", "exit"}:
        break
    history.append({"role": "user", "content": user})
    resp = client.chat.completions.create(
        model="uncensored",
        messages=history,
        temperature=0.9,
        top_p=0.95,
    )
    text = resp.choices[0].message.content
    history.append({"role": "assistant", "content": text})
    print("mara>", text)

Los ajustes de muestreo se pasan al modelo: temperature, top_p, stop, seed y las penalizaciones de frecuencia y presencia. Para roleplay, una temperatura entre 0,8 y 1,0 suele dar un diálogo más animado, mientras que un valor más bajo se adapta a tareas estructuradas. Establece seed cuando quieras comparar dos versiones de prompt en condiciones similares.

Guardar y recargar una conversación

Un chat que desaparece al salir del script es una demo, no una app. Guardar el historial como un archivo JSON es el paso más pequeño que lo hace persistente. La función auxiliar de abajo carga los mensajes guardados del personaje si existen y los escribe de nuevo después de cada turno.

import json
from pathlib import Path

def load(name, persona):
    path = Path(f"{name}.json")
    if path.exists():
        return json.loads(path.read_text())
    return [{"role": "system", "content": persona}]

def save(name, history):
    Path(f"{name}.json").write_text(json.dumps(history, indent=2))

Llama a load al inicio y a save después de agregar la respuesta del asistente. Mantén un archivo por personaje y por usuario, y ya tienes una configuración de múltiples personajes. Una vez que superes los archivos, la misma lista de diccionarios se adapta a una columna de base de datos o a un almacén de clave-valor sin cambios, porque es exactamente lo que la API espera.

Piensa en qué guardas. El historial puede contener detalles personales que los usuarios escribieron. Los prompts enviados a esta API no se usan para entrenamiento, pero tus propios archivos y registros son tu responsabilidad, así que decide cuánto tiempo los conservas y quién puede leerlos.

Recortar el historial antes de que sea costoso

La ventana de contexto es de 100.000 tokens, prompt más completado. Un roleplay largo puede alcanzar ese límite con el tiempo, y el coste aumenta porque pagas tokens de entrada para todo el historial en cada turno. Un enfoque simple mantiene el mensaje del sistema y los últimos N intercambios.

def trimmed(history, keep=20):
    system = history[:1]
    rest = history[1:]
    return system + rest[-keep:]

# inside the loop
resp = client.chat.completions.create(
    model="uncensored",
    messages=trimmed(history),
)

Un diseño mejor para historias largas es un resumen rotativo. Cada 30 mensajes, pide al modelo que resuma la parte más antigua en 200 palabras, reemplaza esos mensajes con el resumen dentro del mensaje del sistema y continúa. Pierdes algo de detalle pero mantienes las tramas, y el costo por turno se mantiene plano.

Aquí están las matemáticas para un chat que ha alcanzado 8.000 tokens de historial con una respuesta de 300 tokens: la entrada es 8.000 x $0,15 / 1.000.000 = $0,0012, la salida es 300 x $0,50 / 1.000.000 = $0,00015, así que $0,00135 por turno. Recortar ese historial a 2.000 tokens reduce el turno a $0,0003 + $0,00015 = $0,00045. Eso es un tercio del precio para la mayoría de las conversaciones.

Transmite respuestas a medida que se escriben

Para una interfaz de chat quieres que el texto aparezca a medida que se genera. Establece stream=True e itera sobre los fragmentos. El streaming se ejecuta mediante eventos enviados por el servidor, y puedes solicitar el uso en el último fragmento.

stream = client.chat.completions.create(
    model="uncensored",
    messages=history,
    stream=True,
    stream_options={"include_usage": True},
)

parts = []
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        piece = chunk.choices[0].delta.content
        parts.append(piece)
        print(piece, end="", flush=True)
print()
reply = "".join(parts)

Recuerda que una petición en streaming mantiene su slot de concurrencia hasta que termina el stream. Con una clave completa puedes ejecutar 8 a la vez; con una clave de prueba solo 2. Si un usuario cierra la pestaña, asegúrate de que tu servidor cierre también el stream entrante, o este mantendrá el slot ocupado.

Ejecutar muchos chats a la vez con asyncio

Un servicio web que maneja muchos usuarios al mismo tiempo necesita el cliente asíncrono. El patrón es simple: un cliente AsyncOpenAI compartido, un semáforo del tamaño de tu límite de concurrencia y una corutina por conversación.

import asyncio
import os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://api.characteraiapi.com/v1", api_key=os.environ["API_KEY"])
gate = asyncio.Semaphore(8)  # use 2 on a trial key

async def reply(messages):
    async with gate:
        r = await client.chat.completions.create(model="uncensored", messages=messages)
        return r.choices[0].message.content

async def main():
    jobs = [
        reply([{"role": "user", "content": f"Give character {i} a one-line greeting."}])
        for i in range(20)
    ]
    for text in await asyncio.gather(*jobs):
        print(text)

asyncio.run(main())

Se crean veinte trabajos, pero solo ocho se ejecutan a la vez. El resto espera su turno dentro del semáforo, así que nunca activas el error de concurrency. Si tu servicio maneja respuestas en streaming, recuerda que cada stream abierto cuenta hasta que termina, lo que significa que lectores lentos en el cliente pueden mantener slots más tiempo del esperado. Establece un tiempo de espera en el cliente y cancela los streams de usuarios que ya se han ido.

El límite por minuto es independiente. Con 300 peticiones por minuto en una clave completa, una ráfaga de 20 llamadas cortas está bien, pero un bucle que envía miles de llamadas necesita ritmo. Un enfoque simple es esperar una fracción de segundo entre lanzamientos de tareas, o usar una biblioteca de cubeta de tokens que se adapte a tu stack.

Herramientas y modo JSON

Los bots de personaje a menudo necesitan salida estructurada: una puntuación de estado de ánimo, una actualización de inventario, una lista de opciones para el jugador. El modo JSON hace que la respuesta sea JSON válido, y describes la forma en el prompt.

import json

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with JSON only: {\"mood\": string, \"choices\": [string, string, string]}"},
        {"role": "user", "content": "Mara finds a sealed hatch in the cargo bay."},
    ],
)
data = json.loads(resp.choices[0].message.content)
print(data["mood"], data["choices"])

Las llamadas a funciones usan los campos estándar tools y tool_choice. El modelo devuelve una entrada tool_calls, tu código ejecuta la función y envías el resultado de vuelta como un mensaje con role: "tool".

tools = [{
    "type": "function",
    "function": {
        "name": "roll_dice",
        "description": "Roll an n-sided die",
        "parameters": {
            "type": "object",
            "properties": {"sides": {"type": "integer"}},
            "required": ["sides"],
        },
    },
}]

msgs = [{"role": "user", "content": "Mara tries to force the hatch. Roll a d20."}]
first = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
call = first.choices[0].message.tool_calls[0]

msgs.append(first.choices[0].message)
msgs.append({"role": "tool", "tool_call_id": call.id, "content": "17"})
final = client.chat.completions.create(model="uncensored", messages=msgs, tools=tools)
print(final.choices[0].message.content)

Prueba esto contra tus propios prompts antes de confiar en ello. Los modelos de pesos abiertos difieren en cuán confiablemente emiten una llamada a función, así que mantén una ruta de respaldo cuando tool_calls esté vacío.

Manejar errores y límites de peticiones

Una clave completa permite 8 peticiones concurrentes y 300 peticiones por minuto. Una clave de prueba permite 2 y 60. Superar un límite te da HTTP 429 con el código de error rate_limited (demasiadas por minuto) o concurrency (demasiadas a la vez). Una sobrecarga temporal también devuelve 429, con un encabezado Retry-After: 5. El SDK lanza RateLimitError para esto, y puedes envolver la llamada en un reintento.

import time
import openai

def chat(messages, tries=4):
    for attempt in range(tries):
        try:
            return client.chat.completions.create(model="uncensored", messages=messages)
        except openai.RateLimitError as err:
            wait = 5
            retry_after = err.response.headers.get("Retry-After")
            if retry_after:
                wait = int(retry_after)
            time.sleep(wait * (attempt + 1))
    raise RuntimeError("still rate limited")

Si ejecutas muchas conversaciones desde un solo proceso, límitalas con un semáforo para que nunca excedas 8 peticiones en vuelo. Con asyncio y AsyncOpenAI, asyncio.Semaphore(8) alrededor de cada llamada es suficiente. Los encabezados de respuesta X-RateLimit-Limit-Requests y X-RateLimit-Limit-Concurrency confirman los límites que aplican a tu clave, y X-Balance-USD muestra tu crédito restante.

Las peticiones fallidas o rechazadas no se cobran, así que los reintentos por errores no te cuestan. Cuando tu saldo está bajo, recarga desde $20 hasta $500; las cantidades desde $50 llevan un bono del 5%, 10% o 15% en los niveles de $50, $100 y $200. Los detalles están en la página de precios, y la lista completa de parámetros está en la documentación.

Rastrear cuánto cuesta cada sesión

Cada respuesta no en streaming incluye un objeto usage con prompt_tokens y completion_tokens. Cuando transmites y solicitas uso, el fragmento final lo lleva. Convierte esos números en dólares con una función pequeña y regístralo junto al ID de sesión.

IN_PRICE = 0.15 / 1_000_000
OUT_PRICE = 0.50 / 1_000_000

def cost(usage):
    return usage.prompt_tokens * IN_PRICE + usage.completion_tokens * OUT_PRICE

resp = client.chat.completions.create(
    model="uncensored",
    messages=[{"role": "user", "content": "Describe the engine room in three lines."}],
)
print(f"${cost(resp.usage):.6f}")

Con estos números puedes responder preguntas prácticas. Si una sesión promedio tiene 40 turnos, con historial creciendo de 500 a 6.000 tokens de entrada y 250 tokens de salida por respuesta, la entrada media es aproximadamente 3.250 tokens. El costo de entrada por turno es aproximadamente 3.250 x $0,15 / 1.000.000 = $0,00049 y la salida es 250 x $0,50 / 1.000.000 = $0,000125, así que alrededor de $0,00061 por turno y $0,0245 para los 40 turnos. Un usuario que juega 20 sesiones al mes te cuesta unos 49 centavos. Ese es un número alrededor del cual puedes fijar el precio de un producto.

Ejecuta la verificación de conexión dentro de un entorno virtual para que la versión del paquete se mantenga fija para el proyecto, y lista los modelos una vez con client.models.list() al inicio. Si esa llamada falla, te enteras de una clave incorrecta o una base URL incorrecta antes que cualquier usuario, y puedes imprimir un mensaje claro en lugar de una traza de pila profunda dentro de un bucle de chat. Los equipos que implementan este código a menudo agregan la misma llamada a una ruta de verificación de salud.

Registra el costo por sesión y mira el cinco por ciento superior. Las sesiones largas que nunca recortan el historial suelen dominar la factura, y la solución es el enfoque de recorte o resumen descrito anteriormente.

Preguntas y respuestas

¿Existe una biblioteca oficial de Python para Character.ai?

Este servicio no es Character.ai y no tiene una biblioteca independiente. Usas el paquete estándar openai con la URL base y el ID de modelo indicados arriba.

¿Cómo mantengo la consistencia del personaje entre mensajes?

Coloca la personalidad en el mensaje del sistema y reenvía el historial reciente con cada petición. La API no almacena conversaciones por ti.

¿Puedo usar el cliente asíncrono?

Sí. AsyncOpenAI acepta la misma URL base y api_key. Limita las llamadas paralelas a 8 en una clave completa o 2 en una clave de prueba.

¿Cuánto cuesta una vuelta de chat?

Con 1.500 tokens de entrada y 300 tokens de salida son $0,000375, basado en $0,15 y $0,50 por 1M de tokens. Un historial más largo aumenta la proporción de entrada.

¿Funciona el streaming con el SDK de Python?

Sí. Pasa stream=True e itera sobre los fragmentos. El uso se envía al final del streaming.

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