Character AI API: Switch your client in three lines

Prerequisites

Before writing code, you need an active account on characteraiapi.com. Visit the Get API key page and sign up with just an email and password. No credit card is required to start, and new accounts receive $0.50 in trial credit valid for 7 days. Once registered, your API key is displayed immediately. Keep this key secure, as it authenticates all requests to the endpoint. You will also need a supported language SDK installed in your development environment. The character ai api endpoint accepts standard OpenAI parameters, so any existing OpenAI-compatible client can work with minimal changes.

Install the SDK

For Python projects, install the official OpenAI package using pip. This library handles the JSON serialization and HTTP requests automatically. For Node.js applications, use npm to add the openai package. Both libraries support the streaming and tool-calling features described later in this guide. Ensure your SDK version is recent enough to support Server-Sent Events (SSE) for real-time token streaming. If you are using a custom HTTP client instead of an SDK, you must manually handle the JSON payload and SSE stream parsing according to the OpenAI API specification.

Authentication

Every request to the API must include your API key in the Authorization header. Use the format Bearer YOUR_API_KEY. The base URL for all requests is https://api.characteraiapi.com/v1. When using an SDK, set the base_url configuration to this value and provide your key via the api_key parameter. If you lose your key or suspect a leak, you can regenerate it from the dashboard; the old key will be revoked immediately. Only one active key is allowed per account. Ensure you are using the correct base URL, as requests to the standard OpenAI endpoint will fail with a 404 or 401 error.

Basic Chat Completion

The core functionality is served via the /v1/chat/completions endpoint. Send a POST request with a model name of uncensored and your message history. The model responds with text output without applying standard content filters for lawful adult content. Below is a curl example demonstrating a simple text completion request.

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."}]
  }'

This request returns a completion object containing the generated text. You can adjust parameters like temperature to control randomness or max_tokens to limit output length. The model supports a context window of 100,000 tokens, allowing for substantial conversation history or long documents to be processed in a single request.

Streaming Responses

For a better user experience, enable streaming by setting stream: true in your request. The API returns Server-Sent Events (SSE) containing partial token chunks as they are generated. This reduces perceived latency for chatbot applications. Use the stream_options parameter if you want to receive the final usage statistics in the last event. Streaming is particularly useful for real-time character roleplay, where displaying text word-by-word enhances immersion. Ensure your client code correctly handles the SSE format to parse each chunk sequentially.

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)

Rate Limits and Errors

The API enforces a limit of 300 requests per minute per key. If you exceed this, you will receive a 429 Too Many Requests error. Request bodies are limited to 8 MB. Common errors include 401 for an invalid or missing key, and 402 if your prepaid credit is exhausted. You can top up from $10 using crypto (USDT or USDC), with bonus credits available for larger deposits. Unlike some providers, there are no hidden fees or subscription locks; you pay only for the tokens you consume. Pricing is transparent: $0.25 per 1M input tokens and $1.00 per 1M output tokens. Ensure your error handling logic retries on 429s with exponential backoff.

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