Skip to content
LyricWinterdocumentation home

API reference

LyricWinter REST API reference (beta)

Base URL, authentication, response envelope, and every endpoint group in the LyricWinter REST API beta, generated from the public OpenAPI 3.1 contract.

BetaUpdated

MarkdownAsk ChatGPTAsk Claude

The LyricWinter REST API is a JSON-over-HTTPS API for LyricWinter Studio. It is in beta. This reference is generated from the public OpenAPI 3.1 contract, the same file that API tools and code generators can download.

PropertyValue
Base URLhttps://lyricwinter.com/api/v1
AuthenticationAuthorization: Bearer lw_... (details)
Request formatContent-Type: application/json, UTF-8
Response format{ "data": ..., "request_id": "req_..." } (details)
IDsLowercase UUIDs
TimestampsISO 8601 in UTC
OpenAPI contract/api/v1/openapi.json

Use the OpenAPI contract#

Load https://lyricwinter.com/api/v1/openapi.json into Postman, Insomnia, Bruno, or an OpenAPI code generator to get a typed client for every endpoint below. Coding agents should read the contract instead of guessing field names.

Terminal
curl https://lyricwinter.com/api/v1/openapi.json -o lyricwinter-openapi.json

Conventions#

  • Scopes. Each endpoint lists the API key scope it requires. Studio endpoints need studio:read or studio:write.
  • Versions. Writes that change shared state take the version you last read, such as document_version, and fail with 409 instead of overwriting newer work. See Studio concepts.
  • Safe retries. Studio writes take a client_mutation_id; exports take an Idempotency-Key header. See Errors and retries.
  • Asynchronous work. Workflows and exports return 202 Accepted. Poll the returned resource until it reaches a terminal status.
  • Media. Audio is served from short-lived signed URLs returned by the API. Fetch fresh URLs instead of storing them.

Endpoint groups

Account and API keys

Check API health, read the account behind an API key, and create, list, or revoke scoped API keys.

Projects

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

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

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

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.

Media and playback

Read the generated audio state for a section, compile a playback manifest for the current document version, and mint short-lived URLs for individual media assets.

Exports

Render a section into a downloadable MP3, WAV, M4B, synchronized EPUB, or SRT file. Exports are pinned to the current document, cast, and mastering versions and run asynchronously; poll an export until its file is ready.

Sharing

Publish a section or a whole project at a stable public link, read its sharing state, or revoke the link.

Sound library

Upload your own sound effects and ambience into the Studio sound library, manage their metadata, and link them to projects so Create Audio can place them automatically.