API reference

Sound library API

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.

BetaUpdated October 1, 2026

Markdown Ask ChatGPT Ask Claude

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

List sounds

GET/studio/sounds

Scope studio:read

Lists sounds in your library, sounds shared with you, or public sounds, filtered by scope and an optional search query. Results are cursor-paginated.

Query parameters

scopestringdefault "mine"
One ofminesharedpublic
qstringmax 200 chars
project_idstringuuid
in_projectboolean
limitinteger1–100default 30
cursorstringmax 500 chars

Response 200

Cursor-paginated sound library. Fields below are inside data.

schema_version"studio-sound-library-1"required
soundsarray of objectrequiredmax 100 items
19 item attributes
- idstringrequireduuid
- namestringrequired1–120 chars
- descriptionstringrequired1–1000 chars
- tagsarray of stringrequired1–12 itemsunique
- statusstringrequired
  One ofuploadingprocessingreadyfailed
- is_publicbooleanrequired
- owner_display_namestring | nullrequired1–200 chars
- is_owned_by_userbooleanrequired
- is_shared_with_userbooleanrequired
- incoming_shareobject | nullrequired
  2 child attributes
  idstringrequireduuid
  statusstringrequired
  One ofpendingaccepteddeclined
- is_in_projectbooleanrequired
- can_editbooleanrequired
- can_deletebooleanrequired
- can_sharebooleanrequired
- metadata_versionintegerrequired≥ 1
- current_revisionobject | nullrequired
  6 child attributes
  idstringrequireduuid
  revision_numberintegerrequired≥ 1
  duration_msintegerrequired100–3900000
  mime_typestringrequired1–200 chars
  file_size_bytesintegerrequired1–754974720
  created_atstringrequireddate-time
- errorobject | nullrequired
  2 child attributes
  codestring | nullrequiredmax 200 chars
  messagestringrequired1–1000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
next_cursorstring | nullrequired1–500 chars

Errors default use the standard error envelope.

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

const response = await fetch(`https://lyricwinter.com/api/v1/studio/sounds`, {
  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/sounds",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": "studio-sound-library-1",
    "sounds": [
      {
        "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "name": "My integration",
        "description": "string",
        "tags": [
          "string"
        ],
        "status": "uploading",
        "is_public": true,
        "owner_display_name": "string",
        "is_owned_by_user": true,
        "is_shared_with_user": true,
        "incoming_share": {
          "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "status": "pending"
        },
        "is_in_project": true,
        "can_edit": true,
        "can_delete": true,
        "can_share": true,
        "metadata_version": 1,
        "current_revision": {
          "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
          "revision_number": 1,
          "duration_ms": 100,
          "mime_type": "string",
          "file_size_bytes": 1,
          "created_at": "2026-09-30T17:00:00.000Z"
        },
        "error": {
          "code": "string",
          "message": "string"
        },
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z"
      }
    ],
    "next_cursor": "string"
  },
  "request_id": "req_01J9Z3K8QF4"
}

Start a sound upload

POST/studio/sounds

Scope studio:writeRetry with the same client_mutation_id

Creates a sound and returns a signed upload session. Files accept up to 256 MiB; decoded audio must be at most 65 minutes. Upload the file to the session URL, then call the complete endpoint. Processing verifies duration and publishes it as current_revision.duration_ms; client-supplied duration is not accepted as authority. Set is_public: true to list the sound in the public catalog and on lyricwinter.com/sounds once it is ready.

Request body application/json

schema_version"studio-sound-upload-1"required
client_mutation_idstringrequireduuid
namestringrequired1–120 chars
descriptionstringrequired1–1000 chars
tagsarray of stringrequired1–12 itemsunique
is_publicbooleanrequired
rights_acknowledgment_version"studio-sound-rights-1"required
fileobjectrequired
Upload files up to 268435456 bytes (256 MiB) and 3900000 ms (65 minutes). Duration is verified from decoded audio during processing, not trusted from a client declaration. The sanitized revision reports its verified duration_ms.
3 child attributes
- filenamestringrequired1–255 chars
- content_typestringrequired
  One ofaudio/wavaudio/x-wavaudio/mpegaudio/oggaudio/opusaudio/flacaudio/mp4audio/aacaudio/webm
- size_bytesintegerrequired1–268435456

Response 201

Upload session created. Fields below are inside data.

schema_version"studio-sound-upload-1"required
soundobjectrequired
19 child attributes
- idstringrequireduuid
- namestringrequired1–120 chars
- descriptionstringrequired1–1000 chars
- tagsarray of stringrequired1–12 itemsunique
- statusstringrequired
  One ofuploadingprocessingreadyfailed
- is_publicbooleanrequired
- owner_display_namestring | nullrequired1–200 chars
- is_owned_by_userbooleanrequired
- is_shared_with_userbooleanrequired
- incoming_shareobject | nullrequired
  2 child attributes
  idstringrequireduuid
  statusstringrequired
  One ofpendingaccepteddeclined
- is_in_projectbooleanrequired
- can_editbooleanrequired
- can_deletebooleanrequired
- can_sharebooleanrequired
- metadata_versionintegerrequired≥ 1
- current_revisionobject | nullrequired
  6 child attributes
  idstringrequireduuid
  revision_numberintegerrequired≥ 1
  duration_msintegerrequired100–3900000
  mime_typestringrequired1–200 chars
  file_size_bytesintegerrequired1–754974720
  created_atstringrequireddate-time
- errorobject | nullrequired
  2 child attributes
  codestring | nullrequiredmax 200 chars
  messagestringrequired1–1000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
uploadobjectrequired
5 child attributes
- idstringrequireduuid
- urlstringrequireduri
- method"PUT"required
- headersmap of stringrequired
- expires_atstringrequireddate-time

Errors default use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/sounds" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": "studio-sound-upload-1",
  "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "name": "My integration",
  "description": "string",
  "tags": [
    "string"
  ],
  "is_public": true,
  "rights_acknowledgment_version": "studio-sound-rights-1",
  "file": {
    "filename": "string",
    "content_type": "audio/wav",
    "size_bytes": 1
  }
}'

const response = await fetch(`https://lyricwinter.com/api/v1/studio/sounds`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": "studio-sound-upload-1",
    "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "name": "My integration",
    "description": "string",
    "tags": [
      "string"
    ],
    "is_public": true,
    "rights_acknowledgment_version": "studio-sound-rights-1",
    "file": {
      "filename": "string",
      "content_type": "audio/wav",
      "size_bytes": 1
    }
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/sounds",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": "studio-sound-upload-1",
      "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "name": "My integration",
      "description": "string",
      "tags": [
        "string"
      ],
      "is_public": True,
      "rights_acknowledgment_version": "studio-sound-rights-1",
      "file": {
        "filename": "string",
        "content_type": "audio/wav",
        "size_bytes": 1
      }
    },
)
payload = response.json()

Response 201 (example)

{
  "data": {
    "schema_version": "studio-sound-upload-1",
    "sound": {
      "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "name": "My integration",
      "description": "string",
      "tags": [
        "string"
      ],
      "status": "uploading",
      "is_public": true,
      "owner_display_name": "string",
      "is_owned_by_user": true,
      "is_shared_with_user": true,
      "incoming_share": {
        "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
        "status": "pending"
      },
      "is_in_project": true,
      "can_edit": true,
      "can_delete": true,
      "can_share": true,
      "metadata_version": 1,
      "current_revision": {
        "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
        "revision_number": 1,
        "duration_ms": 100,
        "mime_type": "string",
        "file_size_bytes": 1,
        "created_at": "2026-09-30T17:00:00.000Z"
      },
      "error": {
        "code": "string",
        "message": "string"
      },
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z"
    },
    "upload": {
      "id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40",
      "url": "https://lyricwinter.com/…",
      "method": "PUT",
      "headers": {},
      "expires_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Complete a sound upload

POST/studio/sounds/{soundId}/uploads/{uploadId}/complete

Scope studio:write

Tells LyricWinter the file has been uploaded so it can process the sound. Poll the latest upload status until the sound is ready.

Path parameters

soundIdstringrequireduuid
uploadIdstringrequireduuid

Request body application/json

schema_version"studio-sound-upload-complete-1"required

Response 200

Idempotent finalization result. Fields below are inside data.

idstringrequireduuid
namestringrequired1–120 chars
descriptionstringrequired1–1000 chars
tagsarray of stringrequired1–12 itemsunique
statusstringrequired
One ofuploadingprocessingreadyfailed
is_publicbooleanrequired
owner_display_namestring | nullrequired1–200 chars
is_owned_by_userbooleanrequired
is_shared_with_userbooleanrequired
incoming_shareobject | nullrequired
2 child attributes
- idstringrequireduuid
- statusstringrequired
  One ofpendingaccepteddeclined
is_in_projectbooleanrequired
can_editbooleanrequired
can_deletebooleanrequired
can_sharebooleanrequired
metadata_versionintegerrequired≥ 1
current_revisionobject | nullrequired
6 child attributes
- idstringrequireduuid
- revision_numberintegerrequired≥ 1
- duration_msintegerrequired100–3900000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–754974720
- created_atstringrequireddate-time
errorobject | nullrequired
2 child attributes
- codestring | nullrequiredmax 200 chars
- messagestringrequired1–1000 chars
created_atstringrequireddate-time
updated_atstringrequireddate-time

Response 202

Sanitization accepted. Fields below are inside data.

idstringrequireduuid
namestringrequired1–120 chars
descriptionstringrequired1–1000 chars
tagsarray of stringrequired1–12 itemsunique
statusstringrequired
One ofuploadingprocessingreadyfailed
is_publicbooleanrequired
owner_display_namestring | nullrequired1–200 chars
is_owned_by_userbooleanrequired
is_shared_with_userbooleanrequired
incoming_shareobject | nullrequired
2 child attributes
- idstringrequireduuid
- statusstringrequired
  One ofpendingaccepteddeclined
is_in_projectbooleanrequired
can_editbooleanrequired
can_deletebooleanrequired
can_sharebooleanrequired
metadata_versionintegerrequired≥ 1
current_revisionobject | nullrequired
6 child attributes
- idstringrequireduuid
- revision_numberintegerrequired≥ 1
- duration_msintegerrequired100–3900000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–754974720
- created_atstringrequireddate-time
errorobject | nullrequired
2 child attributes
- codestring | nullrequiredmax 200 chars
- messagestringrequired1–1000 chars
created_atstringrequireddate-time
updated_atstringrequireddate-time

Errors default use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/sounds/$SOUND_ID/uploads/$UPLOAD_ID/complete" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": "studio-sound-upload-complete-1"
}'

const soundId = "<soundId>";
const uploadId = "<uploadId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sounds/${soundId}/uploads/${uploadId}/complete`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": "studio-sound-upload-complete-1"
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

sound_id = "<soundId>"
upload_id = "<uploadId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/sounds/{sound_id}/uploads/{upload_id}/complete",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": "studio-sound-upload-complete-1"
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "name": "My integration",
    "description": "string",
    "tags": [
      "string"
    ],
    "status": "uploading",
    "is_public": true,
    "owner_display_name": "string",
    "is_owned_by_user": true,
    "is_shared_with_user": true,
    "incoming_share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "status": "pending"
    },
    "is_in_project": true,
    "can_edit": true,
    "can_delete": true,
    "can_share": true,
    "metadata_version": 1,
    "current_revision": {
      "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "revision_number": 1,
      "duration_ms": 100,
      "mime_type": "string",
      "file_size_bytes": 1,
      "created_at": "2026-09-30T17:00:00.000Z"
    },
    "error": {
      "code": "string",
      "message": "string"
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "updated_at": "2026-09-30T17:00:00.000Z"
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get sound upload status

GET/studio/sounds/{soundId}/uploads/latest

Scope studio:read

Returns the processing status of the most recent upload for a sound you own.

Path parameters

soundIdstringrequireduuid

Response 200

Latest owner upload, independent of the playable revision; null when none exists. Fields below are inside data.

schema_versionstringrequired
One ofstudio-sound-upload-status-1
sound_idstringrequireduuid
latestobject | nullrequired
9 child attributes
- idstringrequireduuid
- revision_numberintegerrequired≥ 1
- is_replacementbooleanrequired
- statusstringrequired
  One ofpending_uploadprocessingreadyfailedexpired
- completed_revision_idstring | nullrequireduuid
- errorobject | nullrequired
  2 child attributes
  codestring | nullrequired
  messagestringrequired
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
- expires_atstringrequireddate-time

Errors default use the standard error envelope.

curl "https://lyricwinter.com/api/v1/studio/sounds/$SOUND_ID/uploads/latest" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

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

import os
import requests

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

Response 200 (example)

{
  "data": {
    "schema_version": "studio-sound-upload-status-1",
    "sound_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "latest": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "revision_number": 1,
      "is_replacement": true,
      "status": "pending_upload",
      "completed_revision_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "error": {
        "code": "string",
        "message": "string"
      },
      "created_at": "2026-09-30T17:00:00.000Z",
      "updated_at": "2026-09-30T17:00:00.000Z",
      "expires_at": "2026-09-30T17:00:00.000Z"
    }
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get a sound

GET/studio/sounds/{soundId}

Scope studio:read

Returns one sound's metadata and processing state.

Path parameters

soundIdstringrequireduuid

Query parameters

project_idstringuuid

Response 200

Accessible sound detail. Fields below are inside data.

idstringrequireduuid
namestringrequired1–120 chars
descriptionstringrequired1–1000 chars
tagsarray of stringrequired1–12 itemsunique
statusstringrequired
One ofuploadingprocessingreadyfailed
is_publicbooleanrequired
owner_display_namestring | nullrequired1–200 chars
is_owned_by_userbooleanrequired
is_shared_with_userbooleanrequired
incoming_shareobject | nullrequired
2 child attributes
- idstringrequireduuid
- statusstringrequired
  One ofpendingaccepteddeclined
is_in_projectbooleanrequired
can_editbooleanrequired
can_deletebooleanrequired
can_sharebooleanrequired
metadata_versionintegerrequired≥ 1
current_revisionobject | nullrequired
6 child attributes
- idstringrequireduuid
- revision_numberintegerrequired≥ 1
- duration_msintegerrequired100–3900000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–754974720
- created_atstringrequireddate-time
errorobject | nullrequired
2 child attributes
- codestring | nullrequiredmax 200 chars
- messagestringrequired1–1000 chars
created_atstringrequireddate-time
updated_atstringrequireddate-time

Errors default use the standard error envelope.

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

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

import os
import requests

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

Response 200 (example)

{
  "data": {
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "name": "My integration",
    "description": "string",
    "tags": [
      "string"
    ],
    "status": "uploading",
    "is_public": true,
    "owner_display_name": "string",
    "is_owned_by_user": true,
    "is_shared_with_user": true,
    "incoming_share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "status": "pending"
    },
    "is_in_project": true,
    "can_edit": true,
    "can_delete": true,
    "can_share": true,
    "metadata_version": 1,
    "current_revision": {
      "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "revision_number": 1,
      "duration_ms": 100,
      "mime_type": "string",
      "file_size_bytes": 1,
      "created_at": "2026-09-30T17:00:00.000Z"
    },
    "error": {
      "code": "string",
      "message": "string"
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "updated_at": "2026-09-30T17:00:00.000Z"
  },
  "request_id": "req_01J9Z3K8QF4"
}

Update a sound

PATCH/studio/sounds/{soundId}

Scope studio:write

Updates a sound's name, description, tags, or is_public visibility. Publishing a sound that is still processing returns 409.

Path parameters

soundIdstringrequireduuid

Request body application/json

any

Response 200

Updated sound. Fields below are inside data.

idstringrequireduuid
namestringrequired1–120 chars
descriptionstringrequired1–1000 chars
tagsarray of stringrequired1–12 itemsunique
statusstringrequired
One ofuploadingprocessingreadyfailed
is_publicbooleanrequired
owner_display_namestring | nullrequired1–200 chars
is_owned_by_userbooleanrequired
is_shared_with_userbooleanrequired
incoming_shareobject | nullrequired
2 child attributes
- idstringrequireduuid
- statusstringrequired
  One ofpendingaccepteddeclined
is_in_projectbooleanrequired
can_editbooleanrequired
can_deletebooleanrequired
can_sharebooleanrequired
metadata_versionintegerrequired≥ 1
current_revisionobject | nullrequired
6 child attributes
- idstringrequireduuid
- revision_numberintegerrequired≥ 1
- duration_msintegerrequired100–3900000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–754974720
- created_atstringrequireddate-time
errorobject | nullrequired
2 child attributes
- codestring | nullrequiredmax 200 chars
- messagestringrequired1–1000 chars
created_atstringrequireddate-time
updated_atstringrequireddate-time

Errors default use the standard error envelope.

curl -X PATCH "https://lyricwinter.com/api/v1/studio/sounds/$SOUND_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d 'null'

const soundId = "<soundId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sounds/${soundId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(null),
});
const { data, error, request_id } = await response.json();

import os
import requests

sound_id = "<soundId>"
response = requests.request(
    "PATCH",
    f"https://lyricwinter.com/api/v1/studio/sounds/{sound_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json=None,
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "name": "My integration",
    "description": "string",
    "tags": [
      "string"
    ],
    "status": "uploading",
    "is_public": true,
    "owner_display_name": "string",
    "is_owned_by_user": true,
    "is_shared_with_user": true,
    "incoming_share": {
      "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "status": "pending"
    },
    "is_in_project": true,
    "can_edit": true,
    "can_delete": true,
    "can_share": true,
    "metadata_version": 1,
    "current_revision": {
      "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
      "revision_number": 1,
      "duration_ms": 100,
      "mime_type": "string",
      "file_size_bytes": 1,
      "created_at": "2026-09-30T17:00:00.000Z"
    },
    "error": {
      "code": "string",
      "message": "string"
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "updated_at": "2026-09-30T17:00:00.000Z"
  },
  "request_id": "req_01J9Z3K8QF4"
}

Delete a sound

DELETE/studio/sounds/{soundId}

Scope studio:writeRetry with the same client_mutation_id

Deletes a sound you own.

Path parameters

soundIdstringrequireduuid

Request body application/json

schema_version"studio-sound-mutation-1"required
client_mutation_idstringrequireduuid
expected_metadata_versionintegerrequired≥ 1

Response 200

Logical sound deleted. Fields below are inside data.

sound_effect_idstringrequireduuid
deletedtruerequired

Errors default use the standard error envelope.

curl -X DELETE "https://lyricwinter.com/api/v1/studio/sounds/$SOUND_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": "studio-sound-mutation-1",
  "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "expected_metadata_version": 1
}'

const soundId = "<soundId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sounds/${soundId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": "studio-sound-mutation-1",
    "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "expected_metadata_version": 1
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

sound_id = "<soundId>"
response = requests.request(
    "DELETE",
    f"https://lyricwinter.com/api/v1/studio/sounds/{sound_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": "studio-sound-mutation-1",
      "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "expected_metadata_version": 1
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "sound_effect_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "deleted": true
  },
  "request_id": "req_01J9Z3K8QF4"
}

Create a sound preview URL

POST/studio/sounds/{soundId}/preview-url

Scope studio:read

Returns a short-lived URL for listening to a sound.

Path parameters

soundIdstringrequireduuid

Response 200

Access-checked short-lived same-origin preview capability URL. Fields below are inside data.

schema_version"studio-sound-preview-1"required
urlstringrequireduri
expires_atstringrequireddate-time

Errors default use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/sounds/$SOUND_ID/preview-url" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY"

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

import os
import requests

sound_id = "<soundId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/sounds/{sound_id}/preview-url",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": "studio-sound-preview-1",
    "url": "https://lyricwinter.com/…",
    "expires_at": "2026-09-30T17:00:00.000Z"
  },
  "request_id": "req_01J9Z3K8QF4"
}

List project sounds

GET/studio/projects/{projectId}/sounds

Scope studio:read

Lists the sounds linked to a project. Create Audio can place linked sounds automatically when place_project_sounds is on.

Path parameters

projectIdstringrequireduuid

Query parameters

qstringmax 200 chars
limitinteger1–100default 50
cursorstringmax 500 chars

Response 200

Project sound registry page. Fields below are inside data.

schema_version"studio-sound-library-1"required
soundsarray of objectrequiredmax 100 items
19 item attributes
- idstringrequireduuid
- namestringrequired1–120 chars
- descriptionstringrequired1–1000 chars
- tagsarray of stringrequired1–12 itemsunique
- statusstringrequired
  One ofuploadingprocessingreadyfailed
- is_publicbooleanrequired
- owner_display_namestring | nullrequired1–200 chars
- is_owned_by_userbooleanrequired
- is_shared_with_userbooleanrequired
- incoming_shareobject | nullrequired
  2 child attributes
  idstringrequireduuid
  statusstringrequired
  One ofpendingaccepteddeclined
- is_in_projectbooleanrequired
- can_editbooleanrequired
- can_deletebooleanrequired
- can_sharebooleanrequired
- metadata_versionintegerrequired≥ 1
- current_revisionobject | nullrequired
  6 child attributes
  idstringrequireduuid
  revision_numberintegerrequired≥ 1
  duration_msintegerrequired100–3900000
  mime_typestringrequired1–200 chars
  file_size_bytesintegerrequired1–754974720
  created_atstringrequireddate-time
- errorobject | nullrequired
  2 child attributes
  codestring | nullrequiredmax 200 chars
  messagestringrequired1–1000 chars
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
next_cursorstring | nullrequired1–500 chars
sound_source_registry_versionintegerrequired≥ 1

Errors default use the standard error envelope.

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

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sounds`, {
  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}/sounds",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": "studio-sound-library-1",
    "sounds": [
      {
        "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "name": "My integration",
        "description": "string",
        "tags": [
          "string"
        ],
        "status": "uploading",
        "is_public": true,
        "owner_display_name": "string",
        "is_owned_by_user": true,
        "is_shared_with_user": true,
        "incoming_share": {
          "id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
          "status": "pending"
        },
        "is_in_project": true,
        "can_edit": true,
        "can_delete": true,
        "can_share": true,
        "metadata_version": 1,
        "current_revision": {
          "id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
          "revision_number": 1,
          "duration_ms": 100,
          "mime_type": "string",
          "file_size_bytes": 1,
          "created_at": "2026-09-30T17:00:00.000Z"
        },
        "error": {
          "code": "string",
          "message": "string"
        },
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z"
      }
    ],
    "next_cursor": "string",
    "sound_source_registry_version": 1
  },
  "request_id": "req_01J9Z3K8QF4"
}

Link a sound to a project

POST/studio/projects/{projectId}/sounds

Scope studio:writeRetry with the same client_mutation_id

Links a ready sound from your library to a project so Create Audio can place it.

Path parameters

projectIdstringrequireduuid

Request body application/json

schema_version"studio-project-sound-source-1"required
client_mutation_idstringrequireduuid
sound_effect_idstringrequireduuid
expected_registry_versionintegerrequired≥ 1

Response 201

Project sound membership updated. Fields below are inside data.

schema_version"studio-project-sound-source-1"required
project_idstringrequireduuid
sound_effect_idstringrequireduuid
linkedbooleanrequired
sound_source_registry_versionintegerrequired≥ 1

Errors default use the standard error envelope.

curl -X POST "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/sounds" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": "studio-project-sound-source-1",
  "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "expected_registry_version": 1
}'

const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sounds`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": "studio-project-sound-source-1",
    "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "expected_registry_version": 1
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
response = requests.request(
    "POST",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sounds",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": "studio-project-sound-source-1",
      "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "expected_registry_version": 1
    },
)
payload = response.json()

Response 201 (example)

{
  "data": {
    "schema_version": "studio-project-sound-source-1",
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "linked": true,
    "sound_source_registry_version": 1
  },
  "request_id": "req_01J9Z3K8QF4"
}

Unlink a sound from a project

DELETE/studio/projects/{projectId}/sounds/{soundId}

Scope studio:writeRetry with the same client_mutation_id

Removes a sound from a project. The sound stays in your library.

Path parameters

projectIdstringrequireduuid
soundIdstringrequireduuid

Request body application/json

schema_version"studio-project-sound-source-1"required
client_mutation_idstringrequireduuid
sound_effect_idstringrequireduuid
expected_registry_versionintegerrequired≥ 1

Response 200

Project sound membership updated. Fields below are inside data.

schema_version"studio-project-sound-source-1"required
project_idstringrequireduuid
sound_effect_idstringrequireduuid
linkedbooleanrequired
sound_source_registry_versionintegerrequired≥ 1

Errors default use the standard error envelope.

curl -X DELETE "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/sounds/$SOUND_ID" \
  -H "Authorization: Bearer $LYRICWINTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "schema_version": "studio-project-sound-source-1",
  "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
  "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
  "expected_registry_version": 1
}'

const projectId = "<projectId>";
const soundId = "<soundId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/sounds/${soundId}`, {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schema_version": "studio-project-sound-source-1",
    "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "expected_registry_version": 1
  }),
});
const { data, error, request_id } = await response.json();

import os
import requests

project_id = "<projectId>"
sound_id = "<soundId>"
response = requests.request(
    "DELETE",
    f"https://lyricwinter.com/api/v1/studio/projects/{project_id}/sounds/{sound_id}",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
    json={
      "schema_version": "studio-project-sound-source-1",
      "client_mutation_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
      "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
      "expected_registry_version": 1
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": "studio-project-sound-source-1",
    "project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "sound_effect_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
    "linked": true,
    "sound_source_registry_version": 1
  },
  "request_id": "req_01J9Z3K8QF4"
}

List public sounds

GET/sounds

Scope studio:read

Lists published sounds from the public catalog shown on lyricwinter.com/sounds. No sign-in is required. Filter with q, tag, or category, and page with cursor. Each sound includes its page URL and a preview URL valid for 12 hours.

Query parameters

qstringmax 200 chars
tagstring1–40 chars
categorystringpattern ^[a-z0-9_-]{1,80}$
limitinteger1–100default 30
cursorstringpattern ^[0-9]{1,6}$

Response 200

One page of public sounds. Fields below are inside data.

schema_version"public-sound-catalog-1"required
soundsarray of objectrequiredmax 100 items
10 item attributes
- idstringrequireduuid
- namestringrequired1–120 chars
- descriptionstringrequired1–1000 chars
- tagsarray of stringrequired1–12 items
- categorystringrequired
  Catalog slug derived from the first tag.
- duration_msintegerrequired100–3900000
- page_urlstringrequireduri
- previewobjectrequired
  2 child attributes
  urlstringrequireduri
  Signed-out WAV preview that supports HTTP Range requests.
  expires_atstringrequireddate-time
- created_atstringrequireddate-time
- updated_atstringrequireddate-time
totalintegerrequired≥ 0

Errors default use the standard error envelope.

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

const response = await fetch(`https://lyricwinter.com/api/v1/sounds`, {
  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/sounds",
    headers={
        "Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
    },
)
payload = response.json()

Response 200 (example)

{
  "data": {
    "schema_version": "public-sound-catalog-1",
    "sounds": [
      {
        "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
        "name": "My integration",
        "description": "string",
        "tags": [
          "string"
        ],
        "category": "string",
        "duration_ms": 100,
        "page_url": "https://lyricwinter.com/…",
        "preview": {
          "url": "https://lyricwinter.com/…",
          "expires_at": "2026-09-30T17:00:00.000Z"
        },
        "created_at": "2026-09-30T17:00:00.000Z",
        "updated_at": "2026-09-30T17:00:00.000Z"
      }
    ],
    "total": 1
  },
  "request_id": "req_01J9Z3K8QF4"
}

Get a public sound

GET/sounds/{soundId}

Scope studio:read

Returns one published sound from the public catalog, with its page URL and a preview URL. Sounds that are private or still processing return 404.

Path parameters

soundIdstringrequireduuid

Response 200

Public sound. Fields below are inside data.

idstringrequireduuid
namestringrequired1–120 chars
descriptionstringrequired1–1000 chars
tagsarray of stringrequired1–12 items
categorystringrequired
Catalog slug derived from the first tag.
duration_msintegerrequired100–3900000
page_urlstringrequireduri
previewobjectrequired
2 child attributes
- urlstringrequireduri
  Signed-out WAV preview that supports HTTP Range requests.
- expires_atstringrequireddate-time
created_atstringrequireddate-time
updated_atstringrequireddate-time

Errors default use the standard error envelope.

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

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

import os
import requests

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

Response 200 (example)

{
  "data": {
    "id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
    "name": "My integration",
    "description": "string",
    "tags": [
      "string"
    ],
    "category": "string",
    "duration_ms": 100,
    "page_url": "https://lyricwinter.com/…",
    "preview": {
      "url": "https://lyricwinter.com/…",
      "expires_at": "2026-09-30T17:00:00.000Z"
    },
    "created_at": "2026-09-30T17:00:00.000Z",
    "updated_at": "2026-09-30T17:00:00.000Z"
  },
  "request_id": "req_01J9Z3K8QF4"
}