API reference

Exports API

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.

BetaUpdated September 30, 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"
}

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, when status is completed, its downloadable artifact. Poll about once per second while it runs.

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"
}

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"
}