API reference

Sound library API

Upload your own sound effects and ambience into the Studio sound library, manage their metadata, and link them to projects so Create Audio can place them automatically.

BetaUpdated September 30, 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–300000
  mime_typestringrequired1–200 chars
  file_size_bytesintegerrequired1–62914560
  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 private sound and returns a signed upload session. Upload the file to the session URL, then call the complete endpoint. Requesting is_public: true returns 403 because public listing requires review.

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
3 child attributes
- filenamestringrequired1–255 chars
- content_typestringrequired
  One ofaudio/wavaudio/x-wavaudio/mpegaudio/oggaudio/opusaudio/flacaudio/mp4audio/aacaudio/webm
- size_bytesintegerrequired1–52428800

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–300000
  mime_typestringrequired1–200 chars
  file_size_bytesintegerrequired1–62914560
  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–300000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–62914560
- 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–300000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–62914560
- 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–300000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–62914560
- 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, or tags. A public sound must be made private before its metadata can change (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–300000
- mime_typestringrequired1–200 chars
- file_size_bytesintegerrequired1–62914560
- 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–300000
  mime_typestringrequired1–200 chars
  file_size_bytesintegerrequired1–62914560
  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"
}