A Node.js client for the unofficial Character AI API, an incredible website that uses AI to bring characters to life!
Please note that this project is not affiliated with Character AI in any way. It is a community-driven initiative aimed at unleashing the potential of projects powered by Character AI.
If you enjoy this project, I encourage you to visit their website.
- ⌚ Supports asynchronous requests.
- 🗣️ Enables conversational interactions and information retrieval through the API.
- 🧸 User-friendly and straightforward to utilize.
- 🔁 Actively developed and regularly updated.
- 👤 Supports both guest and token login.
To install the Character.ai API, follow the standard installation procedures.
Here is an example of basic guest authentication and messaging:
// Your code here
Using an Access Token
Certain parts of the API, such as managing conversations, require you to log in using an access token. To obtain one, follow these steps:
- Open Character.AI’s website in your browser (https://beta.character.ai).
- Open the developer tools (F12, Ctrl+J, or Cmd+J).
- Go to the Application tab.
- Navigate to the Storage section and click on Local Storage.
- Look for the
@@auth0spajs@@::dyD3gE281MqgISG7FuIXYhL2WEknqZzv::https://auth0.character.ai/::openid profile email offline_access keyentry.
- Expand the entry and copy the access token.
Once you have obtained the access token, you can use it in the package’s functionality, as explained below:
- To log in as a guest, use the
authenticateAsGuest()function. This is suitable for mass usage or testing purposes.
- To log in with your account or a token, use the
authenticateWithToken()function. This provides access to full features and unlimited messaging capabilities.
Finding your character’s ID
You can easily find your character’s ID in the URL of their chat page. For example, if the character’s name is “Test Character,” the URL will be in the format
The character ID is the last part of the URL:
Character ID: 8_1NyR8w1dOXmI1uWaieQcd147hecbdIK7CeEAIrdJw
WARNING: Experimental Feature
Please note that this section is currently experimental. If you encounter any issues, please open an issue on the platform.
Character AI possesses the remarkable ability to generate and interpret images within a conversation. Some characters leverage this capability to create special characters, recognize images, or interact with users by providing more specific details. The possibilities are endless!
You can seamlessly integrate most of the Character AI image features. Special thanks to @creepycats for implementing many of these features.
Here are some common issues you may encounter while using the Character.ai API:
- ❌ Token was invalid: Ensure that your token is valid and that you have copied the entire token (they can be quite long).
- 😮 Why are Chromium processes opening?: Due to current limitations in the simple fetching mechanism, I employ Puppeteer, a chromium browser control library, to bypass Cloudflare’s restrictions.
- 🦒 authenticateAsGuest() doesn’t work: Check issue #14 for details.
- 🪐 Hit the max amount of messages?: Unfortunately, guest accounts have a limited number of messages before being restricted and prompting users to log in. Refer to the documentation for more information.
- 📣 How to use an account to mass use the library?: You can leverage conversations, a feature introduced in version 1.0.0, to assign to users and channels. To replicate a conversation, use OOC (out of character) messages to make the AI perceive multiple participants. Please see the example below:
(Note: Some characters may ignore OOC requests due to their personality traits.)
- 😲 Is this official?: No, this project is an unofficial fan endeavor. To support the developers, please visit their website.
- ✉️ Did something amazing with node_characterai?: Please let me know!
- 💡 Want to contact me?: Feel free to check out my profile.
- ➕ Have an idea?: Open an issue in the Issues tab.
- ➕ Other issue?: Open an issue in the Issues tab.
Before diving into the in-depth troubleshooting section, please remember the following:
- In the Client class, you can access the Requester class to define puppeteer or other variables related to how Character AI will work using
characterAI.requester.property. Please note that these details are subject to change, so remember to keep the package updated.
If you are a member of cai+, you may have questions about how to use it. To utilize cai+, modify the
.usePlus property in the requester and, if necessary, adjust the
.forceWaitingRoom property as well.
// Your code here
A few months ago, this package only required the node-fetch module to function. The package was designed around making simple API requests.
However, over time, Cloudflare enhanced its efforts to combat scraping and bots, which made it nearly impossible to use this package. To address this challenge, versions 1.1 and above leverage Puppeteer (which uses a chromium browser) to make API requests.
Customizing Puppeteer Settings
IMPORTANT: Make any changes to Puppeteer settings before initializing the client!
In the CharacterAI class, you can access the requester and define the
.puppeteerPath variable and other arguments. These properties are subject to change in future versions.
Ensure that you regularly update this package to access bug fixes and new additions.
❤️ This project is frequently updated, so please check for the latest version to access new features and bug fixes.
🚀 If you encounter any issues or have ideas for improvement, please share them in the Issues section.
📜 By using this API, you are bound to the terms of usage specified by the Character AI website.
(real)coloride – 2023, Licensed MIT.