# LyricWinter > LyricWinter turns stories into fully cast, multi-voice audio with distinct character voices, directed performances, and sound effects. Developers and AI agents can drive LyricWinter Studio through a beta REST API and a remote MCP server. Notes for agents and developers: - The LyricWinter REST API is in beta. Base URL: https://lyricwinter.com/api/v1. Authenticate with `Authorization: Bearer lw_...`; users create scoped keys at https://lyricwinter.com/dashboard under Developers. - Read the OpenAPI 3.1 contract at https://lyricwinter.com/api/v1/openapi.json instead of guessing endpoints, fields, or enum values. - The remote MCP server is https://lyricwinter.com/mcp (Streamable HTTP, OAuth 2.1 with PKCE, or a Studio-scoped API key as a bearer token). - Studio work is asynchronous: start a workflow, then poll it until its status is completed, partially_completed, failed, or cancelled. Creating audio consumes the account's balance, so never repeat a start request with a new client_mutation_id unless the user wants another run. - Every docs page has a Markdown version at the same URL plus `.md`. Requests that send `Accept: text/markdown` to a docs URL also receive Markdown. ## Get started - [LyricWinter API and MCP server](https://lyricwinter.com/docs.md): 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. - [Quickstart](https://lyricwinter.com/docs/quickstart.md): Create an API key, add a story, generate multi-voice audio, and fetch playback with the LyricWinter REST API in about ten minutes. - [Authentication](https://lyricwinter.com/docs/authentication.md): Authenticate LyricWinter API requests with scoped lw_ API keys, choose the right scopes, and understand how MCP clients connect through OAuth 2.1. ## Guides - [Studio concepts](https://lyricwinter.com/docs/studio-concepts.md): How LyricWinter Studio models stories as projects, sections, versioned documents, speakers, and asynchronous workflows, and how to edit them safely over the API. - [Errors and retries](https://lyricwinter.com/docs/errors-and-retries.md): The LyricWinter API response envelope, error codes, request IDs, retry rules, idempotency keys, and client mutation IDs for safe retries of paid operations. ## API reference - [API overview](https://lyricwinter.com/docs/api.md): Base URL, authentication, response envelope, and every endpoint group in the LyricWinter REST API beta, generated from the public OpenAPI 3.1 contract. - [Voice preparation](https://lyricwinter.com/docs/api/voice-preparation.md): Check whether an ElevenLabs voice is already prepared and whether new preparation is currently available. ElevenLabs v4 requires a paid plan. This read-only check does not create voices or reserve provider allowance. - [Account and API keys](https://lyricwinter.com/docs/api/account.md): Check API health, read the account and available generation balance behind an API key, and create, list, or revoke scoped API keys. - [Projects](https://lyricwinter.com/docs/api/projects.md): A Studio project groups ordered sections (chapters) that share one cast of speakers. Standalone stories appear as unassigned stories until you turn them into a named project. - [Sections](https://lyricwinter.com/docs/api/sections.md): A section is one chapter or scene of story text inside a project. Create a standalone story with one section, add sections to a project, reorder them, or delete them. - [Documents and speakers](https://lyricwinter.com/docs/api/documents.md): Every section has a versioned document of narration and dialogue blocks attributed to speakers. Read the document before editing it or generating audio, and list the project's speakers and casting. - [Workflows](https://lyricwinter.com/docs/api/workflows.md): Workflows are durable, asynchronous jobs. A prepare workflow structures text into narration and dialogue; a Create Audio workflow casts voices and generates multi-voice audio. Poll a workflow until it reaches a terminal status. A provider-account limit is reported as a failed step with `STUDIO_WORKFLOW_PROVIDER_QUOTA_EXCEEDED`; generation-batch targets use `PROVIDER_QUOTA_EXCEEDED`. Completed audio remains available. For a shared provider limit, contact us to restore provider access before explicitly resuming. When the failure message says the account's monthly ElevenLabs voice preparation allowance is used up, choose a cached ElevenLabs voice or another engine, or wait for the allowance to reset on the first of the month (UTC). Do not automatically resubmit quota failures. - [Media and playback](https://lyricwinter.com/docs/api/media.md): Check whether generation can start separately from whether audio already exists. Read per-block media freshness and generation activity, compile a playback manifest for current audio, and mint short-lived URLs. Generation availability checks plan access, voice/compiler eligibility, and confirmed ElevenLabs preparation exhaustion; it is not a promise of audio, synthesis quota, or funding. Free accounts cannot generate with ElevenLabs v4, but existing audio remains playable. - [Exports](https://lyricwinter.com/docs/api/exports.md): Render one section or a project's selected sections into downloadable MP3, WAV, M4B, synchronized EPUB, or SRT files. Poll a project job for every child export, then download files individually and fetch each child's immutable manifest for matching timings. No ZIP is produced. Freshness compares document, cast, and mastering versions only, not newer audio takes or artifact readiness. - [Sharing](https://lyricwinter.com/docs/api/sharing.md): Publish a section or a whole project at a stable public link, read its sharing state, or revoke the link. - [Sound library](https://lyricwinter.com/docs/api/sounds.md): Upload sound effects and ambience up to 256 MiB and 65 minutes into the Studio sound library, manage their metadata, publish them to the public catalog, and link them to projects so Create Audio can place them automatically. Processing verifies duration; the sanitized WAV can be up to 720 MiB. Pinned project sounds can play as long ambience overlays; provider-generated SFX remain limited to five minutes. - [Feedback](https://lyricwinter.com/docs/api/feedback.md): Send product feedback with screenshots and other images so our team can see what you mean. ## MCP server - [Connect an MCP client](https://lyricwinter.com/docs/mcp.md): Connect any MCP client to the remote LyricWinter Studio MCP server at https://lyricwinter.com/mcp using Streamable HTTP with OAuth 2.1 or a scoped API key. - [MCP tools reference](https://lyricwinter.com/docs/mcp-tools.md): Every tool exposed by the LyricWinter Studio MCP server, with inputs, required scopes, side effects, and the recommended agent workflow. ## Optional - [Full documentation in one file](https://lyricwinter.com/llms-full.txt): Every docs page above, concatenated as Markdown. - [OpenAPI 3.1 contract](https://lyricwinter.com/api/v1/openapi.json): Machine-readable schema for every public beta endpoint. - [LyricWinter Studio](https://lyricwinter.com/studio): The web app for editing, casting, and generating story audio. - [Pricing](https://lyricwinter.com/pricing): Plans and word balances that audio generation draws from. - [Use cases](https://lyricwinter.com/use-cases): Audiobooks, audio dramas, training role-plays, and other ways people use LyricWinter.