Skip to content

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

Scope studio:read

Returns 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_idstringrequireduuid

    Authenticated caller; clients partition local recovery state by this ID.

  • project_idstringrequireduuid
  • documentobjectrequired

    The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.

    10 child attributes
    • blocksarray of objectrequiredmax 100000 items

      One of 6 shapes:

      kind: "speech"
      • block_versionintegerrequired> 0
      • contentobjectrequired
        6 child attributes
        • annotationsarray of objectrequired

          One of 3 shapes:

          kind: "exclusion"
          • end_utf16integerrequired≥ 0
          • 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"exclusion"required
          • reasonstringrequired

            One ofspeaker_labelstage_directionmetadatauser

          • start_utf16integerrequired≥ 0
          kind: "pronunciation"
          • alphabetstringrequired

            One ofipax-sampacmualias

          • end_utf16integerrequired≥ 0
          • 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"pronunciation"required
          • start_utf16integerrequired≥ 0
          • valuestringrequired1–500 chars
          kind: "extension"
          • end_utf16integerrequired≥ 0
          • 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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • payloadobject | nullrequired
          • start_utf16integerrequired≥ 0
          • versionintegerrequired> 0
        • delivery_control_setsarray of objectrequiredmax 32 items
          11 item attributes
          • capability_revisionstringrequired1–200 chars
          • directivesarray of StudioAstDeliveryDirectiverequiredmax 256 items
          • formatstringrequired

            One ofeleven-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-1

          • idstringrequiredpattern ^[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 chars
          • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*
          • schema_versionstringrequired

            One ofstudio-delivery-control-set-1studio-delivery-control-set-2

          • settingsarray of StudioAstDeliverySettingrequiredmax 32 items
          • source_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$
          • source_utf16_lengthinteger | nullrequired≥ 0
        • pointsarray of objectrequired

          One of 2 shapes:

          kind: "timed_silence"
          • duration_msintegerrequired1–300000
          • 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"timed_silence"required
          • offset_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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • offset_utf16integerrequired≥ 0
          • payloadobject | nullrequired
          • versionintegerrequired> 0
        • schema_version"studio-ast-2"required
        • textstringrequiredmax 65536 chars

          Exact 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 | nullrequired
        5 child attributes
        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null
        • providerstringpattern ^[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"required
      • placementany | nullrequired
      • speaker_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> 0
      • contentobjectrequired
        6 child attributes
        • annotationsarray of objectrequired

          One of 3 shapes:

          kind: "exclusion"
          • end_utf16integerrequired≥ 0
          • 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"exclusion"required
          • reasonstringrequired

            One ofspeaker_labelstage_directionmetadatauser

          • start_utf16integerrequired≥ 0
          kind: "pronunciation"
          • alphabetstringrequired

            One ofipax-sampacmualias

          • end_utf16integerrequired≥ 0
          • 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"pronunciation"required
          • start_utf16integerrequired≥ 0
          • valuestringrequired1–500 chars
          kind: "extension"
          • end_utf16integerrequired≥ 0
          • 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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • payloadobject | nullrequired
          • start_utf16integerrequired≥ 0
          • versionintegerrequired> 0
        • delivery_control_setsarray of objectrequiredmax 32 items
          11 item attributes
          • capability_revisionstringrequired1–200 chars
          • directivesarray of StudioAstDeliveryDirectiverequiredmax 256 items
          • formatstringrequired

            One ofeleven-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-1

          • idstringrequiredpattern ^[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 chars
          • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*
          • schema_versionstringrequired

            One ofstudio-delivery-control-set-1studio-delivery-control-set-2

          • settingsarray of StudioAstDeliverySettingrequiredmax 32 items
          • source_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$
          • source_utf16_lengthinteger | nullrequired≥ 0
        • pointsarray of objectrequired

          One of 2 shapes:

          kind: "timed_silence"
          • duration_msintegerrequired1–300000
          • 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"timed_silence"required
          • offset_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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • offset_utf16integerrequired≥ 0
          • payloadobject | nullrequired
          • versionintegerrequired> 0
        • schema_version"studio-ast-2"required
        • textstringrequiredmax 65536 chars

          Exact 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 | nullrequired
        5 child attributes
        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null
        • providerstringpattern ^[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"required
      • placementany | nullrequired
      • speaker_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> 0
      • contentobjectrequired
        6 child attributes
        • annotationsarray of objectrequired

          One of 3 shapes:

          kind: "exclusion"
          • end_utf16integerrequired≥ 0
          • 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"exclusion"required
          • reasonstringrequired

            One ofspeaker_labelstage_directionmetadatauser

          • start_utf16integerrequired≥ 0
          kind: "pronunciation"
          • alphabetstringrequired

            One ofipax-sampacmualias

          • end_utf16integerrequired≥ 0
          • 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"pronunciation"required
          • start_utf16integerrequired≥ 0
          • valuestringrequired1–500 chars
          kind: "extension"
          • end_utf16integerrequired≥ 0
          • 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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • payloadobject | nullrequired
          • start_utf16integerrequired≥ 0
          • versionintegerrequired> 0
        • delivery_control_setsarray of objectrequiredmax 32 items
          11 item attributes
          • capability_revisionstringrequired1–200 chars
          • directivesarray of StudioAstDeliveryDirectiverequiredmax 256 items
          • formatstringrequired

            One ofeleven-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-1

          • idstringrequiredpattern ^[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 chars
          • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*
          • schema_versionstringrequired

            One ofstudio-delivery-control-set-1studio-delivery-control-set-2

          • settingsarray of StudioAstDeliverySettingrequiredmax 32 items
          • source_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$
          • source_utf16_lengthinteger | nullrequired≥ 0
        • pointsarray of objectrequired

          One of 2 shapes:

          kind: "timed_silence"
          • duration_msintegerrequired1–300000
          • 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"timed_silence"required
          • offset_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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • offset_utf16integerrequired≥ 0
          • payloadobject | nullrequired
          • versionintegerrequired> 0
        • schema_version"studio-ast-2"required
        • textstringrequiredmax 65536 chars

          Exact 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 | nullrequired
        5 child attributes
        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null
        • providerstringpattern ^[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"required
      • placementany | nullrequired
      • speaker_idany | nullrequired
      kind: "excluded"
      • block_versionintegerrequired> 0
      • contentobjectrequired
        6 child attributes
        • annotationsarray of objectrequired

          One of 3 shapes:

          kind: "exclusion"
          • end_utf16integerrequired≥ 0
          • 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"exclusion"required
          • reasonstringrequired

            One ofspeaker_labelstage_directionmetadatauser

          • start_utf16integerrequired≥ 0
          kind: "pronunciation"
          • alphabetstringrequired

            One ofipax-sampacmualias

          • end_utf16integerrequired≥ 0
          • 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"pronunciation"required
          • start_utf16integerrequired≥ 0
          • valuestringrequired1–500 chars
          kind: "extension"
          • end_utf16integerrequired≥ 0
          • 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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • payloadobject | nullrequired
          • start_utf16integerrequired≥ 0
          • versionintegerrequired> 0
        • delivery_control_setsarray of objectrequiredmax 32 items
          11 item attributes
          • capability_revisionstringrequired1–200 chars
          • directivesarray of StudioAstDeliveryDirectiverequiredmax 256 items
          • formatstringrequired

            One ofeleven-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-1

          • idstringrequiredpattern ^[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 chars
          • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • provider_text_overridestring1–65536 charspattern [\s\S]*\S[\s\S]*
          • schema_versionstringrequired

            One ofstudio-delivery-control-set-1studio-delivery-control-set-2

          • settingsarray of StudioAstDeliverySettingrequiredmax 32 items
          • source_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$
          • source_utf16_lengthinteger | nullrequired≥ 0
        • pointsarray of objectrequired

          One of 2 shapes:

          kind: "timed_silence"
          • duration_msintegerrequired1–300000
          • 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"timed_silence"required
          • offset_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"required
          • namestringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
          • namespacestringrequiredpattern ^[a-z][a-z0-9_.-]{0,63}$
          • offset_utf16integerrequired≥ 0
          • payloadobject | nullrequired
          • versionintegerrequired> 0
        • schema_version"studio-ast-2"required
        • textstringrequiredmax 65536 chars

          Exact 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 | nullrequired
        5 child attributes
        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null
        • providerstringpattern ^[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"required
      • placementany | nullrequired
      • speaker_idany | nullrequired
      kind: "note"
      • block_versionintegerrequired> 0
      • contentobjectrequired
        3 child attributes
        • schema_version"studio-ast-2"required
        • textstringrequiredmax 20000 chars
        • type"note"required
      • generation_profile_overrideobject | nullrequired
        5 child attributes
        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null
        • providerstringpattern ^[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"required
      • placementany | nullrequired
      • speaker_idany | nullrequired
      kind: "sfx"
      • block_versionintegerrequired> 0
      • contentobjectrequired
        6 child attributes
        • duration_msintegerrequired100–300000
        • promptstringrequired1–4000 chars
        • schema_version"studio-ast-2"required
        • seedinteger | nullrequired≥ -9007199254740991
        • type"sfx"required
        • sourceobject

          Present only when the SFX block plays an uploaded project sound; seed is then null.

          3 child attributes
          • kind"project_sound"required
          • sound_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 | nullrequired
        5 child attributes
        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null
        • providerstringpattern ^[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"required
      • placementobjectrequired
        5 child attributes
        • anchorobjectrequired

          One 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–1
          • kind"block"required
          • positionstringrequired

            One ofstartfractionendafter

          kind: "section"
          • kind"section"required
          • positionstringrequired

            One ofstartend

          kind: "unplaced"
          • kind"unplaced"required
        • fade_in_msintegerrequired0–300000
        • fade_out_msintegerrequired0–300000
        • gain_dbnumberrequired-60–24
        • offset_msintegerrequired-300000–300000
      • speaker_idany | nullrequired
    • different_speaker_gap_msintegerrequired0–1000

      Silence in milliseconds inserted between adjacent spoken blocks with different speakers.

    • document_versionintegerrequired> 0
    • sfx_enabledbooleanrequired

      Whether 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–1000

      Silence in milliseconds inserted between adjacent spoken blocks with the same speaker.

    • schema_version"studio-ast-2"required
    • section_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> 0

      Project-wide speaker registry version the speakers list was read at.

    • speakersarray of objectrequired

      Every active speaker in the project registry, not only speakers referenced by this section.

      5 item attributes
      • generation_profileobject | nullrequired
        5 child attributes
        • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
        • modelstringrequired1–200 chars
        • fallbackstringrequired

          One ofstrictbest_effort

        • controlsstringrequired

          One ofstrictbest_effort

        • optionsobjectrequired
      • 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 chars
      • speaker_versionintegerrequired> 0
      • voice_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 | nullrequired

    The caller's saved, uncommitted Advanced Source draft for this section, or null.

    6 child attributes
    • source_textstringrequired
    • base_document_versionintegerrequired≥ 1
    • base_speaker_registry_versionintegerrequired≥ 1
    • base_speaker_versionsmap of integerrequired

      Speaker versions keyed by speaker ID when the draft began.

    • diagnosticsarray of objectrequiredmax 1000 items
      2 item attributes
      • codestringrequired

        One ofINVALID_SOURCESTALE_SOURCE

      • messagestringrequired1–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"
Response 200 (example)
{
  "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

Scope studio:writeRetry with the same client_mutation_id

Applies 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_version1required
  • actor_session_idstringrequireduuid
  • client_mutation_idstringrequireduuid
  • base_document_versionintegerrequired≥ 1
  • base_speaker_registry_versionintegerrequired≥ 1
  • target_block_versionsmap of integerrequired
  • target_speaker_versionsmap of integerrequired
  • commandsarray of objectrequired1–1000 items

    One of 2 shapes:

    kind: "set_section_sfx_enabled"
    • kind"set_section_sfx_enabled"required
    • sfx_enabledbooleanrequired

      Whether authored section sound effects are audible in playback and included in rendered exports. Disabling preserves authored SFX blocks and renditions.

    Option 2
    • kindstringrequired

Response 200

Authoritative document after commit or idempotent replay. Fields below are inside data.

  • actor_user_idstringrequireduuid

    Authenticated caller; clients partition local recovery state by this ID.

  • project_idstringrequireduuid
  • documentobjectrequired

    The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.

    Full shape: Get a section document

  • source_draftobject | nullrequired

    The caller's saved, uncommitted Advanced Source draft for this section, or null.

    6 child attributes
    • source_textstringrequired
    • base_document_versionintegerrequired≥ 1
    • base_speaker_registry_versionintegerrequired≥ 1
    • base_speaker_versionsmap of integerrequired

      Speaker versions keyed by speaker ID when the draft began.

    • diagnosticsarray of objectrequiredmax 1000 items
      2 item attributes
      • codestringrequired

        One ofINVALID_SOURCESTALE_SOURCE

      • messagestringrequired1–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
    }
  ]
}'
Response 200 (example)
{
  "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

Scope studio:writeRetry with the same client_mutation_id

Turn 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_version1required
  • actor_session_idstringrequireduuid
  • client_mutation_idstringrequireduuid
  • base_document_versionintegerrequired≥ 1
  • base_speaker_registry_versionintegerrequired≥ 1
  • scriptstringrequiredmin 1 chars

    One 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 objectrequired

    Exact 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 | nullrequireduuid
    • generation_profileobjectrequired
      5 child attributes
      • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
      • modelstringrequired1–200 chars
      • fallbackstringrequired

        One ofstrictbest_effort

      • controlsstringrequired

        One ofstrictbest_effort

      • optionsobjectrequired

Response 200

Canonical Studio document after the import. Fields below are inside data.

  • actor_user_idstringrequireduuid

    Authenticated caller; clients partition local recovery state by this ID.

  • project_idstringrequireduuid
  • documentobjectrequired

    The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks.

    Full shape: Get a section document

  • source_draftobject | nullrequired

    The caller's saved, uncommitted Advanced Source draft for this section, or null.

    6 child attributes
    • source_textstringrequired
    • base_document_versionintegerrequired≥ 1
    • base_speaker_registry_versionintegerrequired≥ 1
    • base_speaker_versionsmap of integerrequired

      Speaker versions keyed by speaker ID when the draft began.

    • diagnosticsarray of objectrequiredmax 1000 items
      2 item attributes
      • codestringrequired

        One ofINVALID_SOURCESTALE_SOURCE

      • messagestringrequired1–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": {}
}'
Response 200 (example)
{
  "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

Scope studio:read

Returns 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_idstringrequireduuid
  • speaker_registry_versionintegerrequired≥ 1
  • speakersarray of objectrequiredmax 10000 items

    Every active project speaker, including unused speakers with zero counts.

    4 item attributes
    • speaker_idstringrequireduuid
    • line_countintegerrequired≥ 0

      Active speech and narration blocks assigned to the speaker across active sections.

    • block_override_countintegerrequired≥ 0

      Of those blocks, how many carry a block-level generation profile override.

    • section_countintegerrequired≥ 0

      Active 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"
Response 200 (example)
{
  "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"
}