NovelAI

https://docs.novelai.net/en
Admin
NovelAI is an AI-powered platform offering advanced text generation, image generation, and scripting...
Tokens:145,855
Snippets:2,093
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initial Chat Example

Source: https://docs.novelai.net/en/text/chatformat

Provide a sample conversation start in Memory to guide the AI's conversational style. End the example with your character's line without a trailing newline.

```text
your_name: Hello.
bot_name: Hi!
your_name: How are you doing?
```

--------------------------------

### clearAll usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Example showing how to invoke the clearAll method to remove all decorations.

```javascript
// Clean up all decorations
api.v1.editor.decorations.clearAll();
```

--------------------------------

### createWidgets usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Example of batch creating multiple widgets using the createWidgets method.

```javascript
const widgets = await api.v1.editor.decorations.createWidgets([
  {
    type: "inline",
    position: { sectionId: 123, offset: 5 },
    content: [
      api.v1.ui.part.text({ text: "First widget" })
    ],
  },
  {
    type: "node",
    sectionId: 456,
    content: [
      api.v1.ui.part.text({ text: "Second widget" })
    ],
  }
]);
```

--------------------------------

### Get configuration value example

Source: https://docs.novelai.net/en/scripting/api-reference

Example usage of the get function to retrieve the player_name configuration.

```typescript
const player_name = await api.v1.config.get("player_name");
```

--------------------------------

### Memory Setup for Chat Style

Source: https://docs.novelai.net/en/text/chatformat

Add this to the start of your Memory to signal the AI to adopt a chat style. Ensure it's followed by your custom memory information.

```text
memory_information
***
[ Style: chat ]
```

--------------------------------

### Scene Setting Examples

Source: https://docs.novelai.net/en/text/specialsymbols

Examples of using square brackets to define time and location settings within the story.

```text
[ London, 1821 ]
```

```text
[ Woodstock, 1969, 22:30 ]
```

```text
[ New York, 1935, Night Club ]
```

```text
[ Monday, 8:00 A.M. ]
```

```text
[ Five Minutes Later ]
```

--------------------------------

### Example of a Randomizer Prompt Chunk

Source: https://docs.novelai.net/en/image/promptchunks

This example demonstrates how to create a Prompt Chunk that randomly selects from a list of camera angle tags. Ensure chunks are separated by commas, and double commas are automatically cleaned up.

```text
||facing viewer|from above|from behind|from below|from side|profile|dutch angle||,
```

--------------------------------

### Get System Prompt

Source: https://docs.novelai.net/en/scripting/story-settings-api

Retrieves the current system prompt, which provides instructions to the model. This prompt is placed at the start of the generation context.

```javascript
let prompt = await api.v1.systemPrompt.get();
api.v1.log(`Current system prompt: ${prompt}`);
```

--------------------------------

### read() Usage Example

Source: https://docs.novelai.net/en/scripting/api-reference

Example showing how to call the read method and the structure of the returned array.

```typescript
const messages = helper.read();
// Returns: [{ role: "user", content: "...", tokens: 10 }, ...]
```

--------------------------------

### larry.help usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Demonstrates how to call the help function with a question and custom callback options.

```javascript
api.v1.larry.help({
  question: "What would you like to do?",
  options: [
    { text: "Generate more", callback: () => api.v1.editor.generate() },
    { text: "Cancel", callback: () => {} }
  ]
});
```

--------------------------------

### Create multiple markers example

Source: https://docs.novelai.net/en/scripting/api-reference

Example usage of createMarkers to add both inline and node markers to the editor.

```javascript
const markers = await api.v1.editor.decorations.createMarkers([
  {
    type: "inline",
    from: { sectionId: 123, offset: 0 },
    to: { sectionId: 123, offset: 5 },
    style: { backgroundColor: "rgba(255, 0, 0, 0.2)" }
  },
  {
    type: "node",
    sectionId: 456,
    style: { backgroundColor: "rgba(0, 0, 255, 0.1)" }
  }
]);
```

--------------------------------

### Chapter Title Examples

Source: https://docs.novelai.net/en/text/specialsymbols

Examples of using square brackets for chapter titles.

```text
[ An Unexpected Quest ]
```

```text
[ The End of Many Things ]
```

```text
[ Into the Wastes ]
```

```text
[ Time Loop (3rd Restart) ]
```

```text
[ Prologue ]
```

```text
[ Epilogue ]
```

--------------------------------

### updateEntry usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Example showing how to update a lorebook entry's text and enabled status.

```typescript
await api.v1.lorebook.updateEntry(entryId, {
  text: "Updated lore text...",
  enabled: true
});
```

--------------------------------

### createMarker usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Demonstrates creating inline and node markers, as well as updating and disposing of a marker handle.

```javascript
// Inline marker (highlight text range)
const marker = await api.v1.editor.decorations.createMarker({
  type: "inline",
  from: { sectionId: 123, offset: 0 },
  to: { sectionId: 123, offset: 10 },
  style: { backgroundColor: "rgba(255, 0, 0, 0.2)" }
});

// Node marker (style entire paragraph)
const nodeMarker = await api.v1.editor.decorations.createMarker({
  type: "node",
  sectionId: 456,
  style: { backgroundColor: "rgba(0, 0, 255, 0.1)" }
});

// Later: update or remove
await marker.update({ style: { backgroundColor: "yellow" } });
await marker.dispose();
```

--------------------------------

### Style Tagging Examples

Source: https://docs.novelai.net/en/text/specialsymbols

Examples of using style tags to influence the AI's writing format.

```text
[ Style: essay, nonfiction ]
```

```text
[ Style: verbose ]
```

```text
[ Style: poetry ]
```

```text
[ Style: text adventure ]
```

```text
[ Style: chat ]
```

```text
[ Style: SFW ]
```

--------------------------------

### Create and manage an inline widget

Source: https://docs.novelai.net/en/scripting/api-reference

Example showing how to create an inline widget, update its content, and dispose of it.

```javascript
const widget = await api.v1.editor.decorations.createWidget({
  type: "inline",
  position: { sectionId: 123, offset: 5 },
  content: [
    api.v1.ui.part.button({
      text: "Button",
      callback: () => api.v1.log("Widget clicked!")
    })
  ],
});

// Later: update content or remove
await widget.update({
  content: [api.v1.ui.part.text({ text: "Updated!" })]
});
await widget.dispose();
```

--------------------------------

### Example: Opening a floating window

Source: https://docs.novelai.net/en/scripting/api-reference

Demonstrates how to open a new floating window with a specific title, dimensions, and text content.

```typescript
const win = await api.v1.ui.window.open({
  type: "window",
  title: "My Tool",
  defaultWidth: 400,
  defaultHeight: 300,
  content: [
    { type: "text", text: "Window content here" }
  ]
});
```

--------------------------------

### Knowledge Tagging Examples

Source: https://docs.novelai.net/en/text/specialsymbols

Examples of using knowledge tags to prompt the AI about specific subjects, including combined style tags.

```text
[ Knowledge: paradoxes ]
```

```text
[ Knowledge: anime in 90s ]
```

```text
[ Knowledge: CRPGs; Style: blog post ]
```

```text
[ Knowledge: supernatural; Style: podcast, transcript ]
```

--------------------------------

### getAll()

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves all items stored in the helper, including those before the current start position.

```APIDOC
## getAll()

### Description
Get all items stored in the helper, including those before the current start position.
```

--------------------------------

### Update comment bot configuration example

Source: https://docs.novelai.net/en/scripting/api-reference

Example usage of the update function to set the bot's name, state, visibility, and content.

```typescript
await api.v1.commentBot.update({
  name: "Euterpe",
  state: "speaking",
  visible: true,
  content: [{ type: "text", text: "I'm here to help!" }]
});
```

--------------------------------

### updateCategory usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Example showing how to update a lorebook category's name and enabled status.

```typescript
await api.v1.lorebook.updateCategory(categoryId, {
  name: "Updated Name",
  enabled: false
});
```

--------------------------------

### nodeState usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Demonstrates how to call nodeState and log information about the navigation path and document sections.

```javascript
const state = await api.v1.document.history.nodeState(someNodeId);
if (state) {
  api.v1.log(`Took ${state.backwardPath.length} steps back, ${state.forwardPath.length} forward`);
  api.v1.log(`Document at target has ${state.sections.length} sections`);
}
```

--------------------------------

### read()

Source: https://docs.novelai.net/en/scripting/api-reference

Reads all items in the current window and updates the start position. Trims items from the start if total tokens exceed the configured limits.

```APIDOC
## read()

### Description
Reads all items in the current window and updates the start position. If the total tokens exceed maxTokens + rolloverTokens, items are trimmed from the start until the total fits within maxTokens.

### Signature
`read(): RolloverHelperStoredItem<T>[]`

### Returns
Array of stored items (original objects with guaranteed tokens property)

### Example
```javascript
const messages = helper.read();
// Returns: [{ role: "user", content: "...", tokens: 10 }, ...]
```
```

--------------------------------

### Create a button component

Source: https://docs.novelai.net/en/scripting/api-reference

Example of creating a button component with an ID, display text, and a callback function.

```javascript
const btn = api.v1.ui.part.button({
  id: "myBtn",
  text: "Click me",
  callback: () => api.v1.log("Clicked!")
});
```

--------------------------------

### getRules

Source: https://docs.novelai.net/en/scripting/api-reference

Get all currently registered decoration rules.

```APIDOC
## getRules

### Signature
`function getRules(): Promise<DecorationRule[]>`

### Returns
- `Promise<DecorationRule[]>` - Promise resolving to array of rules.
```

--------------------------------

### Save file example

Source: https://docs.novelai.net/en/scripting/api-reference

Saves the provided string content to a file with the specified filename.

```javascript
await api.v1.file.save("example.txt", "Hello, world!");
```

--------------------------------

### Generate text using api.v1.generate

Source: https://docs.novelai.net/en/scripting/api-reference

Example of calling the generate method with a user prompt and generation parameters, then logging the result.

```javascript
const response = await api.v1.generate(
  [{ role: "user", content: "What is the difference between izti and aaaa?" }],
  { model: "glm-4-6", max_tokens: 100, temperature: 0.8 }
);
api.v1.log(response.choices[0].text);
```

--------------------------------

### Open a Modal Dialog

Source: https://docs.novelai.net/en/scripting/api-reference

Example of opening a modal with specific configuration options and using the returned object to close it later.

```typescript
const modal = await api.v1.ui.modal.open({
  type: "modal",
  title: "Settings",
  size: "medium",
  content: [
    { type: "text", text: "Configure your settings" }
  ]
});
// Later: modal.close();
```

--------------------------------

### get(key: string)

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves a value from storage based on the provided key.

```APIDOC
## get(key: string)

### Description
Retrieves a value from storage based on the provided key.

### Signature
`function get(key: string): Promise<any>`

### Parameters
- **key** (string) - Storage key

### Returns
- **Promise<any>** - Promise resolving to the stored value or undefined
```

--------------------------------

### Get all RolloverHelper items

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves all items stored in the helper, including those before the current start position.

```typescript
getAll(): RolloverHelperStoredItem<T>[]
```

--------------------------------

### Multi-Character Prompting with Pipe Syntax

Source: https://docs.novelai.net/en/image/multiplecharacters

An example of using the pipe character to separate the base prompt from individual character prompts.

```text
2girls, indoors, factory, night, fog, industrial lights, pipes, light particles, cardboard box, aesthetic, best quality, english text, text | girl, purple eyes, short hair, smile, open mouth, ruffled blouse, red blouse, pleated skirt, blonde hair, green scarf, hands on own hips, blunt bangs, blue skirt, medium skirt, small breasts, bob cut, target#pointing, long sleeves, red nails, fang, cowboy shot. She is being pointed at. | girl, very long hair, purple hair, curly hair, white jeans, white pants, golden shirt, cowboy shot, green eyes, turtleneck sweater, sleeveless turtleneck, side braid, medium breasts, sleeveless, ripped jeans, wavy mouth, blush, purple nails, open mouth, source#pointing at another, speech bubble. She is pointing at the other girl and scolding her. Text: Stop that!
```

--------------------------------

### Get author's note example

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current author's note and logs it to the console.

```typescript
const text = await api.v1.an.get();
api.v1.log("Current author's note:", text);
```

--------------------------------

### read()

Source: https://docs.novelai.net/en/scripting/api-reference

Reads items in the current window and updates the start position, trimming items if token limits are exceeded.

```APIDOC
## read()

### Description
Read all items in the current window and update the start position. If the total tokens exceed maxTokens + rolloverTokens, items are trimmed from the start until the total fits within maxTokens.
```

--------------------------------

### Get Prefill Text

Source: https://docs.novelai.net/en/scripting/story-settings-api

Retrieves the current prefill text, which is added to the start of the most recent assistant message to influence model responses.

```javascript
let prefill = await api.v1.prefill.get();
api.v1.log(`Current prefill: ${prefill}`);
```

--------------------------------

### larry.help(config)

Source: https://docs.novelai.net/en/scripting/api-reference

Displays Larry with a question and optional response buttons.

```APIDOC
## larry.help(config)

### Description
Show Larry with a question and optional response buttons. If no options are provided, Yes/No buttons will be shown with Yes triggering the normal larry generation behaviour.

### Signature
`function help(config: { question: string; options?: { text: string; callback: () => void }[]; [key: string]: any }): void`

### Parameters
- **config** (Object) - Required - Configuration object with question and options.

### Example
```javascript
api.v1.larry.help({
  question: "What would you like to do?",
  options: [
    { text: "Generate more", callback: () => api.v1.editor.generate() },
    { text: "Cancel", callback: () => {} }
  ]
});
```
```

--------------------------------

### Define scenario placeholders with %{}

Source: https://docs.novelai.net/en/text/specialsymbols

Use the %{} block at the top of a prompt to define placeholders that users fill when importing a .scenario file.

```text
%{
1placeholder[Larry]:Your Name:Write your name.
2placeholder[geese]:What do you prefer?:cats/dogs
}
```

--------------------------------

### Open a Simple Window

Source: https://docs.novelai.net/en/scripting/modals-and-windows

Use `api.v1.ui.window.open` to create a window. Windows are floating panels that allow UI interaction. The returned object allows programmatic control.

```javascript
let wndw = api.v1.ui.window.open({
  title: 'Example Window',
  content: [
    {
      type: 'text',
      text: 'This is an example window created by a script.'
    },
  ],
  defaultHeight: 300,
  defaultWidth: 400
});
```

--------------------------------

### removeParagraphs usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Example of calling the removeParagraphs function with an array of section IDs.

```javascript
await api.v1.document.removeParagraphs([404860073937026, 551077518188362, 842273775686437]);
```

--------------------------------

### removeParagraph usage example

Source: https://docs.novelai.net/en/scripting/api-reference

Example of calling the removeParagraph function with a specific section ID.

```javascript
await api.v1.document.removeParagraph(835897208155866);
```

--------------------------------

### window.open(options)

Source: https://docs.novelai.net/en/scripting/api-reference

Opens a new floating window and returns an object with methods to manage the window lifecycle.

```APIDOC
## window.open(options)

### Description
Open a new floating window.

### Signature
`function open(options: WindowOptions): Promise<{ update: (options: Partial<WindowOptions>) => Promise<void>, close: () => Promise<void>, isClosed: () => boolean, closed: Promise<void> }>`

### Parameters
- **options** (WindowOptions) - Required - Window configuration

### Returns
- **Promise<Object>** - Object with update and close methods and a promise that resolves when the window is closed

### Example
```javascript
const win = await api.v1.ui.window.open({
  type: "window",
  title: "My Tool",
  defaultWidth: 400,
  defaultHeight: 300,
  content: [
    { type: "text", text: "Window content here" }
  ]
});
```
```

--------------------------------

### get Function Signature

Source: https://docs.novelai.net/en/scripting/api-reference

Signature for the get function, which retrieves the current comment bot configuration.

```typescript
function get(): Promise<{
                name: string
                state: null | string
                visible: boolean
                content: UIPart[]
                image?: null | string
            }>
```

--------------------------------

### ATTG and Quality Level Initialization

Source: https://docs.novelai.net/en/text/specialsymbols

Example of initializing a story with ATTG tags and an optional quality level for Erato and Xialong models.

```text
[ Tags: London, 1820s, dragons; Genre: steampunk, drama ][ S: 4 ]
```

--------------------------------

### systemPrompt.get()

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current system prompt text.

```APIDOC
## function get(): Promise<string>

### Description
Get the current system prompt text.

### Returns
- **Promise<string>** - Promise resolving to the system prompt content

### Example
```javascript
const prompt = await api.v1.systemPrompt.get();
api.v1.log("System prompt:", prompt);
```
```

--------------------------------

### Get configuration value signature

Source: https://docs.novelai.net/en/scripting/api-reference

The signature for the get function used to retrieve configuration values by key.

```typescript
function get(key: string): Promise<any>
```

--------------------------------

### Rollover Helper Example

Source: https://docs.novelai.net/en/scripting/generation-api

This script demonstrates how to use the `createRolloverHelper` to manage context size in a chat window. It adds user messages, generates a response, and then adds the assistant's response back into the context, ensuring that the context stays within the defined limits by removing older messages when necessary.

```APIDOC
## `api.v1.createRolloverHelper`

### Description
Creates a helper object to manage context size for generations, implementing rollover logic to stay within token limits.

### Usage
```javascript
const rollover = api.v1.createRolloverHelper<ChatMessage>({
    maxTokens: MAX_TOKENS,
    rolloverTokens: ROLLOVER_TOKENS,
    model: MODEL
});

async function sendMessage(userInput: string) {
    if (!userInput.trim()) return;
    
    await rollover.add({ role: "user", content: userInput });
    updateDisplay();
    
    const messages: Message[] = [SYSTEM_MESSAGE, ...rollover.read()];
    
    const response = await api.v1.generate(messages, {
        model: MODEL,
        max_tokens: 200,
        temperature: 0.7
    });
    
    const assistantContent = response.choices[0]?.text ?? "(no response)";
    await rollover.add({ role: "assistant", content: assistantContent });
    updateDisplay();
}
```

### Parameters
- `maxTokens` (number): The maximum number of tokens allowed for the context.
- `rolloverTokens` (number): The number of tokens to reserve or remove when the limit is reached.
- `model` (string): The model identifier to use for generation.

### Methods
- `add(message)`: Adds a message to the context.
- `read()`: Returns the current context messages.
- `count()`: Returns the number of messages in the context.
- `totalTokens()`: Returns the total number of tokens in the context.
```

--------------------------------

### api.v1.systemPrompt.set

Source: https://docs.novelai.net/en/scripting/api-reference

Sets the system prompt for the current context.

```APIDOC
## api.v1.systemPrompt.set(prompt)

### Description
Sets the system prompt to the provided string value.

### Signature
`await api.v1.systemPrompt.set(prompt: string)`
```

--------------------------------

### createWidgets

Source: https://docs.novelai.net/en/scripting/api-reference

Batch create multiple widgets. Requires the 'editorDecorations' permission.

```APIDOC
## createWidgets

### Signature
`function createWidgets<T extends DecorationCreateWidgetOptions = DecorationCreateWidgetOptions>(options: T[]): Promise<DecorationWidgetHandle<T>[]>`

### Parameters
- **options** (T[]) - Array of widget creation options.

### Returns
- `Promise<DecorationWidgetHandle<T>[]>` - Promise resolving to array of widget handles.

### Example
```javascript
const widgets = await api.v1.editor.decorations.createWidgets([
  {
    type: "inline",
    position: { sectionId: 123, offset: 5 },
    content: [
      api.v1.ui.part.text({ text: "First widget" })
    ],
  },
  {
    type: "node",
    sectionId: 456,
    content: [
      api.v1.ui.part.text({ text: "Second widget" })
    ],
  }
]);
```
```

--------------------------------

### Insert Paragraph at Start

Source: https://docs.novelai.net/en/scripting/document-api

Inserts a new paragraph at the beginning of the document. Use section ID '0' to specify insertion at the start.

```javascript
api.v1.document.insertParagraphAfter(0, {
  text: 'This paragraph was inserted at the start of the document.',
});
```

--------------------------------

### Create a script panel

Source: https://docs.novelai.net/en/scripting/api-reference

Initializes a script panel with a specified ID, name, and content components.

```javascript
const panel = api.v1.ui.extension.scriptPanel({
  id: "myPanel",
  name: "My Tools",
  content: [
    api.v1.ui.part.text({ text: "Panel content" })
  ]
});
```

--------------------------------

### read() Method Signature

Source: https://docs.novelai.net/en/scripting/api-reference

Reads all items in the current window and updates the start position, trimming items from the start if the total tokens exceed maxTokens + rolloverTokens.

```typescript
read(): RolloverHelperStoredItem<T>[]
```

--------------------------------

### systemPrompt.set(text)

Source: https://docs.novelai.net/en/scripting/api-reference

Sets the system prompt text. Requires the 'storyEdit' permission.

```APIDOC
## function set(text: string): Promise<void>

### Description
Set the system prompt text. If set to undefined or an empty string, the default system prompt will be used. Requires the “storyEdit” permission.

### Parameters
- **text** (string) - The new system prompt content

### Returns
- **Promise<void>** - Promise that resolves when the system prompt is updated
```

--------------------------------

### extension.contextMenuButton(config)

Source: https://docs.novelai.net/en/scripting/api-reference

Creates a context menu button extension.

```APIDOC
## function extension.contextMenuButton(config)

### Description
Create a context menu button extension.

### Signature
`function contextMenuButton(config: Omit<UIExtensionContextMenuButton, 'type'>): UIExtensionContextMenuButton`

### Parameters
- **config** (Omit<UIExtensionContextMenuButton, ‘type’>) - Required - Context menu button configuration

### Returns
- **UIExtensionContextMenuButton** - A context menu button UIExtension
```

--------------------------------

### getMarker

Source: https://docs.novelai.net/en/scripting/api-reference

Get a marker by its unique ID.

```APIDOC
## getMarker

### Signature
`function getMarker(id: string): Promise<DecorationMarkerInfo | null>`

### Parameters
- **id** (string) - The marker ID.

### Returns
- `Promise<DecorationMarkerInfo | null>` - Promise resolving to marker info or null if not found.
```

--------------------------------

### list()

Source: https://docs.novelai.net/en/scripting/api-reference

Lists all keys currently in storage.

```APIDOC
## list()

### Description
List all keys in storage.

### Signature
`function list(): Promise<string[]>`

### Returns
- **Promise<string[]>** - Promise resolving to array of storage keys
```

--------------------------------

### list()

Source: https://docs.novelai.net/en/scripting/api-reference

Lists all keys currently stored in temporary storage.

```APIDOC
## list()

### Description
List all keys in temporary storage.

### Signature
`function list(): Promise<string[]>`

### Returns
- **Promise<string[]>** - Promise resolving to array of storage keys

### Example
```javascript
const keys = await api.v1.tempStorage.list();
api.v1.log("Stored keys:", keys);
```
```

--------------------------------

### getMarkers

Source: https://docs.novelai.net/en/scripting/api-reference

Get all markers created by the current script.

```APIDOC
## getMarkers

### Signature
`function getMarkers(): Promise<DecorationMarkerInfo[]>`

### Returns
- `Promise<DecorationMarkerInfo[]>` - Promise resolving to array of marker info.
```

--------------------------------

### get(key)

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves a value from story storage by its key.

```APIDOC
## get(key)

### Description
Get a value from story storage.

### Signature
`function get(key: string): Promise<any>`

### Parameters
- **key** (string) - Storage key

### Returns
- Promise<any> - Promise resolving to the stored value or undefined

### Example
```javascript
const count = await api.v1.storyStorage.get("runCount") || 0;
```
```

--------------------------------

### Get story title

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current story title.

```typescript
const title = await api.v1.story.title.get();
```

--------------------------------

### Get story description

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current story description.

```typescript
const description = await api.v1.story.description.get();
```

--------------------------------

### Get RolloverHelper configuration

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current configuration object for the helper.

```typescript
getConfig(): RolloverHelperConfig
```

--------------------------------

### Chat Window with Rollover Helper Example

Source: https://docs.novelai.net/en/scripting/generation-api

This script demonstrates how to use `api.v1.createRolloverHelper` to manage context size in a chat application. It automatically handles adding new messages and removing old ones to stay within token limits, ensuring efficient caching.

```typescript
/**
 * Simple Chat Window - Rollover Helper Example
 * This script creates a simple chat window that uses a rollover helper to manage context size.
 */

const MODEL = "glm-4-6";
const MAX_TOKENS = 2000;
const ROLLOVER_TOKENS = 500;

const SYSTEM_MESSAGE: Message = {
    role: "system",
    content: "You are a helpful assistant. Keep responses brief."
};

type ChatMessage = {
    role: "user" | "assistant";
    content: string;
};

const rollover = api.v1.createRolloverHelper<ChatMessage>({
    maxTokens: MAX_TOKENS,
    rolloverTokens: ROLLOVER_TOKENS,
    model: MODEL
});

async function sendMessage(userInput: string) {
    if (!userInput.trim()) return;
    
    await rollover.add({ role: "user", content: userInput });
    updateDisplay();
    
    const messages: Message[] = [SYSTEM_MESSAGE, ...rollover.read()];
    
    const response = await api.v1.generate(messages, {
        model: MODEL,
        max_tokens: 200,
        temperature: 0.7
    });
    
    const assistantContent = response.choices[0]?.text ?? "(no response)";
    await rollover.add({ role: "assistant", content: assistantContent });
    updateDisplay();
}

function updateDisplay() {
    const history = rollover.read();
    const chatText = history
        .map(m => `**${m.role}:** ${m.content}`)
        .join("\n\n");
    
    win.update({
        content: [
            { type: "text", id: "chat", markdown: true, text: chatText || "*No messages yet*" },
            {
                type: "textInput",
                id: "input",
                placeholder: "Type a message...",
                onSubmit: sendMessage
            },
            {
                type: "text",
                id: "status",
                text: `${rollover.count()} messages, ~${rollover.totalTokens()} tokens`,
                style: { opacity: 0.6, fontSize: "0.85em" }
            }
        ]
    });
}

const win = await api.v1.ui.window.open({
    title: "Chat (Rollover Demo)",
    defaultWidth: 400,
    defaultHeight: 300,
    resizable: true,
    content: []
});

updateDisplay();

```

--------------------------------

### Get story ID

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the unique identifier for the current story.

```typescript
const id = await api.v1.story.id();
```

--------------------------------

### Get Memory Content

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current story memory text.

```typescript
function get(): Promise<string>
```

```javascript
const mem = await api.v1.memory.get();
api.v1.log("Current memory:", mem);
```

--------------------------------

### systemPrompt.getDefault()

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the default system prompt text for the current model and story mode.

```APIDOC
## function getDefault(): Promise<string>

### Description
Get the default system prompt text for the current model and story mode.

### Returns
- **Promise<string>** - Promise resolving to the default system prompt content

### Example
```javascript
const defaultPrompt = await api.v1.systemPrompt.getDefault();
api.v1.log("Default system prompt:", defaultPrompt);
```
```

--------------------------------

### Get All Lorebook Categories

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves an array of all available lorebook categories.

```typescript
function categories(): Promise<LorebookCategory[]>
```

--------------------------------

### Get Script ID

Source: https://docs.novelai.net/en/scripting/messaging-api

Retrieves the unique ID of the current script.

```APIDOC
## Get Script ID

### Description
Retrieves the ID of the current script.

### Method
`api.v1.script.id`

### Response
#### Success Response (string)
- **id** (string) - The unique identifier for the current script.

### Request Example
```javascript
api.v1.log(`My script ID: ${api.v1.script.id}`);
```
```

--------------------------------

### getAll()

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves all items stored in the helper.

```APIDOC
## getAll()

### Description
Get all items stored in the helper, including those before the current start position.

### Signature
`getAll(): RolloverHelperStoredItem<T>[]`

### Returns
Array of all stored items
```

--------------------------------

### Register onGenerationEnd Hook

Source: https://docs.novelai.net/en/scripting/api-reference

Example of registering the onGenerationEnd hook using api.v1.hooks.register.

```javascript
api.v1.hooks.register("onGenerationEnd", (params) => {
  // Do something after generation ends
});
```

--------------------------------

### Get theme information

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current theme object and logs its properties.

```javascript
const theme = await api.v1.theme.get();
api.v1.log(theme.name); // "NovelAI Dark"
api.v1.log(theme.colors.bg0); // "#000000"
api.v1.log(theme.fonts.default); // "Source Sans Pro"
```

--------------------------------

### System Utilities

Source: https://docs.novelai.net/en/scripting/api-reference

General system utilities including timers, tokenization, and TTS.

```APIDOC
## System Utilities

- `api.v1.timers` (clearTimeout, setTimeout, sleep)
- `api.v1.tokenizer` (decode, encode)
- `api.v1.tts` (pause, queue, resume, speak, stop, togglePause)
```

--------------------------------

### Create a container component

Source: https://docs.novelai.net/en/scripting/api-reference

Creates a container UIPart using the provided configuration.

```typescript
function container(config: Omit<UIPartContainer, 'type'>): UIPartContainer
```

--------------------------------

### Get current prefill text

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current prefill text as a promise.

```typescript
function get(): Promise<string>
```

```typescript
const text = await api.v1.prefill.get();
api.v1.log("Current prefill:", text);
```

--------------------------------

### Create a text display component

Source: https://docs.novelai.net/en/scripting/api-reference

Creates a text display UIPart using the provided configuration.

```typescript
function text(config: Omit<UIPartText, 'type'>): UIPartText
```

--------------------------------

### Get logprobs function signature

Source: https://docs.novelai.net/en/scripting/api-reference

Signature for retrieving the current logprobs information.

```typescript
function get(): Promise<{ logprobs: Logprobs[]; model: string } | null>
```

--------------------------------

### Get current generation parameters

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current generation parameters as a promise.

```typescript
function get(): Promise<{
                model: string
                max_tokens?: number
                temperature?: number
                top_p?: number
                top_k?: number
                frequency_penalty?: number
                presence_penalty?: number
                min_p?: number
            }>
```

--------------------------------

### Get current selection range

Source: https://docs.novelai.net/en/scripting/api-reference

Retrieves the current selection range in the editor.

```typescript
function get(): Promise<DocumentSelection>
```

--------------------------------

### Create an image component

Source: https://docs.novelai.net/en/scripting/api-reference

Creates an image UIPart using the provided configuration.

```typescript
function image(config: Omit<UIPartImage, 'type'>): UIPartImage
```

--------------------------------

### modal.open(options)

Source: https://docs.novelai.net/en/scripting/api-reference

Opens a new modal dialog with the specified configuration options. Returns an object containing methods to update or close the modal.

```APIDOC
## modal.open(options)

### Description
Opens a new modal dialog. Returns a promise that resolves to an object with control methods.

### Signature
`function open(options: ModalOptions): Promise<{ update: (options: Partial<ModalOptions>) => Promise<void>, close: () => Promise<void>, isClosed: () => boolean, closed: Promise<void> }>`

### Parameters
- **options** (ModalOptions) - Required - Modal configuration

### Returns
- **Promise** - Object with update and close methods and a promise that resolves when the modal is closed

### Example
```javascript
const modal = await api.v1.ui.modal.open({
  type: "modal",
  title: "Settings",
  size: "medium",
  content: [
    { type: "text", text: "Configure your settings" }
  ]
});
// Later: modal.close();
```
```

--------------------------------

### Registering onResponse Hook

Source: https://docs.novelai.net/en/scripting/api-reference

Example of registering the onResponse hook to modify generated text.

```javascript
api.v1.hooks.register("onResponse", (params) => {
  // Modify generated text
  const modified = params.text.map(t => t.replace(/bad word/g, "****"));
  return { text: modified };
});
```

--------------------------------

### createMarkers

Source: https://docs.novelai.net/en/scripting/api-reference

Batch create multiple markers in the editor. Requires 'editorDecorations' permission.

```APIDOC
## createMarkers

### Description
Batch create multiple markers. Requests the “editorDecorations” permission.

### Signature
`function createMarkers(options: (DecorationCreateInlineMarkerOptions | DecorationCreateNodeMarkerOptions)[]): Promise<DecorationMarkerHandle[]>`

### Parameters
- **options** ((DecorationCreateInlineMarkerOptions | DecorationCreateNodeMarkerOptions)[]) - Required - Array of marker creation options.

### Returns
- **Promise<DecorationMarkerHandle[]>** - Promise resolving to array of marker handles.

### Example
```javascript
const markers = await api.v1.editor.decorations.createMarkers([
  {
    type: "inline",
    from: { sectionId: 123, offset: 0 },
    to: { sectionId: 123, offset: 5 },
    style: { backgroundColor: "rgba(255, 0, 0, 0.2)" }
  },
  {
    type: "node",
    sectionId: 456,
    style: { backgroundColor: "rgba(0, 0, 255, 0.1)" }
  }
]);
```
```

--------------------------------

### Register onGenerationRequested Hook

Source: https://docs.novelai.net/en/scripting/api-reference

Example of registering the onGenerationRequested hook to potentially prevent generation.

```javascript
api.v1.hooks.register("onGenerationRequested", ({ model, generationPosition }) => {
   // Do something
   return { stopGeneration: true }; // Prevent generation
});
```

--------------------------------

### Schedule a delayed callback

Source: https://docs.novelai.net/en/scripting/api-reference

Example of using setTimeout to log a message after 1000 milliseconds.

```javascript
const timerId = await api.v1.timers.setTimeout(() => {
  api.v1.log("Delayed message");
}, 1000);
```

--------------------------------

### createWidget

Source: https://docs.novelai.net/en/scripting/api-reference

Create a new inline widget to render UI components at a specific position. Requires 'editorDecorations' permission.

```APIDOC
## createWidget

### Description
Create a new inline widget. Widgets render UI components at a specific position in the document. Requests the “editorDecorations” permission.

### Signature
`function createWidget<T extends DecorationCreateWidgetOptions = DecorationCreateWidgetOptions>(options: T): Promise<DecorationWidgetHandle<T>>`

### Parameters
- **options** (T) - Required - Widget creation options.

### Returns
- **Promise<DecorationWidgetHandle<T>>** - Promise resolving to a widget handle.

### Example
```javascript
const widget = await api.v1.editor.decorations.createWidget({
  type: "inline",
  position: { sectionId: 123, offset: 5 },
  content: [
    api.v1.ui.part.button({
      text: "Button",
      callback: () => api.v1.log("Widget clicked!")
    })
  ],
});

// Later: update content or remove
await widget.update({ content: [api.v1.ui.part.text({ text: "Updated!" })] });
await widget.dispose();
```
```

--------------------------------

### Log function usage

Source: https://docs.novelai.net/en/scripting/api-reference

Example of calling the log function with a message and a timestamp object.

```javascript
api.v1.log("Script started", { timestamp: Date.now() });
```

--------------------------------

### Set author's note example

Source: https://docs.novelai.net/en/scripting/api-reference

Updates the author's note content.

```typescript
await api.v1.an.set("[ Style: descriptive and atmospheric ]");
```

--------------------------------

### container

Source: https://docs.novelai.net/en/scripting/api-reference

Creates a container component.

```APIDOC
## container

### Description
Creates a container component.

### Signature
`function container(config: Omit<UIPartContainer, 'type'>): UIPartContainer`

### Parameters
- **config** (Omit<UIPartContainer, ‘type’>) - Required - Container configuration

### Returns
- **UIPartContainer** - A container UIPart
```

--------------------------------

### Character Viewpoint Switching

Source: https://docs.novelai.net/en/text/specialsymbols

Examples of using square brackets to indicate character viewpoints.

```text
[ John ]
```

```text
[ Batman ]
```

--------------------------------

### button(config)

Source: https://docs.novelai.net/en/scripting/api-reference

Creates a button component.

```APIDOC
## button(config)

### Description
Create a button component.

### Signature
`function button(config: Omit<UIPartButton, 'type'>): UIPartButton`

### Parameters
- **config** (Omit<UIPartButton, 'type'>) - Button configuration

### Returns
- **UIPartButton** - A button UIPart

### Example
```javascript
const btn = api.v1.ui.part.button({
  id: "myBtn",
  text: "Click me",
  callback: () => api.v1.log("Clicked!")
});
```
```
Tokens:
Raw