An unofficial asynchronous Python api wrapper for Character AI using curl-cffi.

This library is based on the Character AI Unofficial Node API, made by realcoloride.

If you have any questions, problems, suggestions, please contact me:

📚 Documentation.

pip install PyCharacterAI

First, import and create a new instance of the Client class:

from PyCharacterAI import Client


client = Client()

You can use client = Client(use_plus=True) if you have character ai plus.

This library allows you to authenticate in two ways:

1. As a guest (Some api features are not available):

await client.authenticate_as_guest()

2. Using a token:

token = 'TOKEN'
await client.authenticate_with_token(token)

Instructions for getting a token:

1. Open the Character AI website in your browser
2. Open the developer tools F12 and go to the Application tab.
3. Go to the Storage section and click on Local Storage.
4. Look for the char_token key.
5. Copy value.

⚠️ Warning! Do not share this token with anyone!

import asyncio
from PyCharacterAI import Client

token = "TOKEN"


async def main():
    client = Client()
    await client.authenticate_with_token(token)

    username = (await client.fetch_user())['user']['username']
    print(f'Authenticated as {username}')

    character_id = "iV5qb8ttzD7Ytl69U_-ONcW2tW_lrFrOVKExyKJHlJM"  # Lily (by @landon)
    chat = await client.create_or_continue_chat(character_id)

    while True:
        message = input(f'{username}: ')  # In: Hi!

        answer = await chat.send_message(message)
        print(f"{answer.src_character_name}: {answer.text}")  # Out: hello there! what kind of question you gonna ask me ? i'm here to assist you :)


asyncio.run(main())

We'll get a link to the image on the Character AI server, which we can use for our own purposes: attach it to a message, download it, etc.

1. We can generate an image from a prompt:

prompt = "Prompt"

url = await client.generate_image(prompt)

2. We can upload our own image:

image = "URL or path to the image"

url = (await client.upload_image(image))['response']

Available image formats: PNG, JPEG, WEBP.

We can synthesize audio from text using one of several voices (Text to Speech)

A list of available voices

text = "Hi all ! This is PyCharacterAI. PyCharacterAI is An unofficial asynchronous api wrapper for Character AI. For Python."
voice = 22 # Anime Girl (F) (en-US)

audio = await client.generate_voice(voice, text)

It'll return BytesIO, which we can use:

filepath = "voice.mp3"  # Path to the directory where you want to save the audio

with open(filepath, 'wb') as f:
   f.write(audio.read())