---
title: "LyricWinter API and MCP server"
description: "Build with LyricWinter Studio from code or from an AI agent. The REST API (beta) and the remote MCP server turn stories into fully cast, multi-voice audio."
canonical_url: https://lyricwinter.com/docs
markdown_url: https://lyricwinter.com/docs.md
last_updated: 2026-09-30
status: beta
---
# LyricWinter API and MCP server

> Build with LyricWinter Studio from code or from an AI agent. The REST API (beta) and the remote MCP server turn stories into fully cast, multi-voice audio.

LyricWinter turns written stories into fully cast audio: every character gets a distinct voice, narration and dialogue are directed, and sound effects are placed automatically. Developers can build on LyricWinter Studio in two ways:

- **The LyricWinter REST API (beta)** at `https://lyricwinter.com/api/v1`, for scripts, backends, and apps.
- **The LyricWinter MCP server** at `https://lyricwinter.com/mcp`, for AI agents such as Claude, ChatGPT, Cursor, VS Code, and Codex.

Both use the same Studio account, projects, and balance. Anything you create through one is visible in the other and in the [Studio web app](/studio).

> [!NOTE]
> The LyricWinter API and MCP server are in beta. They are ready to build on, but fields may be added and some behavior may change before general availability. Check these docs for the current contract.

## What can you build with the LyricWinter API?

The LyricWinter API exposes the same Studio engine that powers the web and iOS apps:

- **Import stories.** Create a standalone story or a multi-chapter project from plain text.
- **Generate multi-voice audio.** One asynchronous workflow detects speakers, casts voices, directs emotion and delivery, places sound effects, and renders audio for up to 16 sections at a time.
- **Read and edit the script.** Every section is a versioned document of narration and dialogue blocks that you can read and update without overwriting newer work.
- **Play and export.** Stream per-block audio, compile a playback manifest, or export MP3, WAV, M4B, synchronized EPUB, or SRT files.
- **Share.** Publish a section or a whole project at a stable public link.
- **Bring your own sounds.** Upload sound effects and ambience, then let Create Audio place them.

## Should I use the REST API or the MCP server?

| If you want to… | Use |
| --- | --- |
| Automate audio production from your own code or backend | [REST API](/docs/quickstart) |
| Let an AI assistant create and manage Studio stories in conversation | [MCP server](/docs/mcp) |
| Build a custom app or integration on top of Studio | [REST API](/docs/api) |
| Connect Claude, ChatGPT, Cursor, VS Code, or Codex to your account | [MCP server](/docs/mcp) |

The MCP server is a thin, authenticated layer over the REST API. It exposes 13 [tools](/docs/mcp-tools) for the most common Studio tasks. The REST API covers more, including exports, sharing, and the sound library.

## How does LyricWinter Studio work?

1. You create a **project** and add **sections** (chapters or scenes) of story text.
2. A **workflow** prepares each section: it splits the text into narration and dialogue blocks, attributes every line to a **speaker**, and casts a voice for each character.
3. The same workflow directs each performance and generates audio. You poll the workflow until it finishes.
4. You play the result block by block, compile a playback manifest, or export a file.

Read [Studio concepts](/docs/studio-concepts) for the full model, including versions and safe retries.

## How much does it cost?

API and MCP usage draws from the same word balance as the Studio app. Reading data is free. Creating audio consumes words from the account that owns the project. See [pricing](/pricing) for plans and word packs, and check your balance in the [dashboard](/dashboard).

## Machine-readable resources

- **OpenAPI 3.1 contract:** [`https://lyricwinter.com/api/v1/openapi.json`](https://lyricwinter.com/api/v1/openapi.json)
- **Docs index for LLMs:** [`https://lyricwinter.com/llms.txt`](https://lyricwinter.com/llms.txt), with the full text at [`/llms-full.txt`](https://lyricwinter.com/llms-full.txt)
- **Markdown for any page:** add `.md` to the URL, for example [`/docs/quickstart.md`](/docs/quickstart.md)
- **MCP OAuth metadata:** [`/.well-known/oauth-protected-resource/mcp`](https://lyricwinter.com/.well-known/oauth-protected-resource/mcp)

## Get help

Email [support@lyricwinter.com](mailto:support@lyricwinter.com) and include the `request_id` from any failing response.