EN ▾
Get API key

Character AI API in Python: OpenAI SDK Setup

To use a character ai api python workflow, install the official openai package, point its base URL at an OpenAI-compatible endpoint and set the model to uncensored. The rest of this page builds a small persona chat on top of that, with history, streaming, retries and cost tracking.

Terminal on a platform streaming chat bubbles into linked cubes, representing a Python chat client

Key points

  1. Two values change in the standard SDK: base_url and api_key.
  2. Character behaviour comes from the system message plus the history you resend each turn.
  3. Streaming, tool calling and JSON mode all work through the same client.
  4. Handle HTTP 429 with a short wait and cap parallel calls at 8 on a full key.

Install and connect

There is no special client library. Character apps in Python use the same openai package as everything else. Install it and keep your key in an environment variable.

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

Get a key from the API key page first. New accounts can claim $0.50 of trial credit there with one click, no card needed. Then create the client:

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)

If that prints a greeting and a usage object, the connection is good. The service exposes POST /v1/chat/completions and GET /v1/models. Anything that is not text chat, such as images, embeddings or fine-tuning, is not available.

A character chat loop with memory

The API is stateless. It does not remember the last turn, so your program must send the whole conversation each time. For a persona that means a system message followed by alternating user and assistant messages. This loop keeps them in a list.

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)

Sampling settings are passed through to the model: temperature, top_p, stop, seed and the frequency and presence penalties. For roleplay, a temperature between 0.8 and 1.0 usually gives livelier dialogue, while a lower value suits structured tasks. Set seed when you want to compare two prompt versions under similar conditions.

Save and reload a conversation

A chat that disappears when the script exits is a demo, not an app. Storing the history as a JSON file is the smallest step that makes it feel persistent. The helper below loads a character's saved messages if they exist and writes them back after every turn.

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

Call load at startup and save after you append the assistant reply. Keep one file per character and per user, and you already have a multi-character setup. Once you outgrow files, the same list of dicts fits a database column or a key-value store without change, because it is exactly what the API expects.

Think about what you store. The history may contain personal details that users typed in. Prompts sent to this API are not used for training, but your own files and logs are your responsibility, so decide how long you keep them and who can read them.

Trim history before it gets expensive

The context window is 100,000 tokens, prompt plus completion. A long roleplay can reach that over time, and cost grows with it because you pay input tokens for the full history on every turn. A simple approach keeps the system message and the last N exchanges.

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

A better design for long stories is a rolling summary. Every 30 messages, ask the model to summarise the older part in 200 words, replace those messages with the summary inside the system message, and continue. You lose some detail but keep the plot threads, and the per-turn cost stays flat.

Here is the math for a chat that has reached 8,000 tokens of history with a 300 token reply: input is 8,000 x $0.15 / 1,000,000 = $0.0012, output is 300 x $0.50 / 1,000,000 = $0.00015, so $0.00135 per turn. Trimming that history to 2,000 tokens drops the turn to $0.0003 + $0.00015 = $0.00045. That is a third of the price for most conversations.

Stream replies as they are written

For a chat interface you want text to appear as it is generated. Set stream=True and iterate over the chunks. Streaming runs over server-sent events, and you can ask for usage in the last chunk.

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)

Remember that a streamed request holds its concurrency slot until the stream ends. On a full key you can run 8 at once; on a trial key only 2. If a user closes the tab, make sure your server closes the upstream stream too, or it keeps the slot busy.

Run many chats at once with asyncio

A web service that handles many users at the same time needs the async client. The pattern is simple: one shared AsyncOpenAI client, one semaphore sized to your concurrency limit, and a coroutine per conversation.

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

Twenty jobs are created, but only eight run at once. The rest wait their turn inside the semaphore, so you never trigger the concurrency error. If your service handles streaming replies, remember that each open stream counts until it finishes, which means slow readers on the client side can hold slots longer than you expect. Set a timeout on the client and cancel streams whose users have gone away.

The per-minute limit is separate. At 300 requests per minute on a full key, a burst of 20 short calls is fine, but a loop that sends thousands of calls needs pacing. A simple approach is to sleep for a fraction of a second between task launches, or use a token bucket library that fits your stack.

Tools and JSON mode

Character bots often need structured output: a mood score, an inventory update, a list of choices for the player. JSON mode makes the reply valid JSON, and you describe the shape in the 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"])

Tool calling uses the standard tools and tool_choice fields. The model returns a tool_calls entry, your code runs the function, and you send the result back as a message with 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)

Test this against your own prompts before relying on it. Open-weight models differ in how reliably they emit a tool call, so keep a fallback path when tool_calls is empty.

Handle errors and rate limits

A full key allows 8 concurrent requests and 300 requests per minute. A trial key allows 2 and 60. Over a limit you get HTTP 429 with the error code rate_limited (too many per minute) or concurrency (too many at once). A temporary overload also returns 429, with a Retry-After: 5 header. The SDK raises RateLimitError for these, and you can wrap the call in a retry.

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

If you run many conversations from one process, bound them with a semaphore so you never exceed 8 requests in flight. With asyncio and AsyncOpenAI, asyncio.Semaphore(8) around each call is enough. The response headers X-RateLimit-Limit-Requests and X-RateLimit-Limit-Concurrency confirm the limits that apply to your key, and X-Balance-USD shows your remaining credit.

Failed or refused requests are not charged, so retries on errors do not cost you. When your balance runs low, top up from $20 to $500; amounts from $50 carry a bonus of 5%, 10% or 15% at the $50, $100 and $200 levels. Details are on the pricing page, and the full parameter list is in the docs.

Track what each session costs

Every non-streamed response includes a usage object with prompt_tokens and completion_tokens. When you stream and ask for usage, the final chunk carries it. Turn those numbers into dollars with a small function and log it next to the session ID.

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

With these numbers you can answer practical questions. If an average session is 40 turns, with history growing from 500 to 6,000 input tokens and 250 output tokens per reply, the mean input is roughly 3,250 tokens. Input cost per turn is about 3,250 x $0.15 / 1,000,000 = $0.00049 and output is 250 x $0.50 / 1,000,000 = $0.000125, so around $0.00061 per turn and $0.0245 for the 40 turns. A user who plays 20 sessions a month costs you about 49 cents. That is a number you can price a product around.

Run the connection check inside a virtual environment so the package version stays fixed for the project, and list the models once with client.models.list() at startup. If that call fails, you learn about a wrong key or a wrong base URL before any user does, and you can print a clear message instead of a stack trace deep inside a chat loop. Teams that deploy this code often add the same call to a health check route.

Log the cost per session and look at the top five percent. Long sessions that never trim history usually dominate the bill, and the fix is the trimming or summary approach described earlier.

Questions and answers

Is there an official Character.ai Python library?

This service is not Character.ai and has no separate library. You use the standard openai package with the base URL and model ID given above.

How do I keep a character consistent across messages?

Put the persona in the system message and resend the recent history with every request. The API does not store conversations for you.

Can I use the async client?

Yes. AsyncOpenAI accepts the same base_url and api_key. Limit parallel calls to 8 on a full key or 2 on a trial key.

How much does one chat turn cost?

With 1,500 input tokens and 300 output tokens it is $0.000375, based on $0.15 and $0.50 per 1M tokens. Longer history raises the input share.

Does streaming work with the Python SDK?

Yes. Pass stream=True and iterate over the chunks. Usage is sent at the end of the stream.

Your key is one form away

Create an account, copy the key, change the base URL. That is the whole setup.

Get API key