API reference

Exports API

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.

BetaUpdated October 1, 2026

Markdown Ask ChatGPT Ask Claude

Base URL: https://lyricwinter.com/api/v1
Authentication: Authorization: Bearer lw_…
Contract: openapi.json

Get the mastering profile

GET/studio/projects/{projectId}/mastering-profile

Scope studio:read

Returns the project's loudness and mastering settings and its mastering_version, which exports require.

Path parameters

projectIdstringrequireduuid

Response 200

Current mastering authority and profile. Fields below are inside data.

schema_version1required
project_idstringrequireduuid
project_kindstringrequired
One ofstandalonenamed
mastering_versionintegerrequired≥ 1
scopestringrequired
One ofdocumentproject
profileobjectrequired
10 child attributes
- schema_version1required
- enabledbooleanrequired
- target_lufsnumberrequired-30–-10
- strengthnumberrequired0–1
- max_boost_dbnumberrequired0–24
- max_reduction_dbnumberrequired0–24
- silence_threshold_lufsnumberrequired-120–-20
- peak_ceiling_dbnumberrequired-12–-0.1
- speaker_adjustments_dbmap of numberrequired
- sfx_bus_gain_dbnumberrequired-24–24default 0
sfx_adjustmentsobject
3 child attributes
- nonzero_countintegerrequired≥ 0
- nonzero_section_countintegerrequired≥ 0
- fingerprintstringrequiredpattern ^[a-f0-9]{64}$

Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/mastering-profile" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/mastering-profile`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/mastering-profile",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_kind": "standalone",
    "mastering_version": 1,
    "scope": "document",
    "profile": {
      "schema_version": 1,
      "enabled": true,
      "target_lufs": -30,
      "strength": 0,
      "max_boost_db": 0,
      "max_reduction_db": 0,
      "silence_threshold_lufs": -120,
      "peak_ceiling_db": -12,
      "speaker_adjustments_db": {},
      "sfx_bus_gain_db": 0
    },
    "sfx_adjustments": {
      "nonzero_count": 1,
      "nonzero_section_count": 1,
      "fingerprint": "string"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Export a project's sections

POST/studio/projects/{projectId}/exports

Scope studio:writeRetry with the same Idempotency-Key

Creates a parent job with one section export per selected active section, in project order. Send schema_version: 1, format, and pin: "current" with an Idempotency-Key header. Optional sections selects 1-100 unique section UUIDs; omitting it selects all active sections, up to 100. The selection and saved document, cast, and mastering version plan are captured together and remain fixed. Audio takes are selected when each child compiles, not atomically at enqueue. Returns 202 for a new job or 200 for a database replay; an HTTP replay may retain the original 202. Dispatch is asynchronous, without a fixed completion deadline. This does not generate speech or automatically retry failed paid generation. Poll the parent and download child files separately; archive is always null.

Path parameters

projectIdstringrequireduuid

Headers

Idempotency-Keystringrequired8–128 charspattern ^[\x21-\x7E]+$
Key for one intended project export. Retry the same request with the same key; reuse for a different request returns 409.

Request body application/json

schema_version1required
formatstringrequired
One ofmp3wavm4bepubsrt
pin"current"required
Capture saved document, speaker registry, and mastering versions at enqueue. This does not capture an atomic queue-time media revision.
sectionsarray of string1–100 itemsunique
Active section IDs belonging to this project. Returned children follow project order, not request order. Omit to select all active sections; the resulting selection must contain one to 100 sections.

Response 200

The existing parent was returned by database idempotency replay; this does not imply completion. Fields below are inside data.

schema_version1required
idstringrequireduuid
Parent project export job ID.
project_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
queued when all children are queued; running while any child is active otherwise. Once all children are terminal or unavailable: completed if all succeeded, partial_failed if only some succeeded, or failed if none succeeded. Child cancellation, supersession, and unavailability count as failure, not successful completion.
One ofqueuedrunningcompletedpartial_failedfailed
percentintegerrequired0–100
Floor of the mean child progress. Each terminal or unavailable child counts as 100, including failed, cancelled, or superseded children. Measures finished work, not success rate.
created_atstringrequireddate-time
sectionsarray of objectrequired1–100 items
Immutable selection and authority version plan in captured project order, with available child states or per-section unavailability errors.
6 item attributes
- section_idstringrequireduuid
- titlestringrequiredmax 500 chars
  Section title captured for this parent.
- export_idstringrequireduuid
  Captured child ID. Child status, manifest, and cancellation endpoints are usable only while the child remains accessible.
- authorityobjectrequired
  Immutable saved versions captured at enqueue, retained even if the child is moved or deleted.
  3 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
- exportobject | nullrequired
  Current ordinary child export payload, or null when the child is unavailable after transfer or deletion.
  15 child attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
- errorobject | nullrequired
  Per-section availability error, or null when the child is available. Unavailable children report STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE and count as aggregate failure.
  2 child attributes
  codestringrequiredmin 1 chars
  messagestringrequired
archiveany | nullrequired
No combined archive or ZIP is produced. Download child artifacts individually.

Response 202

New durable project export work accepted, or its original accepted HTTP response replayed. Poll for current state. Fields below are inside data.

schema_version1required
idstringrequireduuid
Parent project export job ID.
project_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
queued when all children are queued; running while any child is active otherwise. Once all children are terminal or unavailable: completed if all succeeded, partial_failed if only some succeeded, or failed if none succeeded. Child cancellation, supersession, and unavailability count as failure, not successful completion.
One ofqueuedrunningcompletedpartial_failedfailed
percentintegerrequired0–100
Floor of the mean child progress. Each terminal or unavailable child counts as 100, including failed, cancelled, or superseded children. Measures finished work, not success rate.
created_atstringrequireddate-time
sectionsarray of objectrequired1–100 items
Immutable selection and authority version plan in captured project order, with available child states or per-section unavailability errors.
6 item attributes
- section_idstringrequireduuid
- titlestringrequiredmax 500 chars
  Section title captured for this parent.
- export_idstringrequireduuid
  Captured child ID. Child status, manifest, and cancellation endpoints are usable only while the child remains accessible.
- authorityobjectrequired
  Immutable saved versions captured at enqueue, retained even if the child is moved or deleted.
  3 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
- exportobject | nullrequired
  Current ordinary child export payload, or null when the child is unavailable after transfer or deletion.
  15 child attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
- errorobject | nullrequired
  Per-section availability error, or null when the child is available. Unavailable children report STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE and count as aggregate failure.
  2 child attributes
  codestringrequiredmin 1 chars
  messagestringrequired
archiveany | nullrequired
No combined archive or ZIP is produced. Download child artifacts individually.

Errors 400, 401, 403, 404, 409, 500, 503 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/exports" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "format": "mp3",
  "pin": "current"
}'

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/exports`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "schema_version": 1,
    "format": "mp3",
    "pin": "current"
  }),
});
const { data, error, request_id } = await response.json();

import os, uuid
import requests

project_id = "<projectId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/exports",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "schema_version": 1,
      "format": "mp3",
      "pin": "current"
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "format": "mp3",
    "status": "queued",
    "percent": 1,
    "created_at": "2026-09-30T17:00:00.000Z",
    "sections": [
      {
        "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "title": "Chapter One",
        "export_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "authority": {
          "document_version": 1,
          "speaker_registry_version": 1,
          "mastering_version": 1
        },
        "export": {
          "schema_version": 1,
          "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
          "format": "mp3",
          "status": "queued",
          "phase": "queued",
          "percent": 1,
          "cache_result": "miss",
          "authority": {
            "document_version": 1,
            "speaker_registry_version": 1,
            "mastering_version": 1,
            "is_current": true
          },
          "created_at": "2026-09-30T17:00:00.000Z",
          "started_at": "2026-09-30T17:00:00.000Z",
          "completed_at": "2026-09-30T17:00:00.000Z",
          "error": {
            "code": "string",
            "message": "string"
          },
          "artifact": {
            "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
            "filename": "string",
            "content_type": "string",
            "size_bytes": 1,
            "download_url": "https://lyricwinter.com/…",
            "download_url_expires_at": "2026-09-30T17:00:00.000Z",
            "artifact_expires_at": "2026-09-30T17:00:00.000Z"
          }
        },
        "error": {
          "code": "string",
          "message": "string"
        }
      }
    ],
    "archive": null
  },
  "request_id": "req_01J9Z3K8QF4"
}

List project export jobs

GET/studio/projects/{projectId}/exports

Scope studio:read

Lists parent jobs newest first, including their child exports. Optional format filters the list. cursor is an integer offset starting at 0; limit is 1-10 and defaults to 1. Pass the returned string next_cursor as the next offset; null means the end. Listing does not start exports or regenerate audio.

Path parameters

projectIdstringrequireduuid

Query parameters

formatstring
One ofmp3wavm4bepubsrt
cursorinteger≥ 0default 0
limitinteger1–10default 1

Response 200

A page of project export jobs and child statuses. Fields below are inside data.

schema_version1required
exportsarray of objectrequiredmax 10 items
9 item attributes
- schema_version1required
- idstringrequireduuid
  Parent project export job ID.
- project_idstringrequireduuid
- formatstringrequired
  One ofmp3wavm4bepubsrt
- statusstringrequired
  queued when all children are queued; running while any child is active otherwise. Once all children are terminal or unavailable: completed if all succeeded, partial_failed if only some succeeded, or failed if none succeeded. Child cancellation, supersession, and unavailability count as failure, not successful completion.
  One ofqueuedrunningcompletedpartial_failedfailed
- percentintegerrequired0–100
  Floor of the mean child progress. Each terminal or unavailable child counts as 100, including failed, cancelled, or superseded children. Measures finished work, not success rate.
- created_atstringrequireddate-time
- sectionsarray of objectrequired1–100 items
  Immutable selection and authority version plan in captured project order, with available child states or per-section unavailability errors.
  6 item attributes
  section_idstringrequireduuid
  titlestringrequiredmax 500 chars
  Section title captured for this parent.
  export_idstringrequireduuid
  Captured child ID. Child status, manifest, and cancellation endpoints are usable only while the child remains accessible.
  authorityobjectrequired
  Immutable saved versions captured at enqueue, retained even if the child is moved or deleted.
  3 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  exportobject | nullrequired
  Current ordinary child export payload, or null when the child is unavailable after transfer or deletion.
  15 child attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
  errorobject | nullrequired
  Per-section availability error, or null when the child is available. Unavailable children report STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE and count as aggregate failure.
  2 child attributes
  codestringrequiredmin 1 chars
  messagestringrequired
- archiveany | nullrequired
  No combined archive or ZIP is produced. Download child artifacts individually.
next_cursorstring | nullrequiredmin 1 chars
Next integer offset encoded as a string, or null at the end. Pass it as cursor with the same format filter.

Errors 400, 401, 403, 404, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/exports" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/exports`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/exports",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "exports": [
      {
        "schema_version": 1,
        "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "format": "mp3",
        "status": "queued",
        "percent": 1,
        "created_at": "2026-09-30T17:00:00.000Z",
        "sections": [
          {
            "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
            "title": "Chapter One",
            "export_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
            "authority": {
              "document_version": 1,
              "speaker_registry_version": 1,
              "mastering_version": 1
            },
            "export": {
              "schema_version": 1,
              "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
              "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
              "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
              "format": "mp3",
              "status": "queued",
              "phase": "queued",
              "percent": 1,
              "cache_result": "miss",
              "authority": {
                "document_version": null,
                "speaker_registry_version": null,
                "mastering_version": null,
                "is_current": null
              },
              "created_at": "2026-09-30T17:00:00.000Z",
              "started_at": "2026-09-30T17:00:00.000Z",
              "completed_at": "2026-09-30T17:00:00.000Z",
              "error": {
                "code": null,
                "message": null
              },
              "artifact": {
                "asset_id": null,
                "filename": null,
                "content_type": null,
                "size_bytes": null,
                "download_url": null,
                "download_url_expires_at": null,
                "artifact_expires_at": null
              }
            },
            "error": {
              "code": "string",
              "message": "string"
            }
          }
        ],
        "archive": null
      }
    ],
    "next_cursor": "string"
  },
  "request_id": "req_01J9Z3K8QF4"
}

Poll a project export job

GET/studio/projects/{projectId}/exports/{exportId}

Scope studio:read

Returns the parent job and ordered sections, each with section_id, captured title, child export_id, captured authority versions, nullable export, and nullable error. If a child is moved to another project or deleted, export is null and error.code is STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE; the captured plan remains. Poll while queued or running. completed, partial_failed, and failed are terminal. Unavailable children count as failures; percent counts them and terminal failures as finished work, so 100 does not mean success. Download each available completed child's export.artifact.download_url; use its child ID for /studio/exports/{exportId}/manifest (including optional schema_version=2 word timings) or /cancel. Transfers and cleanup are not blocked, and original child endpoints are not guaranteed to remain accessible. The parent ID is not a child ID. There is no combined archive or automatic re-export after edits.

Path parameters

projectIdstringrequireduuid
exportIdstringrequireduuid
The parent project export ID, not a child section export ID.

Response 200

Current project export parent and child states. Fields below are inside data.

schema_version1required
idstringrequireduuid
Parent project export job ID.
project_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
queued when all children are queued; running while any child is active otherwise. Once all children are terminal or unavailable: completed if all succeeded, partial_failed if only some succeeded, or failed if none succeeded. Child cancellation, supersession, and unavailability count as failure, not successful completion.
One ofqueuedrunningcompletedpartial_failedfailed
percentintegerrequired0–100
Floor of the mean child progress. Each terminal or unavailable child counts as 100, including failed, cancelled, or superseded children. Measures finished work, not success rate.
created_atstringrequireddate-time
sectionsarray of objectrequired1–100 items
Immutable selection and authority version plan in captured project order, with available child states or per-section unavailability errors.
6 item attributes
- section_idstringrequireduuid
- titlestringrequiredmax 500 chars
  Section title captured for this parent.
- export_idstringrequireduuid
  Captured child ID. Child status, manifest, and cancellation endpoints are usable only while the child remains accessible.
- authorityobjectrequired
  Immutable saved versions captured at enqueue, retained even if the child is moved or deleted.
  3 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
- exportobject | nullrequired
  Current ordinary child export payload, or null when the child is unavailable after transfer or deletion.
  15 child attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
- errorobject | nullrequired
  Per-section availability error, or null when the child is available. Unavailable children report STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE and count as aggregate failure.
  2 child attributes
  codestringrequiredmin 1 chars
  messagestringrequired
archiveany | nullrequired
No combined archive or ZIP is produced. Download child artifacts individually.

Errors 400, 401, 403, 404, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const projectId = "<projectId>";
const exportId = "<exportId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/exports/${exportId}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
export_id = "<exportId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/exports/{export_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "format": "mp3",
    "status": "queued",
    "percent": 1,
    "created_at": "2026-09-30T17:00:00.000Z",
    "sections": [
      {
        "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "title": "Chapter One",
        "export_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
        "authority": {
          "document_version": 1,
          "speaker_registry_version": 1,
          "mastering_version": 1
        },
        "export": {
          "schema_version": 1,
          "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
          "format": "mp3",
          "status": "queued",
          "phase": "queued",
          "percent": 1,
          "cache_result": "miss",
          "authority": {
            "document_version": 1,
            "speaker_registry_version": 1,
            "mastering_version": 1,
            "is_current": true
          },
          "created_at": "2026-09-30T17:00:00.000Z",
          "started_at": "2026-09-30T17:00:00.000Z",
          "completed_at": "2026-09-30T17:00:00.000Z",
          "error": {
            "code": "string",
            "message": "string"
          },
          "artifact": {
            "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
            "filename": "string",
            "content_type": "string",
            "size_bytes": 1,
            "download_url": "https://lyricwinter.com/…",
            "download_url_expires_at": "2026-09-30T17:00:00.000Z",
            "artifact_expires_at": "2026-09-30T17:00:00.000Z"
          }
        },
        "error": {
          "code": "string",
          "message": "string"
        }
      }
    ],
    "archive": null
  },
  "request_id": "req_01J9Z3K8QF4"
}

Compare section export versions

GET/studio/projects/{projectId}/export-freshness

Scope studio:read

Returns active sections in project order, their saved document, speaker registry, and mastering versions, and their latest export for format (default mp3). Deleted sections are omitted; at most 100 active sections are supported. basis is document_cast_mastering_versions. Without an export, latest_export and matches_current_authority are null. A true match is only a version comparison: it does not guarantee latest audio takes, successful completion, complete media, or a valid downloadable artifact. Inspect status and artifact separately. This read does not export or generate anything.

Path parameters

projectIdstringrequireduuid

Query parameters

formatstringdefault "mp3"
One ofmp3wavm4bepubsrt

Response 200

Version comparisons for the project's active sections. Fields below are inside data.

schema_version1required
project_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
basis"document_cast_mastering_versions"required
Saved version comparison only; not take freshness, artifact validity, or successful completion.
sectionsarray of objectrequiredmax 100 items
Active sections in project order; deleted sections are omitted. Projects exceeding 100 active sections return 400.
7 item attributes
- section_idstringrequireduuid
- titlestringrequiredmax 500 chars
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
- latest_exportobject | nullrequired
  Latest section export for the requested format, regardless of status; null if none exists.
  15 child attributes
  schema_version1required
  idstringrequireduuid
  project_idstringrequireduuid
  section_idstringrequireduuid
  formatstringrequired
  One ofmp3wavm4bepubsrt
  statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
  phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
  percentintegerrequired0–100
  cache_resultstringrequired
  One ofmissreusedcoalesced
  authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
  created_atstringrequireddate-time
  started_atstring | nullrequireddate-time
  completed_atstring | nullrequireddate-time
  errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
  artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
- matches_current_authorityboolean | nullrequired
  Whether the latest export's document, cast, and mastering versions match. Null without an export. true does not guarantee latest takes, completion, timeline completeness, or a valid artifact.

Errors 400, 401, 403, 404, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/export-freshness" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/export-freshness`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/export-freshness",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "format": "mp3",
    "basis": "document_cast_mastering_versions",
    "sections": [
      {
        "section_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "title": "Chapter One",
        "document_version": 1,
        "speaker_registry_version": 1,
        "mastering_version": 1,
        "latest_export": {
          "schema_version": 1,
          "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
          "project_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
          "section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
          "format": "mp3",
          "status": "queued",
          "phase": "queued",
          "percent": 1,
          "cache_result": "miss",
          "authority": {
            "document_version": 1,
            "speaker_registry_version": 1,
            "mastering_version": 1,
            "is_current": true
          },
          "created_at": "2026-09-30T17:00:00.000Z",
          "started_at": "2026-09-30T17:00:00.000Z",
          "completed_at": "2026-09-30T17:00:00.000Z",
          "error": {
            "code": "string",
            "message": "string"
          },
          "artifact": {
            "asset_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
            "filename": "string",
            "content_type": "string",
            "size_bytes": 1,
            "download_url": "https://lyricwinter.com/…",
            "download_url_expires_at": "2026-09-30T17:00:00.000Z",
            "artifact_expires_at": "2026-09-30T17:00:00.000Z"
          }
        },
        "matches_current_authority": true
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

List exports

GET/studio/exports

Scope studio:read

Lists the account's exports, newest first. Completed exports include a download URL that is valid for twelve hours; the file itself is kept for thirty days.

Query parameters

section_idstringuuid
formatstring
One ofmp3wavm4bepubsrt
statusstring
One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
cursorinteger≥ 0default 0
limitinteger1–100default 25

Response 200

One export page. Fields below are inside data.

schema_version1required
exportsarray of objectrequired
15 item attributes
- schema_version1required
- idstringrequireduuid
- project_idstringrequireduuid
- section_idstringrequireduuid
- formatstringrequired
  One ofmp3wavm4bepubsrt
- statusstringrequired
  One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
- phasestringrequired
  One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
- percentintegerrequired0–100
- cache_resultstringrequired
  One ofmissreusedcoalesced
- authorityobjectrequired
  4 child attributes
  document_versionintegerrequired≥ 1
  speaker_registry_versionintegerrequired≥ 1
  mastering_versionintegerrequired≥ 1
  is_currentbooleanrequired
- created_atstringrequireddate-time
- started_atstring | nullrequireddate-time
- completed_atstring | nullrequireddate-time
- errorobject | nullrequired
  2 child attributes
  codestringrequired
  messagestringrequired
- artifactobject | nullrequired
  7 child attributes
  asset_idstringrequireduuid
  filenamestringrequired1–255 chars
  content_typestringrequiredmin 1 chars
  size_bytesintegerrequired≥ 1
  download_urlstringrequireduri
  download_url_expires_atstringrequireddate-time
  artifact_expires_atstringrequireddate-time
next_cursorstring | nullrequiredmin 1 chars

Errors 400, 401, 403, 404, 409, 500, 503 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/exports" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const response = await fetch(`https://lyricwinter.com/api/v1/studio/exports`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/exports",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "exports": [
      {
        "schema_version": 1,
        "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "format": "mp3",
        "status": "queued",
        "phase": "queued",
        "percent": 1,
        "cache_result": "miss",
        "authority": {
          "document_version": 1,
          "speaker_registry_version": 1,
          "mastering_version": 1,
          "is_current": true
        },
        "created_at": "2026-09-30T17:00:00.000Z",
        "started_at": "2026-09-30T17:00:00.000Z",
        "completed_at": "2026-09-30T17:00:00.000Z",
        "error": {
          "code": "string",
          "message": "string"
        },
        "artifact": {
          "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
          "filename": "string",
          "content_type": "string",
          "size_bytes": 1,
          "download_url": "https://lyricwinter.com/…",
          "download_url_expires_at": "2026-09-30T17:00:00.000Z",
          "artifact_expires_at": "2026-09-30T17:00:00.000Z"
        }
      }
    ],
    "next_cursor": "string"
  },
  "request_id": "req_01J9Z3K8QF4"
}

Create an export

POST/studio/exports

Scope studio:writeRetry with the same Idempotency-Key

Renders one section into mp3, wav, m4b, synchronized epub, or srt, pinned to the document, speaker registry, and mastering versions you send. Returns 202 for new work or 200 when an identical, unexpired file is reused. Requires an Idempotency-Key header.

Headers

Idempotency-Keystringrequired1–255 chars
Opaque caller key. The same key and request replay safely; the same key with a different request conflicts.

Request body application/json

schema_version1required
section_idstringrequireduuid
document_versionintegerrequired≥ 1
speaker_registry_versionintegerrequired≥ 1
mastering_versionintegerrequired≥ 1
formatstringrequired
One ofmp3wavm4bepubsrt

Response 200

An unexpired identical artifact was reused. Fields below are inside data.

schema_version1required
idstringrequireduuid
project_idstringrequireduuid
section_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
phasestringrequired
One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
percentintegerrequired0–100
cache_resultstringrequired
One ofmissreusedcoalesced
authorityobjectrequired
4 child attributes
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
- is_currentbooleanrequired
created_atstringrequireddate-time
started_atstring | nullrequireddate-time
completed_atstring | nullrequireddate-time
errorobject | nullrequired
2 child attributes
- codestringrequired
- messagestringrequired
artifactobject | nullrequired
7 child attributes
- asset_idstringrequireduuid
- filenamestringrequired1–255 chars
- content_typestringrequiredmin 1 chars
- size_bytesintegerrequired≥ 1
- download_urlstringrequireduri
- download_url_expires_atstringrequireddate-time
- artifact_expires_atstringrequireddate-time

Response 202

New durable export work accepted. Fields below are inside data.

schema_version1required
idstringrequireduuid
project_idstringrequireduuid
section_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
phasestringrequired
One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
percentintegerrequired0–100
cache_resultstringrequired
One ofmissreusedcoalesced
authorityobjectrequired
4 child attributes
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
- is_currentbooleanrequired
created_atstringrequireddate-time
started_atstring | nullrequireddate-time
completed_atstring | nullrequireddate-time
errorobject | nullrequired
2 child attributes
- codestringrequired
- messagestringrequired
artifactobject | nullrequired
7 child attributes
- asset_idstringrequireduuid
- filenamestringrequired1–255 chars
- content_typestringrequiredmin 1 chars
- size_bytesintegerrequired≥ 1
- download_urlstringrequireduri
- download_url_expires_atstringrequireddate-time
- artifact_expires_atstringrequireddate-time

Errors 400, 401, 403, 404, 409, 500, 502, 503 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/exports" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": 1,
  "section_id": "11111111-1111-4111-8111-111111111111",
  "document_version": 7,
  "speaker_registry_version": 3,
  "mastering_version": 4,
  "format": "mp3"
}'

const response = await fetch(`https://lyricwinter.com/api/v1/studio/exports`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "schema_version": 1,
    "section_id": "11111111-1111-4111-8111-111111111111",
    "document_version": 7,
    "speaker_registry_version": 3,
    "mastering_version": 4,
    "format": "mp3"
  }),
});
const { data, error, request_id } = await response.json();

import os, uuid
import requests

response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/exports",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
      "schema_version": 1,
      "section_id": "11111111-1111-4111-8111-111111111111",
      "document_version": 7,
      "speaker_registry_version": 3,
      "mastering_version": 4,
      "format": "mp3"
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
    "format": "mp3",
    "status": "queued",
    "phase": "queued",
    "percent": 1,
    "cache_result": "miss",
    "authority": {
      "document_version": 1,
      "speaker_registry_version": 1,
      "mastering_version": 1,
      "is_current": true
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "started_at": "2026-09-30T17:00:00.000Z",
    "completed_at": "2026-09-30T17:00:00.000Z",
    "error": {
      "code": "string",
      "message": "string"
    },
    "artifact": {
      "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "filename": "string",
      "content_type": "string",
      "size_bytes": 1,
      "download_url": "https://lyricwinter.com/…",
      "download_url_expires_at": "2026-09-30T17:00:00.000Z",
      "artifact_expires_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get an export

GET/studio/exports/{exportId}

Scope studio:read

Returns an export's status, phase, percent complete, and its completed, unexpired downloadable artifact. Historical files remain tied to their original export. authority.is_current compares document, cast, and mastering versions only, not the latest audio rendition. For timings matching this file, fetch /studio/exports/{exportId}/manifest.

Path parameters

exportIdstringrequireduuid

Response 200

Current durable export state. Fields below are inside data.

schema_version1required
idstringrequireduuid
project_idstringrequireduuid
section_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
phasestringrequired
One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
percentintegerrequired0–100
cache_resultstringrequired
One ofmissreusedcoalesced
authorityobjectrequired
4 child attributes
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
- is_currentbooleanrequired
created_atstringrequireddate-time
started_atstring | nullrequireddate-time
completed_atstring | nullrequireddate-time
errorobject | nullrequired
2 child attributes
- codestringrequired
- messagestringrequired
artifactobject | nullrequired
7 child attributes
- asset_idstringrequireduuid
- filenamestringrequired1–255 chars
- content_typestringrequiredmin 1 chars
- size_bytesintegerrequired≥ 1
- download_urlstringrequireduri
- download_url_expires_atstringrequireddate-time
- artifact_expires_atstringrequireddate-time

Errors 400, 401, 403, 404, 409, 500, 503 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/exports/$EXPORT_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const exportId = "<exportId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/exports/${exportId}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

export_id = "<exportId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/exports/{export_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
    "format": "mp3",
    "status": "queued",
    "phase": "queued",
    "percent": 1,
    "cache_result": "miss",
    "authority": {
      "document_version": 1,
      "speaker_registry_version": 1,
      "mastering_version": 1,
      "is_current": true
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "started_at": "2026-09-30T17:00:00.000Z",
    "completed_at": "2026-09-30T17:00:00.000Z",
    "error": {
      "code": "string",
      "message": "string"
    },
    "artifact": {
      "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "filename": "string",
      "content_type": "string",
      "size_bytes": 1,
      "download_url": "https://lyricwinter.com/…",
      "download_url_expires_at": "2026-09-30T17:00:00.000Z",
      "artifact_expires_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get an export's immutable timeline

GET/studio/exports/{exportId}/manifest

Scope studio:read

Returns the exact pinned manifest identity (id, content hash, and schema_version), total duration, completeness, and block timings used by this export. The response's timing_basis is media_and_intra_block_silence_excluding_inter_block_spacing: speech and narration block durations sum their contiguous playback asset and separately assembled silence units, but exclude inter-block spacing units. An asset unit can share a block's start_ms yet have a shorter duration_ms when a trailing pause follows it; do not normalize either duration. Join block-level records by stable block_id and word sidecars by unit_id, not by start time or block_index. block_index is zero-based in the captured document's full block order. Optional schema_version=2 adds section-relative provider word timing sidecars for the pinned immutable assets, not today's retakes; missing alignment is explicitly unavailable. Default V1 is unchanged. Returns 409 before a manifest is pinned. This read does not compile or generate media.

Path parameters

exportIdstringrequireduuid

Query parameters

schema_versionintegerdefault 1
One of12

Response 200

The export's pinned block timeline and content-addressed manifest identity. Fields below are inside data.

One of 2 shapes:

schema_version: 1, timing_basis: "media_and_intra_block_silence_excluding_inter_block_spacing"

schema_version1required
export_idstringrequireduuid
project_idstringrequireduuid
section_idstringrequireduuid
manifestobjectrequired
3 child attributes
- idstringrequireduuid
- hashstringrequiredpattern ^[a-f0-9]{64}$
  Content hash of the exact immutable render manifest used by the export.
- schema_versionstringrequired
  One ofstudio-render-manifest-1studio-render-manifest-2
source_authorityobjectrequired
3 child attributes
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
duration_msintegerrequired≥ 0
completenessstringrequired
One ofpartialcomplete
timing_basis"media_and_intra_block_silence_excluding_inter_block_spacing"required
blocksarray of objectrequired
5 item attributes
- block_idstringrequireduuid
- block_indexintegerrequired≥ 0
  Zero-based position in the export's captured document block order, including non-speech blocks.
- media_kindstringrequired
  One ofspeechnarrationsfx
- start_msintegerrequired≥ 0
- duration_msintegerrequired≥ 1
  Block span including internal authored silence but excluding inter-block spacing; SFX spans its overlay.

schema_version: 2, timing_basis: "media_and_intra_block_silence_excluding_inter_block_spacing"

Opt-in export-bound timeline with word timing sidecars from the exact source assets in its immutable stored manifest, never current retakes.

schema_version2required
export_idstringrequireduuid
project_idstringrequireduuid
section_idstringrequireduuid
manifestobjectrequired
3 child attributes
- idstringrequireduuid
- hashstringrequiredpattern ^[a-f0-9]{64}$
  Content hash of the exact immutable render manifest used by the export.
- schema_versionstringrequired
  One ofstudio-render-manifest-1studio-render-manifest-2
source_authorityobjectrequired
3 child attributes
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
duration_msintegerrequired≥ 0
completenessstringrequired
One ofpartialcomplete
timing_basis"media_and_intra_block_silence_excluding_inter_block_spacing"required
blocksarray of objectrequired
5 item attributes
- block_idstringrequireduuid
- block_indexintegerrequired≥ 0
  Zero-based position in the export's captured document block order, including non-speech blocks.
- media_kindstringrequired
  One ofspeechnarrationsfx
- start_msintegerrequired≥ 0
- duration_msintegerrequired≥ 1
  Block span including internal authored silence but excluding inter-block spacing; SFX spans its overlay.
unit_word_timingsarray of objectrequiredmax 60000 items
One of 2 shapes:
word_timing: "provider"
- unit_idstringrequireduuid
- block_idstringrequireduuid
- asset_idstringrequireduuid
- word_timing"provider"required
- wordsarray of objectrequired1–10000 items
  3 item attributes
  textstringrequired1–4096 chars
  start_msintegerrequired≥ 0
  end_msintegerrequired≥ 0
word_timing: "unavailable"
- unit_idstringrequireduuid
- block_idstringrequireduuid
- asset_idstringrequireduuid
- word_timing"unavailable"required

Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/exports/$EXPORT_ID/manifest" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const exportId = "<exportId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/exports/${exportId}/manifest`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

export_id = "<exportId>"
response = requests.request(
    "GET",
    f"https://lyricwinter.com/api/v1/studio/exports/{export_id}/manifest",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "export_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
    "manifest": {
      "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "hash": "string",
      "schema_version": "studio-render-manifest-1"
    },
    "source_authority": {
      "document_version": 1,
      "speaker_registry_version": 1,
      "mastering_version": 1
    },
    "duration_ms": 1,
    "completeness": "partial",
    "timing_basis": "media_and_intra_block_silence_excluding_inter_block_spacing",
    "blocks": [
      {
        "block_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "block_index": 1,
        "media_kind": "speech",
        "start_ms": 1,
        "duration_ms": 1
      }
    ]
  },
  "request_id": "req_01J9Z3K8QF4"
}

Cancel an export

POST/studio/exports/{exportId}/cancel

Scope studio:write

Cancels a queued export immediately or asks a running one to stop. Files already produced for other requests are not deleted.

Path parameters

exportIdstringrequireduuid

Response 200

Current cancelled or canceling export state. Fields below are inside data.

schema_version1required
idstringrequireduuid
project_idstringrequireduuid
section_idstringrequireduuid
formatstringrequired
One ofmp3wavm4bepubsrt
statusstringrequired
One ofqueuedrunningretry_waitcancelingcompletedfailedcancelledsuperseded
phasestringrequired
One ofqueuedcompilingclaiming_artifactdownloadingmixingencodingpackaginguploadingcompletefailedcancelled
percentintegerrequired0–100
cache_resultstringrequired
One ofmissreusedcoalesced
authorityobjectrequired
4 child attributes
- document_versionintegerrequired≥ 1
- speaker_registry_versionintegerrequired≥ 1
- mastering_versionintegerrequired≥ 1
- is_currentbooleanrequired
created_atstringrequireddate-time
started_atstring | nullrequireddate-time
completed_atstring | nullrequireddate-time
errorobject | nullrequired
2 child attributes
- codestringrequired
- messagestringrequired
artifactobject | nullrequired
7 child attributes
- asset_idstringrequireduuid
- filenamestringrequired1–255 chars
- content_typestringrequiredmin 1 chars
- size_bytesintegerrequired≥ 1
- download_urlstringrequireduri
- download_url_expires_atstringrequireddate-time
- artifact_expires_atstringrequireddate-time

Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/exports/$EXPORT_ID/cancel" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

const exportId = "<exportId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/exports/${exportId}/cancel`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
  },
});
const { data, error, request_id } = await response.json();

import os
import requests

export_id = "<exportId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/exports/{export_id}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": 1,
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
    "format": "mp3",
    "status": "queued",
    "phase": "queued",
    "percent": 1,
    "cache_result": "miss",
    "authority": {
      "document_version": 1,
      "speaker_registry_version": 1,
      "mastering_version": 1,
      "is_current": true
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "started_at": "2026-09-30T17:00:00.000Z",
    "completed_at": "2026-09-30T17:00:00.000Z",
    "error": {
      "code": "string",
      "message": "string"
    },
    "artifact": {
      "asset_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "filename": "string",
      "content_type": "string",
      "size_bytes": 1,
      "download_url": "https://lyricwinter.com/…",
      "download_url_expires_at": "2026-09-30T17:00:00.000Z",
      "artifact_expires_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}