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

Character voice design

Design a Studio character voice, read its exact job and candidates, select before expiry, or request cancellation. Retain original mutation/request/job identities. Voice creation does not generate speech; assignment_outcome and the current document determine whether casting succeeded. The project preference selects the engine for future designs independently of the sample-design provider.

Voices and uploads

Discover accessible voices, inspect current engine eligibility, and upload a private voice through the ordinary asynchronous upload flow. Retain original voice, resource and operation identifiers when recovering an interrupted upload.

Voice creation recovery

Read the recorded result of a voice creation request without starting another creation.

Voice preparation

Check whether an ElevenLabs voice is already prepared and whether new preparation is currently available. New custom voices require UltraWinter and shared capacity; prepared current-revision voices remain usable on eligible paid plans. This read-only check does not create voices or reserve 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. Provider-quota failures can appear as failed steps with `STUDIO_WORKFLOW_PROVIDER_QUOTA_EXCEEDED`; generation-batch targets report `PROVIDER_QUOTA_EXCEEDED`, `ELEVENLABS_ACCOUNT_PREPARATION_LIMIT`, or `ELEVENLABS_SHARED_PREPARATION_LIMIT`. Completed audio remains available. New custom ElevenLabs voices require UltraWinter and a dynamic shared allocation, subject to live provider capacity. If preparation is unavailable, choose a prepared current-revision voice or explicitly choose another engine, or wait and recheck availability before resuming. Do not assume a fixed quota or provider reset date. An engine switch must be an explicit choice; do not automatically resubmit quota failures. For other provider-account outages, contact us before resuming.

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 ElevenLabs preparation capacity; exhausted or unverified capacity blocks new preparation, not eligible paid-plan reuse of prepared current-revision voices. 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 includes document, cast, mastering and saved spatial settings, but does not prove current audio takes or artifact readiness.

Sharing

Share chapters at one story link once Stories publishing opens for your account, inspect sharing state, or unpublish chapters. Before your rollout, these endpoints retain the older listening-link behavior. New chapters start as drafts.

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.