Character AI API Key: How to Get and Use One
If you searched for a character ai api key, the first thing to know is that this site is not Character.ai and does not issue its keys. It gives you a key for an independent, OpenAI-compatible text API that works as a drop-in backend for character chat apps.
Updated

Key points
- You get a key after signing up with Google or email and password, then opening the API key page.
- New users can claim $0.50 of trial credit with one click, no card needed, valid for 7 days.
- Use the base URL https://api.characteraiapi.com/v1 and the model ID
uncensoredwith any OpenAI SDK. - Keep the key on a server or in an environment variable, never in public front-end code.
What you are actually getting
Character.ai is a consumer chat product. People who search for a character ai api key usually want one of two things: a way to call a character chatbot from their own code, or a backend for a persona app that is not limited by a hosted product's rules. This site covers the second need. You sign up, receive a key, and send requests to an OpenAI-compatible endpoint. Nothing here connects to Character.ai or reuses its characters.
The service is a hosted text API in front of one open-weight model, run by an independent provider and tuned to answer without content refusals for lawful adult use. It is not the official API of any model vendor and not a router across vendors. The model ID is uncensored, and the base URL is https://api.characteraiapi.com/v1. Two methods exist: POST /v1/chat/completions and GET /v1/models.
Because the interface matches OpenAI's, the work of building a character is on your side. You write the persona as a system message, keep the conversation history, and send it with each request. That gives you control over voice, memory and pacing that a closed product rarely exposes. The hard limit is the same for every user: no sexual content involving minors, ever.
Get your key in five steps
The whole path takes a few minutes. You do not need a card to start.
- Sign up. Use Google, or register with an email and password.
- Open the key page. Go to the API key page, where your account's key is shown.
- Claim the trial. One click on that page adds $0.50 of trial credit. It is limited to one per person and is valid for 7 days.
- Copy the key. Store it in a password manager or a secrets file straight away.
- Send a test request. Use the curl command below before you touch any app code.
Treat the key like a password. Anyone who has it can spend your balance. If you think it leaked, stop using it right away, remove it from every app and check your balance for unexpected spending.
Test the key with curl
Set the key as an environment variable so it never lands in your shell history as plain text inside a script. Then list the models. This confirms that the key works and that you reach the right host.
export API_KEY="paste-your-key-here"
curl https://api.characteraiapi.com/v1/models \
-H "Authorization: Bearer $API_KEY"You should get a JSON list that includes uncensored. Now send a first chat request with a small persona. The system message sets the character, the user message starts the scene.
curl https://api.characteraiapi.com/v1/chat/completions \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "uncensored",
"messages": [
{"role": "system", "content": "You are Mara, a dry-witted ship engineer in a space opera. Stay in character."},
{"role": "user", "content": "The reactor is humming wrong again. What do you do?"}
],
"temperature": 0.9
}'The response follows the standard chat completions shape. The reply text is in choices[0].message.content. The response headers also carry X-Request-Id, X-Balance-USD and the rate limit headers, which is handy when you want to show a remaining balance in your own UI.
Use the key from Python or Node
Any OpenAI SDK works once you change two values: the base URL and the key. Here is the Python version with the official openai package.
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.characteraiapi.com/v1",
api_key=os.environ["API_KEY"],
)
reply = client.chat.completions.create(
model="uncensored",
messages=[
{"role": "system", "content": "You are Mara, a ship engineer. Stay in character."},
{"role": "user", "content": "Status report?"},
],
)
print(reply.choices[0].message.content)And the same call in Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.characteraiapi.com/v1",
apiKey: process.env.API_KEY,
});
const reply = await client.chat.completions.create({
model: "uncensored",
messages: [
{ role: "system", content: "You are Mara, a ship engineer. Stay in character." },
{ role: "user", content: "Status report?" },
],
});
console.log(reply.choices[0].message.content);Many chat front ends have a field for a custom OpenAI-compatible endpoint. In those tools you paste the base URL, paste the key, and type uncensored as the model name. Nothing else needs to change. The docs page lists the supported parameters, including streaming, tool calling and JSON mode.
Common key problems and quick fixes
Most first-time failures come from a handful of small mistakes. Check them in this order before you suspect anything bigger.
- Extra whitespace or quotes in the key. A trailing newline copied from a file is enough to make authentication fail. Print the length of the variable and compare it with what you copied.
- Wrong base URL. The base URL ends in
/v1, and the SDK appends/chat/completionsitself. If you also add/chat/completionsto the base URL, the path doubles and the request fails. - Wrong model name. The model ID is
uncensored. Names borrowed from other services will not match. CallGET /v1/modelsto see what the server reports. - Missing header. Raw HTTP calls need
Authorization: Bearerfollowed by a space and the key, plusContent-Type: application/jsonon POST requests. - Empty balance. The
X-Balance-USDresponse header shows what is left. When the trial credit is spent or past its 7 days, top up or requests will stop succeeding. - Rate limits. A trial key allows 2 concurrent requests and 60 per minute. Two open streams already use both slots.
A bad key typically produces an authentication error rather than a model reply. A limit produces HTTP 429 with the code rate_limited or concurrency. Reading the error body, not just the status code, saves time because the code tells you which limit you hit. Every response carries an X-Request-Id; keep it in your logs, so you can match a failed call to a specific request later.
Trial limits and what the trial buys
A trial key has lower limits than a full one: 2 concurrent requests and 60 requests per minute. A full key allows 8 concurrent requests and 300 requests per minute. For testing a single persona that is plenty. If you run several chats at once from a test script, you will see HTTP 429 with the error code concurrency or rate_limited. A streamed request holds its concurrency slot until the stream ends, so two open streams on a trial key fill it.
How far does $0.50 go? Prices are $0.15 per 1M input tokens and $0.50 per 1M output tokens. Take a typical chat turn with 1,500 tokens of history and persona going in and 300 tokens coming out:
- Input: 1,500 tokens x $0.15 / 1,000,000 = $0.000225
- Output: 300 tokens x $0.50 / 1,000,000 = $0.00015
- One turn: $0.000375
- $0.50 / $0.000375 is about 1,333 turns
That is enough to test several characters properly. Failed or refused requests are not charged, so a request that errors out does not eat your credit. The trial expires after 7 days; credit you buy later does not expire.
Settings that make a persona feel right
A key gets you the connection; the quality of a character comes from the prompt and the sampling settings. A few habits help more than clever tricks.
Write the system message as a short character sheet in plain sentences: who the character is, how they talk, what they want, and how long their replies should be. Give one or two example lines of dialogue if the voice matters. Models follow concrete examples better than adjectives, so a line like "Mara answers in short, dry sentences and jokes when nervous" works better than "Mara is witty and charming".
Use temperature to set liveliness. Values near 0.9 give more varied phrasing, while values near 0.5 keep the character steadier. Add a stop sequence if your app uses a speaker label such as "User:" and you want to prevent the model from writing the other side of the conversation. The frequency and presence penalties can reduce repeated phrases in long chats, but raise them gently, since high values can make dialogue strange.
Remember that the model only knows what is in the request. If the character should recall the player's name from 200 messages ago, either keep that message in the window or store key facts in the system message. This is why a memory list that you update yourself often beats sending a huge history.
Topping up when the trial runs out
There is no subscription. You prepay and spend per token. Top-ups take any whole amount from $20 to $500, and larger amounts carry a bonus: +5% from $50, +10% from $100 and +15% from $200. So $50 becomes $52.50 of credit, $100 becomes $110, and $200 becomes $230. You can pay with crypto (USDT on TRC20, USDC on Base).
The pricing page has the full table. For planning, the same 1,500-in, 300-out turn costs $0.000375, so $20 covers roughly 53,000 such turns. Long-running roleplay costs more per turn because the history grows, so cap how much of it you resend. The context window is 100,000 tokens, prompt plus completion, but you rarely want to fill it.
Keeping the key safe in a real app
The most common mistake with a chat project is calling the API straight from browser code. Anything shipped to the browser can be read by every visitor, including the key. Put a small server between your front end and the API. The browser talks to your route, your route adds the Authorization: Bearer header and forwards the request.
- Store the key in an environment variable or a secrets manager, not in the repository.
- Add a
.enventry to.gitignorebefore your first commit. - Use one key per environment so a leak in development does not touch production.
- Watch the
X-Balance-USDheader to catch runaway loops early. - Retry on HTTP 429 with a short wait. A temporary overload response includes
Retry-After: 5.
Prompts sent to the API are not used for training. Even so, avoid sending data you would not want to store in a log on your own side. If you want a deeper look at what such an API does and does not do, the myths and facts article covers common misunderstandings.