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

Voice preparation

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

Check API health, read the account and available generation balance 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. 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

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

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

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

Sound library

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

Send product feedback with screenshots and other images so our team can see what you mean.