{"id":22446773,"url":"https://github.com/realcoloride/node_characterai","last_synced_at":"2025-05-15T00:07:49.952Z","repository":{"id":65702732,"uuid":"597714985","full_name":"realcoloride/node_characterai","owner":"realcoloride","description":"Unofficial Character AI wrapper for node.","archived":false,"fork":false,"pushed_at":"2025-04-18T06:44:39.000Z","size":458,"stargazers_count":367,"open_issues_count":9,"forks_count":81,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-12T19:08:50.518Z","etag":null,"topics":["ai","api","character","characterai","node","unofficial","wrapper"],"latest_commit_sha":null,"homepage":"https://character.ai/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/realcoloride.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-02-05T12:24:47.000Z","updated_at":"2025-05-10T01:31:33.000Z","dependencies_parsed_at":"2023-02-19T09:01:31.583Z","dependency_job_id":"d6fba9a1-76a8-4a91-ab90-f1897619be22","html_url":"https://github.com/realcoloride/node_characterai","commit_stats":{"total_commits":36,"total_committers":1,"mean_commits":36.0,"dds":0.0,"last_synced_commit":"54998816f4d8be2c883210affbe968e1d284ae23"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realcoloride%2Fnode_characterai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realcoloride%2Fnode_characterai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realcoloride%2Fnode_characterai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/realcoloride%2Fnode_characterai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/realcoloride","download_url":"https://codeload.github.com/realcoloride/node_characterai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254249197,"owners_count":22039029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","api","character","characterai","node","unofficial","wrapper"],"created_at":"2024-12-06T04:11:19.200Z","updated_at":"2025-05-15T00:07:44.936Z","avatar_url":"https://github.com/realcoloride.png","language":"JavaScript","funding_links":["https://ko-fi.com/coloride"],"categories":[],"sub_categories":[],"readme":"\u003e [!WARNING]\r\n\u003e 🔧 **This version will be deprecated soon.**\r\n\u003e\r\n\u003e ⭐ I am transitioning to the `2.0` version, currently in beta. Whenever the stable version of `2.0` comes out, it will be actively merged and the previous `1.x` will be deprecated.\r\n\u003e\r\n\u003e ℹ️ **So please be ready to update your code and migrate as soon as you can**, or if you wish to get used to the changes to avoid a code rewrite soon, **please consider using the `beta`**, but make sure to give me your feedback and report back on your problems. **Your feedback matters.**\r\n\u003e \r\n\u003e 👍 If you just want to see the branch, [click here](https://github.com/realcoloride/node_characterai/tree/2.0).\r\n\u003e \r\n\u003e ❓ If you want to let me know your feedback or report issues, [click here to open the related issue](https://github.com/realcoloride/node_characterai/issues/180).\r\n\r\n# Character AI Unofficial Node API\r\n\r\n\u003e Node.js client for the unofficial [Character AI API](https://character.ai/), an awesome website which brings characters to life with AI!\r\n\r\n## Intro\r\n\r\nThis repository is inspired by [RichardDorian's unofficial node API](https://github.com/RichardDorian/node-character.ai/).\r\nThough, I found it hard to use and it was not really stable and archived. So I remade it in javascript.\r\n\r\n**This project is not affiliated with Character AI in any way! It is a community project.**\r\nThe purpose of this project is to bring and build projects powered by Character AI.\r\n\r\nIf you like this project, please check their [website](https://character.ai/).\r\n\r\n## Features\r\n\r\n* 👍 Fully written in Javascript and CommonJS (for max compatibility and ease of use)\r\n* ⌚ Asynchronous requests\r\n* 🗣️ Use conversations or use the API to fetch information\r\n* 🧸 Easy to use\r\n* 🔁 Active development\r\n* 👤 Guest \u0026 token login support\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install node_characterai\r\n```\r\n\r\n## Usage\r\n\r\nBasic guest authentication and message:\r\n\r\n```javascript\r\nconst CharacterAI = require(\"node_characterai\");\r\nconst characterAI = new CharacterAI();\r\n\r\n(async () =\u003e {\r\n  // Authenticating as a guest (use `.authenticateWithToken()` to use an account)\r\n  await characterAI.authenticateAsGuest();\r\n\r\n  // Place your character's id here\r\n  const characterId = \"8_1NyR8w1dOXmI1uWaieQcd147hecbdIK7CeEAIrdJw\";\r\n\r\n  // Create a chat object to interact with the conversation\r\n  const chat = await characterAI.createOrContinueChat(characterId);\r\n\r\n  // Send a message\r\n  const response = await chat.sendAndAwaitResponse(\"Hello discord mod!\", true);\r\n\r\n  console.log(response);\r\n  // Use `response.text` to use it as a string\r\n})();\r\n```\r\n\r\n## Using an Access Token\r\n\r\nSome parts of the API (like managing a conversation) require you to be logged in using a `sessionToken`.\r\n\r\nTo get it, you can open your browser, go to the [Character.AI website](https://character.ai) in `localStorage`.\r\n\r\n\u003e [!IMPORTANT]  \r\n\u003e If you are using old versions of the package and are getting a `Authentication token is invalid`, you now again need a `sessionToken` to authenticate (as of update `1.2.5` and higher). See below.\r\n\u003e \r\n\u003e **If you are using something that is using the package and has not updated to the latest version in a while, make sure to update the package by doing `npm update node_characterai` or manually copying the files or open a respective issue to their package (if they have one).**\r\n\r\n---\r\n### ⚠️ WARNING: DO NOT share your session token to anyone you do not trust or if you do not know what you're doing. \r\n#### _Anyone with your session token could have access to your account without your consent. Do this at your own risk._\r\n---\r\n\r\n### On PC:\r\n1. Open the Character.AI website in your browser (https://beta.character.ai)\r\n2. Open the developer tools (\u003ckbd\u003eF12\u003c/kbd\u003e, \u003ckbd\u003eCtrl+Shift+I\u003c/kbd\u003e, or \u003ckbd\u003eCmd+J\u003c/kbd\u003e)\r\n3. Go to the `Application` tab\r\n4. Go to the `Storage` section and click on `Local Storage`\r\n5. Look for the `char_token` key\r\n6. Open the object, right click on value and copy your session token.\r\n\r\n![Session_Token](https://github.com/realcoloride/node_characterai/assets/108619637/1d46db04-0744-42d2-a6d7-35152b967a82)\r\n\r\n### On Mobile:\r\n\r\n1. Open the Character.AI website in your browser on the OLD interface (https://old.character.ai/)\r\n2. Open the URL bar, write `javascript:` (case sensitive) and paste the following:\r\n```javascript\r\n(function(){let e=window.localStorage[\"char_token\"];if(!e){alert(\"You need to log in first!\");return;}let t=JSON.parse(e).value;document.documentElement.innerHTML=`\u003cdiv\u003e\u003ci\u003e\u003cp\u003eprovided by node_characterai - \u003ca href=\"https://github.com/realcoloride/node_characterai?tab=readme-ov-file#using-an-access-token\"\u003eclick here for more information\u003c/a\u003e\u003c/p\u003e\u003c/i\u003e\u003cp\u003eHere is your session token:\u003c/p\u003e\u003cinput value=\"${t}\" readonly\u003e\u003cp\u003e\u003cstrong\u003eDo not share this with anyone unless you know what you are doing! This is your personal session token. If stolen or requested by someone you don't trust, they could access your account without your consent; if so, please close the page immediately.\u003c/strong\u003e\u003c/p\u003e\u003cbutton id=\"copy\" onclick=\"navigator.clipboard.writeText('${t}'); alert('Copied to clipboard!')\"\u003eCopy session token to clipboard\u003c/button\u003e\u003cbutton onclick=\"window.location.reload();\"\u003eRefresh the page\u003c/button\u003e\u003c/div\u003e`;localStorageKey=null;storageInformation=null;t=null;})();\r\n```\r\n3. The following page should appear:\r\n![Access_Token_Mobile](https://github.com/realcoloride/node_characterai/assets/108619637/2954586c-5dab-4e1c-820c-4e8528653d14)\r\n\r\n4. Click the respective buttons to copy your access token or id token to your clipboard.\r\n---\r\n\r\nWhen using the package, you can:\r\n* Login as guest using `authenticateAsGuest()` - *for mass usage or testing purposes*\r\n* Login with your account or a token using `authenticateWithToken()` - *for full features and unlimited messaging*\r\n\r\n## Finding your character's ID\r\n\r\nYou can find your character ID in the URL of a Character's chat page.\r\n\r\nFor example, if you go to the chat page of the character `Discord Moderator` you will see the URL `https://beta.character.ai/chat?char=8_1NyR8w1dOXmI1uWaieQcd147hecbdIK7CeEAIrdJw`.\r\n\r\nThe last part of the URL is the character ID:\r\n![Character_ID](https://i.imgur.com/nd86fN4.png)\r\n\r\n## Image Interactions\r\n### WARNING: This part is currently experimental, if you encounter any problem, open an [**Issue**](https://github.com/realcoloride/node_characterai/issues).\r\n\r\n🖼️ Character AI has the ability to generate and interpret images in a conversation. Some characters base this concept into special characters, or maybe use it for recognizing images, or to interact with a character and give it more details on something: *the possibilities are endless*.\r\n\r\n💁 Most of the Character AI image features can be used like so:\r\n\r\n```javascript\r\n// Most of these functions will return you an URL to the image\r\nawait chat.generateImage(\"dolphins swimming in green water\");\r\nawait chat.uploadImage(\"https://www.example.com/image.jpg\");\r\nawait chat.uploadImage(\"./photos/image.jpg\");\r\n\r\n// Other supported types are Buffers, Readable Streams, File Paths, and URLs\r\nawait chat.uploadImage(imageBuffer);\r\n\r\n// Including the image relative path is necessary to upload an image\r\nawait chat.sendAndAwaitResponse({\r\n  text: \"What is in this image?\",\r\n  image_rel_path: \"https://www.example.com/coffee.jpg\",\r\n  image_description: \"This is coffee.\",\r\n  image_description_type: \"HUMAN\" // Set this if you are manually saying what the AI is looking at\r\n}, true);\r\n```\r\n*Props to @creepycats for implementing most of this stuff out*\r\n\r\n## Troubleshooting\r\n\r\n|**Problem**|Answer|\r\n|-------|------|\r\n|❌ **Token was invalid**|Make sure your token is actually valid and you copied your entire token (its pretty long) or, you have not updated the package.|\r\n|⚠️ **The specified Chromium path for puppeteer could not be located**|On most systems, puppeteer will automatically locate Chromium. But on certain distributions, the path has to be specified manually. This warning occurs if `node_characterai` could not locate Chromium on linux (*/usr/bin/chromium-browser*), and will error if puppeteer cannot locate it automatically. See [this](#specifying-chromiums-path) for a fix.|\r\n|😮 **Why are chromium processes opening?**|This is because as of currently, the simple fetching is broken and I use puppeteer (a chromium browser control library) to go around cloudflare's restrictions.|\r\n|👥 **`authenticateAsGuest()` doesn't work**|See issue [#14](https://github.com/realcoloride/node_characterai/issues/14).|\r\n|🦒 **Hit the max amount of messages?**|Sadly, guest accounts only have a limited amount of messages before they get limited and forced to login. See below for more info 👇|\r\n|🪐 **How to use an account to mass use the library?**|You can use **conversations**, a feature introduced in `1.0.0`, to assign to users and channels. **To reproduce a conversation, use OOC (out of character) to make the AI think you're with multiple people.** __See an example here:__ ![chrome_RDbmXXtFNl](https://user-images.githubusercontent.com/108619637/224778145-284dd89e-7960-499c-b0f0-0deca419c578.png)![chrome_BgF8crPvqC](https://user-images.githubusercontent.com/108619637/224778153-c2a42a26-c5f7-4148-9644-34353482833e.png) (Disclaimer: on some characters, their personality will make them ignore any OOC request). |\r\n|🏃 **How do I avoid concurrency and crashes when using more than one request at a time?**|Check the solution found by @SeoulSKY [here](https://github.com/realcoloride/node_characterai/issues/157#issuecomment-2005709711) using `async-mutex`.|\r\n|📣 **Is this official?**|No, this project is made by a fan of the website and is unofficial. *To support the developers, please check out [their website](https://beta.character.ai)*.|\r\n|😲 **Did something awesome with `node_characterai`?**|Please let me know!|\r\n|✉️ **Want to contact me?**|See my profile|\r\n|☕ **Want to support me?**|You can send me a coffee on ko.fi: https://ko-fi.com/coloride. Many thanks!|\r\n|💡 **Have an idea?**|Open an issue in the [**Issues**](https://github.com/realcoloride/node_characterai/issues) tab|\r\n|➕ **Other issue?**|Open an issue in the [**Issues**](https://github.com/realcoloride/node_characterai/issues) tab|\r\n\r\n## In-depth troubleshooting\r\n#### **🤚 Before you scroll, please know that:**\r\n* In the `Client` class, you can access the `Requester` class and define puppeteer or other variables related to how CharacterAI will work using `characterAI.requester.(property)`. *Also, anything here is subject to change, so make sure to update the package frequently.*\r\n\r\n### 💳 About CharacterAI+\r\n#### **\"I am a member of cai+, how do I use it?\"**\r\n\r\nChange the property `.usePlus` from the requester and if needed, change `.forceWaitingRoom`.\r\n\r\nFor example:\r\n```javascript\r\n// Default is `false`\r\ncharacterAI.requester.usePlus = true;\r\n```\r\n\r\n### 🧭 About Puppeteer\r\nAround a few months ago, the package only required the `node-fetch` module to run. The package was made using simple API requests.\r\n\r\n*However, over time, Cloudflare started fighting against scraping and bots, which also made it almost impossible for anyone to use this package.*\r\n\r\n**This is where in versions 1.1 and higher, puppeteer is used (which uses a chromium browser) to make requests with the API.**\r\n\r\n### ⚙️ How to change Puppeteer settings\r\n **👉 IMPORTANT: do the changes *before* you initialize your client!**\r\n\r\nIn the CharacterAI class, you can access the requester and define the `.puppeteerPath` variable or other arguments, and the properties include *(and are subject to change in future versions)*:\r\n```javascript\r\n// Chromium executable path (in some linux distributions, /usr/bin/chromium-browser)\r\npuppeteerPath;\r\n// Default arguments for when the browser launches\r\npuppeteerLaunchArgs;\r\n// Boolean representing the default timeout (default is 30000ms)\r\npuppeteerNoDefaultTimeout;\r\n// Number representing the default protocol timeout\r\npuppeteerProtocolTimeout;\r\n```\r\n\r\n##### Specifying Chromium's path\r\n🐧 For linux users, if your puppeteer doesn't automatically detect the path to Chromium, you will need to specify it manually.\r\n\r\nTo do this, you just need to set `puppeteerPath` to your Chromium path:\r\n```javascript\r\ncharacterAI.puppeteerPath = \"/path/to/chromium-browser\";\r\n```\r\n\r\nOn Linux, you can use the `which` command to find where Chromium is installed:\r\n```bash\r\n$ which chromium-browser # or whatever command you use to launch chrome\r\n```\r\n\r\n💡 I recommend that you __frequently__ update this package for bug fixes and new additions.\r\n\r\n## Disclaimer\r\n##### ❤️ This project is updated frequently, **always check for the latest version for new features or bug fixes**.\r\n\r\n🚀 If you have an issue or idea, let me know in the [**Issues**](https://github.com/realcoloride/node_characterai/issues) section.\r\n\r\n📜 If you use this API, you also bound to the terms of usage of their website.\r\n\r\n*(real)coloride - 2023-2024, Licensed MIT.*\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealcoloride%2Fnode_characterai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frealcoloride%2Fnode_characterai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frealcoloride%2Fnode_characterai/lists"}