NovelAI Scripting API Documentation

Welcome to the NovelAI Scripting API documentation. Scripts allow you to extend NovelAI’s functionality with custom UI components, generation hooks, and document manipulation capabilities. They are written in TypeScript, a superset of JavaScript.

Getting Started

The User Scripts modal can be found in the goose menu in the left sidebar, or, when a story is selected, the advanced tab of the right sidebar. Alt+X will also open the modal.

This modal is where you will can import, create, and modify scripts. There are two levels of scripts, account and story. Account scripts are saved to the account and will be loaded when any story is selected. Story scripts are saved to the story file and will be loaded only when that story is loaded.

Sections

• API Reference

• Hooks

• Storage

• UI Extensions

• UI Parts

• Modals and Windows

• Document

• Generating Text

• Context Building

• Story Settings

• Lorebook

• Text-to-Speech

• Utilities

• Messaging

• Permissions

• Decorations

Architecture

Scripts are run executed in an insolated JavaScript interpreter in a Web Worker and can interact with NovelAI only through a set of predefined API methods. As scripts are run in a Web Worker, they don’t block the UI thread and won’t interrupt the main page while running. Because of this most API functions are asynchronous and return promises. If you’re unfamiliar with promises in JavaScript or need a refresher I recommend this page from the MDN Web Docs.

What You Can’t Do

For security and privacy reasons scripts don’t have free reign over the page. There are several things they cannot do. Scripts are not allowed to make arbitrary network requests, access most user account information, directly access the DOM, or alter parts of the page not designated for scripts.

Scripts Are Transient

Scripts can be unloaded at any time, such as when the user disables them, switches stories, or closes the User Scripts modal. Because of this scripts should avoid maintaining important state in memory. Instead they should use the Storage API to persist important data.

I’ve made the website unusable, how do I disable scripts?

If a rogue script has made the website unusable to the point where that script cannot be disabled through the User Scripts modal, you can disable all scripts by adding ?noscript=true to the end of the URL and reloading the page. This will prevent any scripts from loading, allowing you to access the User Scripts modal and disable or remove the problematic script.

Unhandled Promise Rejections

For various technical reasons, unhandled rejected promises in scripts will not show any error message in the UI or console. To avoid silent failures, make sure to properly handle errors in your scripts using .catch on promises or awaiting them in a try/catch block.