API reference
Documents and speakers API
Every section has a versioned document of narration and dialogue blocks attributed to speakers. Read the document before editing it or generating audio, and list the project's speakers and casting.
BetaUpdated
- Base URL
- https://lyricwinter.com/api/v1
- Authentication
- Authorization: Bearer lw_…
- Contract
- openapi.json
Get a section document
GET/studio/sections/{sectionId}/document
studio:readReturns the section's current document: its document_version, blocks, the project's speakers and speaker_registry_version, and whether section sound effects are enabled. Read it before editing the section or generating audio.
Path parameters
sectionIdstringrequireduuid
Response 200
Canonical Studio document and optional recovery draft. Fields below are inside data.
actor_user_idstringrequireduuidAuthenticated caller; clients partition local recovery state by this ID.
project_idstringrequireduuiddocumentobjectrequiredThe canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
10 child attributes
blocksarray of objectrequiredmax 100000 itemsOne of 6 shapes:
kind: "speech"block_versionintegerrequired> 0contentobjectrequired6 child attributes
annotationsarray of objectrequiredOne of 3 shapes:
kind: "exclusion"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"exclusion"requiredreasonstringrequiredOne of
speaker_labelstage_directionmetadatauserstart_utf16integerrequired≥ 0
kind: "pronunciation"alphabetstringrequiredOne of
ipax-sampacmualiasend_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"pronunciation"requiredstart_utf16integerrequired≥ 0valuestringrequired1–500 chars
kind: "extension"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$payloadobject | nullrequiredstart_utf16integerrequired≥ 0versionintegerrequired> 0
delivery_control_setsarray of objectrequiredmax 32 items11 item attributes
capability_revisionstringrequired1–200 charsdirectivesarray of StudioAstDeliveryDirectiverequiredmax 256 itemsformatstringrequiredOne of
eleven-v4-1inworld-tts2-1inworld-tts2-experimental-1inworld-tts15-max-1inworld-tts15-mini-1fish-s2-inline-1fish-s2.1-inline-1cartesia-sonic35-1openai-gpt4o-mini-tts-1openai-tts1-hd-1openai-tts1-1smallest-lightning31-1chatterbox-classic-1zyphra-zonos2-cloud-1f5tts-v1-1misotts-8b-1idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$modelstringrequired1–200 charsproviderstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*schema_versionstringrequiredOne of
studio-delivery-control-set-1studio-delivery-control-set-2settingsarray of StudioAstDeliverySettingrequiredmax 32 itemssource_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$source_utf16_lengthinteger | nullrequired≥ 0
pointsarray of objectrequiredOne of 2 shapes:
kind: "timed_silence"duration_msintegerrequired1–300000idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"timed_silence"requiredoffset_utf16integerrequired≥ 0
kind: "extension"idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$offset_utf16integerrequired≥ 0payloadobject | nullrequiredversionintegerrequired> 0
schema_version"studio-ast-2"requiredtextstringrequiredmax 65536 charsExact block text; at most 65,536 UTF-16 code units. Annotation, point, and delivery offsets are UTF-16 offsets into this string.
type"text"required
generation_profile_overrideobject | nullrequired5 child attributes
controlsstringOne of
strictbest_effortfallbackstringOne of
strictbest_effortmodelstring1–200 charsoptionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | nullproviderstringpattern ^[a-z][a-z0-9_-]{0,63}$
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"speech"requiredplacementany | nullrequiredspeaker_idstring | nullrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
kind: "narration"block_versionintegerrequired> 0contentobjectrequired6 child attributes
annotationsarray of objectrequiredOne of 3 shapes:
kind: "exclusion"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"exclusion"requiredreasonstringrequiredOne of
speaker_labelstage_directionmetadatauserstart_utf16integerrequired≥ 0
kind: "pronunciation"alphabetstringrequiredOne of
ipax-sampacmualiasend_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"pronunciation"requiredstart_utf16integerrequired≥ 0valuestringrequired1–500 chars
kind: "extension"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$payloadobject | nullrequiredstart_utf16integerrequired≥ 0versionintegerrequired> 0
delivery_control_setsarray of objectrequiredmax 32 items11 item attributes
capability_revisionstringrequired1–200 charsdirectivesarray of StudioAstDeliveryDirectiverequiredmax 256 itemsformatstringrequiredOne of
eleven-v4-1inworld-tts2-1inworld-tts2-experimental-1inworld-tts15-max-1inworld-tts15-mini-1fish-s2-inline-1fish-s2.1-inline-1cartesia-sonic35-1openai-gpt4o-mini-tts-1openai-tts1-hd-1openai-tts1-1smallest-lightning31-1chatterbox-classic-1zyphra-zonos2-cloud-1f5tts-v1-1misotts-8b-1idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$modelstringrequired1–200 charsproviderstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*schema_versionstringrequiredOne of
studio-delivery-control-set-1studio-delivery-control-set-2settingsarray of StudioAstDeliverySettingrequiredmax 32 itemssource_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$source_utf16_lengthinteger | nullrequired≥ 0
pointsarray of objectrequiredOne of 2 shapes:
kind: "timed_silence"duration_msintegerrequired1–300000idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"timed_silence"requiredoffset_utf16integerrequired≥ 0
kind: "extension"idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$offset_utf16integerrequired≥ 0payloadobject | nullrequiredversionintegerrequired> 0
schema_version"studio-ast-2"requiredtextstringrequiredmax 65536 charsExact block text; at most 65,536 UTF-16 code units. Annotation, point, and delivery offsets are UTF-16 offsets into this string.
type"text"required
generation_profile_overrideobject | nullrequired5 child attributes
controlsstringOne of
strictbest_effortfallbackstringOne of
strictbest_effortmodelstring1–200 charsoptionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | nullproviderstringpattern ^[a-z][a-z0-9_-]{0,63}$
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"narration"requiredplacementany | nullrequiredspeaker_idstring | nullrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
kind: "unparsed"block_versionintegerrequired> 0contentobjectrequired6 child attributes
annotationsarray of objectrequiredOne of 3 shapes:
kind: "exclusion"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"exclusion"requiredreasonstringrequiredOne of
speaker_labelstage_directionmetadatauserstart_utf16integerrequired≥ 0
kind: "pronunciation"alphabetstringrequiredOne of
ipax-sampacmualiasend_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"pronunciation"requiredstart_utf16integerrequired≥ 0valuestringrequired1–500 chars
kind: "extension"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$payloadobject | nullrequiredstart_utf16integerrequired≥ 0versionintegerrequired> 0
delivery_control_setsarray of objectrequiredmax 32 items11 item attributes
capability_revisionstringrequired1–200 charsdirectivesarray of StudioAstDeliveryDirectiverequiredmax 256 itemsformatstringrequiredOne of
eleven-v4-1inworld-tts2-1inworld-tts2-experimental-1inworld-tts15-max-1inworld-tts15-mini-1fish-s2-inline-1fish-s2.1-inline-1cartesia-sonic35-1openai-gpt4o-mini-tts-1openai-tts1-hd-1openai-tts1-1smallest-lightning31-1chatterbox-classic-1zyphra-zonos2-cloud-1f5tts-v1-1misotts-8b-1idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$modelstringrequired1–200 charsproviderstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*schema_versionstringrequiredOne of
studio-delivery-control-set-1studio-delivery-control-set-2settingsarray of StudioAstDeliverySettingrequiredmax 32 itemssource_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$source_utf16_lengthinteger | nullrequired≥ 0
pointsarray of objectrequiredOne of 2 shapes:
kind: "timed_silence"duration_msintegerrequired1–300000idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"timed_silence"requiredoffset_utf16integerrequired≥ 0
kind: "extension"idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$offset_utf16integerrequired≥ 0payloadobject | nullrequiredversionintegerrequired> 0
schema_version"studio-ast-2"requiredtextstringrequiredmax 65536 charsExact block text; at most 65,536 UTF-16 code units. Annotation, point, and delivery offsets are UTF-16 offsets into this string.
type"text"required
generation_profile_overrideobject | nullrequired5 child attributes
controlsstringOne of
strictbest_effortfallbackstringOne of
strictbest_effortmodelstring1–200 charsoptionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | nullproviderstringpattern ^[a-z][a-z0-9_-]{0,63}$
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"unparsed"requiredplacementany | nullrequiredspeaker_idany | nullrequired
kind: "excluded"block_versionintegerrequired> 0contentobjectrequired6 child attributes
annotationsarray of objectrequiredOne of 3 shapes:
kind: "exclusion"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"exclusion"requiredreasonstringrequiredOne of
speaker_labelstage_directionmetadatauserstart_utf16integerrequired≥ 0
kind: "pronunciation"alphabetstringrequiredOne of
ipax-sampacmualiasend_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"pronunciation"requiredstart_utf16integerrequired≥ 0valuestringrequired1–500 chars
kind: "extension"end_utf16integerrequired≥ 0idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$payloadobject | nullrequiredstart_utf16integerrequired≥ 0versionintegerrequired> 0
delivery_control_setsarray of objectrequiredmax 32 items11 item attributes
capability_revisionstringrequired1–200 charsdirectivesarray of StudioAstDeliveryDirectiverequiredmax 256 itemsformatstringrequiredOne of
eleven-v4-1inworld-tts2-1inworld-tts2-experimental-1inworld-tts15-max-1inworld-tts15-mini-1fish-s2-inline-1fish-s2.1-inline-1cartesia-sonic35-1openai-gpt4o-mini-tts-1openai-tts1-hd-1openai-tts1-1smallest-lightning31-1chatterbox-classic-1zyphra-zonos2-cloud-1f5tts-v1-1misotts-8b-1idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$modelstringrequired1–200 charsproviderstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*schema_versionstringrequiredOne of
studio-delivery-control-set-1studio-delivery-control-set-2settingsarray of StudioAstDeliverySettingrequiredmax 32 itemssource_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$source_utf16_lengthinteger | nullrequired≥ 0
pointsarray of objectrequiredOne of 2 shapes:
kind: "timed_silence"duration_msintegerrequired1–300000idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"timed_silence"requiredoffset_utf16integerrequired≥ 0
kind: "extension"idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"extension"requirednamestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$offset_utf16integerrequired≥ 0payloadobject | nullrequiredversionintegerrequired> 0
schema_version"studio-ast-2"requiredtextstringrequiredmax 65536 charsExact block text; at most 65,536 UTF-16 code units. Annotation, point, and delivery offsets are UTF-16 offsets into this string.
type"text"required
generation_profile_overrideobject | nullrequired5 child attributes
controlsstringOne of
strictbest_effortfallbackstringOne of
strictbest_effortmodelstring1–200 charsoptionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | nullproviderstringpattern ^[a-z][a-z0-9_-]{0,63}$
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"excluded"requiredplacementany | nullrequiredspeaker_idany | nullrequired
kind: "note"block_versionintegerrequired> 0contentobjectrequired3 child attributes
schema_version"studio-ast-2"requiredtextstringrequiredmax 20000 charstype"note"required
generation_profile_overrideobject | nullrequired5 child attributes
controlsstringOne of
strictbest_effortfallbackstringOne of
strictbest_effortmodelstring1–200 charsoptionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | nullproviderstringpattern ^[a-z][a-z0-9_-]{0,63}$
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"note"requiredplacementany | nullrequiredspeaker_idany | nullrequired
kind: "sfx"block_versionintegerrequired> 0contentobjectrequired6 child attributes
duration_msintegerrequired100–300000promptstringrequired1–4000 charsschema_version"studio-ast-2"requiredseedinteger | nullrequired≥ -9007199254740991type"sfx"requiredsourceobjectPresent only when the SFX block plays an uploaded project sound; seed is then null.
3 child attributes
kind"project_sound"requiredsound_effect_idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$sound_effect_revision_idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
generation_profile_overrideobject | nullrequired5 child attributes
controlsstringOne of
strictbest_effortfallbackstringOne of
strictbest_effortmodelstring1–200 charsoptionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | nullproviderstringpattern ^[a-z][a-z0-9_-]{0,63}$
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$kind"sfx"requiredplacementobjectrequired5 child attributes
anchorobjectrequiredOne of 3 shapes:
kind: "block"block_idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$fractionnumber | nullrequired0–1kind"block"requiredpositionstringrequiredOne of
startfractionendafter
kind: "section"kind"section"requiredpositionstringrequiredOne of
startend
kind: "unplaced"kind"unplaced"required
fade_in_msintegerrequired0–300000fade_out_msintegerrequired0–300000gain_dbnumberrequired-60–24offset_msintegerrequired-300000–300000
speaker_idany | nullrequired
different_speaker_gap_msintegerrequired0–1000Silence in milliseconds inserted between adjacent spoken blocks with different speakers.
document_versionintegerrequired> 0sfx_enabledbooleanrequiredWhether authored section sound effects are audible in playback and included in rendered exports. Legacy sections without a stored value report true.
same_speaker_gap_msintegerrequired0–1000Silence in milliseconds inserted between adjacent spoken blocks with the same speaker.
schema_version"studio-ast-2"requiredsection_idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$Canonical lowercase UUID of the section.
speaker_registry_versionintegerrequired> 0Project-wide speaker registry version the speakers list was read at.
speakersarray of objectrequiredEvery active speaker in the project registry, not only speakers referenced by this section.
5 item attributes
generation_profileobject | nullrequired5 child attributes
providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$modelstringrequired1–200 charsfallbackstringrequiredOne of
strictbest_effortcontrolsstringrequiredOne of
strictbest_effortoptionsobjectrequired
idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$namestringrequired1–200 charsspeaker_versionintegerrequired> 0voice_idstring | nullrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
titlestringrequiredmax 500 chars
source_draftobject | nullrequiredThe caller's saved, uncommitted Advanced Source draft for this section, or null.
6 child attributes
source_textstringrequiredbase_document_versionintegerrequired≥ 1base_speaker_registry_versionintegerrequired≥ 1base_speaker_versionsmap of integerrequiredSpeaker versions keyed by speaker ID when the draft began.
diagnosticsarray of objectrequiredmax 1000 items2 item attributes
codestringrequiredOne of
INVALID_SOURCESTALE_SOURCEmessagestringrequired1–2000 chars
updated_atstringrequireddate-time
Errors 400, 401, 403, 404, 500 use the standard error envelope.
curl "https://lyricwinter.com/api/v1/studio/sections/$SECTION_ID/document" \
-H "Authorization: Bearer $LYRICWINTER_API_KEY"const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sections/${sectionId}/document`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
},
});
const { data, error, request_id } = await response.json();import os
import requests
section_id = "<sectionId>"
response = requests.request(
"GET",
f"https://lyricwinter.com/api/v1/studio/sections/{section_id}/document",
headers={
"Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
},
)
payload = response.json(){
"data": {
"actor_user_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"document": {
"blocks": [
{
"block_version": 1,
"content": {
"annotations": [
{
"end_utf16": null,
"id": null,
"kind": "exclusion",
"reason": "speaker_label",
"start_utf16": null
}
],
"delivery_control_sets": [
{
"capability_revision": null,
"directives": [],
"format": "eleven-v4-1",
"id": null,
"model": null,
"provider": null,
"provider_text_override": null,
"schema_version": "studio-delivery-control-set-1",
"settings": [],
"source_fingerprint": null,
"source_utf16_length": null
}
],
"points": [
{
"duration_ms": null,
"id": null,
"kind": "timed_silence",
"offset_utf16": null
}
],
"schema_version": "studio-ast-2",
"text": "A bell rang. \"Who is there?\" Mira asked.",
"type": "text"
},
"generation_profile_override": {
"controls": "strict",
"fallback": "strict",
"model": "string",
"options": {},
"provider": "string"
},
"id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
"kind": "speech",
"placement": null,
"speaker_id": "d3d94468-02a4-4c5e-b6f7-0a1b2c3d4e40"
}
],
"different_speaker_gap_ms": 1,
"document_version": 1,
"sfx_enabled": true,
"same_speaker_gap_ms": 1,
"schema_version": "studio-ast-2",
"section_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"speaker_registry_version": 1,
"speakers": [
{
"generation_profile": {
"provider": "string",
"model": "string",
"fallback": "strict",
"controls": "strict",
"options": {}
},
"id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"name": "My integration",
"speaker_version": 1,
"voice_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30"
}
],
"title": "Chapter One"
},
"source_draft": {
"source_text": "string",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"base_speaker_versions": {},
"diagnostics": [
{
"code": "INVALID_SOURCE",
"message": "string"
}
],
"updated_at": "2026-09-30T17:00:00.000Z"
}
},
"request_id": "req_01J9Z3K8QF4"
}Edit a section document
PATCH/studio/sections/{sectionId}/document
studio:writeRetry with the same client_mutation_idApplies a batch of document commands against the versions you last read. The whole batch commits atomically; if any targeted version changed, the request fails with 409 and nothing is applied.
Path parameters
sectionIdstringrequireduuid
Request body application/json
schema_version1requiredactor_session_idstringrequireduuidclient_mutation_idstringrequireduuidbase_document_versionintegerrequired≥ 1base_speaker_registry_versionintegerrequired≥ 1target_block_versionsmap of integerrequiredtarget_speaker_versionsmap of integerrequiredcommandsarray of objectrequired1–1000 itemsOne of 2 shapes:
kind: "set_section_sfx_enabled"kind"set_section_sfx_enabled"requiredsfx_enabledbooleanrequiredWhether authored section sound effects are audible in playback and included in rendered exports. Disabling preserves authored SFX blocks and renditions.
Option 2kindstringrequired
Response 200
Authoritative document after commit or idempotent replay. Fields below are inside data.
actor_user_idstringrequireduuidAuthenticated caller; clients partition local recovery state by this ID.
project_idstringrequireduuiddocumentobjectrequiredThe canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
Full shape: Get a section document
source_draftobject | nullrequiredThe caller's saved, uncommitted Advanced Source draft for this section, or null.
6 child attributes
source_textstringrequiredbase_document_versionintegerrequired≥ 1base_speaker_registry_versionintegerrequired≥ 1base_speaker_versionsmap of integerrequiredSpeaker versions keyed by speaker ID when the draft began.
diagnosticsarray of objectrequiredmax 1000 items2 item attributes
codestringrequiredOne of
INVALID_SOURCESTALE_SOURCEmessagestringrequired1–2000 chars
updated_atstringrequireddate-time
Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.
curl -X PATCH "https://lyricwinter.com/api/v1/studio/sections/$SECTION_ID/document" \
-H "Authorization: Bearer $LYRICWINTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"schema_version": 1,
"actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"target_block_versions": {},
"target_speaker_versions": {},
"commands": [
{
"kind": "set_section_sfx_enabled",
"sfx_enabled": true
}
]
}'const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sections/${sectionId}/document`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"schema_version": 1,
"actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"target_block_versions": {},
"target_speaker_versions": {},
"commands": [
{
"kind": "set_section_sfx_enabled",
"sfx_enabled": true
}
]
}),
});
const { data, error, request_id } = await response.json();import os
import requests
section_id = "<sectionId>"
response = requests.request(
"PATCH",
f"https://lyricwinter.com/api/v1/studio/sections/{section_id}/document",
headers={
"Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
},
json={
"schema_version": 1,
"actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"target_block_versions": {},
"target_speaker_versions": {},
"commands": [
{
"kind": "set_section_sfx_enabled",
"sfx_enabled": True
}
]
},
)
payload = response.json(){
"data": {
"actor_user_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"document": {
"blocks": [],
"different_speaker_gap_ms": 1,
"document_version": 1,
"sfx_enabled": true,
"same_speaker_gap_ms": 1,
"schema_version": "studio-ast-2",
"section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
"speaker_registry_version": 1,
"speakers": [],
"title": "Chapter One"
},
"source_draft": {
"source_text": "string",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"base_speaker_versions": {},
"diagnostics": [
{
"code": "INVALID_SOURCE",
"message": "string"
}
],
"updated_at": "2026-09-30T17:00:00.000Z"
}
},
"request_id": "req_01J9Z3K8QF4"
}Import a speaker-labeled script
POST/studio/sections/{sectionId}/script
studio:writeRetry with the same client_mutation_idTurn SPEAKER: [optional direction] spoken text lines into a Studio document without building an AST. Map each speaker label to a voice and generation profile. A separate (silence 4s) line adds exact silence after the preceding spoken line. Unsupported lines or directions fail rather than disappearing. This replaces the section script; it does not generate audio. Send the current document and speaker-registry versions. Reusing an existing speaker name updates that project-wide speaker's voice and profile. Retry uncertain responses with the same mutation ID and body; a receipt that cannot be verified returns 409 without importing again.
Path parameters
sectionIdstringrequireduuid
Request body application/json
schema_version1requiredactor_session_idstringrequireduuidclient_mutation_idstringrequireduuidbase_document_versionintegerrequired≥ 1base_speaker_registry_versionintegerrequired≥ 1scriptstringrequiredmin 1 charsOne SPEAKER: [optional direction] spoken text per nonblank line. A separate (silence 4s) or (silence 4000ms) line adds 1-300 seconds of silence after the preceding spoken line. Labels match speaker-map keys exactly. Unsupported lines are rejected.
speakersmap of objectrequiredExact speaker-label keys used in the script, each with an explicit voice and generation profile. Existing project speakers with the same name are reused.
2 child attributes
voice_idstring | nullrequireduuidgeneration_profileobjectrequired5 child attributes
providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$modelstringrequired1–200 charsfallbackstringrequiredOne of
strictbest_effortcontrolsstringrequiredOne of
strictbest_effortoptionsobjectrequired
Response 200
Canonical Studio document after the import. Fields below are inside data.
actor_user_idstringrequireduuidAuthenticated caller; clients partition local recovery state by this ID.
project_idstringrequireduuiddocumentobjectrequiredThe canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.
Full shape: Get a section document
source_draftobject | nullrequiredThe caller's saved, uncommitted Advanced Source draft for this section, or null.
6 child attributes
source_textstringrequiredbase_document_versionintegerrequired≥ 1base_speaker_registry_versionintegerrequired≥ 1base_speaker_versionsmap of integerrequiredSpeaker versions keyed by speaker ID when the draft began.
diagnosticsarray of objectrequiredmax 1000 items2 item attributes
codestringrequiredOne of
INVALID_SOURCESTALE_SOURCEmessagestringrequired1–2000 chars
updated_atstringrequireddate-time
Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.
curl -X POST "https://lyricwinter.com/api/v1/studio/sections/$SECTION_ID/script" \
-H "Authorization: Bearer $LYRICWINTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"schema_version": 1,
"actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"script": "string",
"speakers": {}
}'const sectionId = "<sectionId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/sections/${sectionId}/script`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LYRICWINTER_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"schema_version": 1,
"actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"script": "string",
"speakers": {}
}),
});
const { data, error, request_id } = await response.json();import os
import requests
section_id = "<sectionId>"
response = requests.request(
"POST",
f"https://lyricwinter.com/api/v1/studio/sections/{section_id}/script",
headers={
"Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
},
json={
"schema_version": 1,
"actor_session_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"client_mutation_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"script": "string",
"speakers": {}
},
)
payload = response.json(){
"data": {
"actor_user_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"project_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"document": {
"blocks": [],
"different_speaker_gap_ms": 1,
"document_version": 1,
"sfx_enabled": true,
"same_speaker_gap_ms": 1,
"schema_version": "studio-ast-2",
"section_id": "45c48cce-2e2d-4fbd-8a1c-5e6f7a8b9c30",
"speaker_registry_version": 1,
"speakers": [],
"title": "Chapter One"
},
"source_draft": {
"source_text": "string",
"base_document_version": 1,
"base_speaker_registry_version": 1,
"base_speaker_versions": {},
"diagnostics": [
{
"code": "INVALID_SOURCE",
"message": "string"
}
],
"updated_at": "2026-09-30T17:00:00.000Z"
}
},
"request_id": "req_01J9Z3K8QF4"
}List project speakers
GET/studio/projects/{projectId}/speakers
studio:readReturns the project's speakers with how many lines and sections each one appears in, plus the current speaker_registry_version.
Path parameters
projectIdstringrequireduuid
Response 200
Project-wide character usage and current character registry authority. Fields below are inside data.
project_idstringrequireduuidspeaker_registry_versionintegerrequired≥ 1speakersarray of objectrequiredmax 10000 itemsEvery active project speaker, including unused speakers with zero counts.
4 item attributes
speaker_idstringrequireduuidline_countintegerrequired≥ 0Active speech and narration blocks assigned to the speaker across active sections.
block_override_countintegerrequired≥ 0Of those blocks, how many carry a block-level generation profile override.
section_countintegerrequired≥ 0Active sections containing at least one of those blocks.
Errors 400, 401, 403, 404, 500 use the standard error envelope.
curl "https://lyricwinter.com/api/v1/studio/projects/$PROJECT_ID/speakers" \
-H "Authorization: Bearer $LYRICWINTER_API_KEY"const projectId = "<projectId>";
const response = await fetch(`https://lyricwinter.com/api/v1/studio/projects/${projectId}/speakers`, {
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}/speakers",
headers={
"Authorization": f"Bearer {os.environ['LYRICWINTER_API_KEY']}",
},
)
payload = response.json(){
"data": {
"project_id": "8f14e45f-ceea-4e7a-9c2d-3b1a5f2e7c10",
"speaker_registry_version": 1,
"speakers": [
{
"speaker_id": "c9f0f895-fb98-4b91-9e3f-1d2a6b7c8d20",
"line_count": 1,
"block_override_count": 1,
"section_count": 1
}
]
},
"request_id": "req_01J9Z3K8QF4"
}