Documents and speakers API

Get a section document

GET/studio/sections/{sectionId}/document

Path parameters

• sectionIdstringrequireduuid

Errors 400, 401, 403, 404, 500 use the standard error envelope.

Edit a section document

PATCH/studio/sections/{sectionId}/document

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 24 shapes:

  kind: "set_title"

  • kind"set_title"required
  • titlestringrequiredmax 500 chars

  kind: "set_section_pacing"

  Set silence between consecutive audible passages without replacing the script. Both gaps are required; normal document and cast version checks apply.

  • kind"set_section_pacing"required
  • same_speaker_gap_msintegerrequired0–1000
  • different_speaker_gap_msintegerrequired0–1000

  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.

  kind: "replace_text"

  Offsets are UTF-16 indices. Runtime also verifies the expected text hash and range against the current block.

  • kind"replace_text"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • start_utf16integerrequired≥ 0
  • end_utf16integerrequired≥ 0
  • expected_text_hashstringrequiredpattern ^[0-9a-f]{64}$
  • textstringrequired

  kind: "insert_block"

  • kind"insert_block"required
  • indexintegerrequired≥ 0
  • blockobjectrequired

    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-1fish-drama-3-inline-1cartesia-sonic36-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

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      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-1fish-drama-3-inline-1cartesia-sonic36-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

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      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-1fish-drama-3-inline-1cartesia-sonic36-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

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      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-1fish-drama-3-inline-1cartesia-sonic36-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

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      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

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      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–3900000

        Generated sound effects (no source) allow up to 300000 ms; a pinned project sound allows up to 3900000 ms.

      • 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

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      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

  kind: "delete_block"

  • kind"delete_block"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

  kind: "move_block"

  • kind"move_block"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • to_indexintegerrequired≥ 0

  kind: "create_sfx"

  For an uploaded project sound, use content.source.kind=project_sound, seed=null, and a section or block placement anchor.

  • kind"create_sfx"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • contentobjectrequired
    6 child attributes

    • duration_msintegerrequired100–3900000

      Generated sound effects (no source) allow up to 300000 ms; a pinned project sound allows up to 3900000 ms.

    • 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}$
  • 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

  kind: "update_sfx"

  • kind"update_sfx"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • contentobjectrequired
    6 child attributes

    • duration_msintegerrequired100–3900000

      Generated sound effects (no source) allow up to 300000 ms; a pinned project sound allows up to 3900000 ms.

    • 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}$
  • 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

  kind: "split_blocks"

  • kind"split_blocks"required
  • targetsarray of objectrequired1–2 items
    4 item attributes

    • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    • split_offsets_utf16array of integerrequired1–2 items
    • new_block_idsarray of stringrequired1–2 items
    • annotation_fragment_idsmap of array of stringrequired

  kind: "merge_blocks"

  Left and right block IDs must differ.

  • kind"merge_blocks"required
  • left_block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • right_block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • expected_left_text_length_utf16integerrequired≥ 0

  kind: "upsert_annotation"

  • kind"upsert_annotation"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • annotationobjectrequired

    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}$
    • payloadboolean | string | integer | number | array of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null | map of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null | nullrequired
    • start_utf16integerrequired≥ 0
    • versionintegerrequired> 0

  kind: "remove_annotation"

  • kind"remove_annotation"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • annotation_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

  kind: "upsert_point"

  • kind"upsert_point"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • pointobjectrequired

    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
    • payloadboolean | string | integer | number | array of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null | map of boolean | string | integer | number | array of StudioAstJsonValue | map of StudioAstJsonValue | null | nullrequired
    • versionintegerrequired> 0

  kind: "remove_point"

  • kind"remove_point"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • point_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

  kind: "upsert_delivery_control_set"

  • kind"upsert_delivery_control_set"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • setobjectrequired

    Provider-specific delivery controls for one provider/model. The format fixes the provider, model, and which setting and directive kinds are allowed (StudioDeliveryControlSetSchema in libs/studio/ast/v2/delivery-controls.ts). source_fingerprint and source_utf16_length are non-null exactly when directives or provider_text_override are present.

    11 child attributes

    • capability_revisionstringrequired1–200 chars
    • directivesarray of objectrequiredmax 256 items

      One of 8 shapes:

      kind: "inworld.turn_instruction"

      • idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      • instructionstringrequired1–4000 chars
      • kind"inworld.turn_instruction"required
      • scopeobject

        One of 2 shapes:

        kind: "block"

        • kind"block"required

        kind: "point"

        • kind"point"required
        • offset_utf16integerrequired≥ 0
        • ordinalintegerrequired0–255

      kind: "inworld.nonverbal"

      • 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"inworld.nonverbal"required
      • offset_utf16integerrequired≥ 0
      • ordinalintegerrequired0–255
      • valuestringrequired

        One oflaughbreatheclear_throatsighcoughyawn

      kind: "fish.inline_instruction"

      • idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      • instructionstringrequired1–4000 chars
      • kind"fish.inline_instruction"required
      • offset_utf16integerrequired≥ 0
      • ordinalintegerrequired0–255

      kind: "elevenlabs.audio_tag"

      • 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"elevenlabs.audio_tag"required
      • instructionstringrequired1–200 chars

        Trimmed audio-tag text without square brackets or control characters.

      • scopeobjectrequired

        One of 2 shapes:

        kind: "block"

        • kind"block"required

        kind: "point"

        • kind"point"required
        • offset_utf16integerrequired≥ 0
        • ordinalintegerrequired0–255

      kind: "cartesia.emotion"

      • 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"cartesia.emotion"required
      • scopeobjectrequired

        One of 2 shapes:

        kind: "block"

        • kind"block"required

        kind: "point"

        • kind"point"required
        • offset_utf16integerrequired≥ 0
        • ordinalintegerrequired0–255
      • valuestringrequired

        One ofneutralhappyexcitedenthusiasticelatedeuphorictriumphantamazedsurprisedflirtatiouscuriouscontentpeacefulserenecalmgratefulaffectionatetrustsympatheticanticipationmysteriousangrymadoutragedfrustratedagitatedthreateneddisgustedcontemptenvioussarcasticironicsaddejectedmelancholicdisappointedhurtguiltyboredtiredrejectednostalgicwistfulapologetichesitantinsecureconfusedresignedanxiouspanickedalarmedscaredproudconfidentdistantskepticalcontemplativedetermined

      kind: "cartesia.laughter"

      • 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"cartesia.laughter"required
      • offset_utf16integerrequired≥ 0
      • ordinalintegerrequired0–255

      kind: "openai.instructions"

      • idstringrequiredpattern ^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      • instructionstringrequired1–4000 chars
      • kind"openai.instructions"required

      kind: "chatterbox.nonverbal"

      • 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"chatterbox.nonverbal"required
      • offset_utf16integerrequired≥ 0
      • ordinalintegerrequired0–255
      • valuestringrequired

        One oflaughchucklesighcoughsnifflegroanyawngasp

    • formatstringrequired

      One ofeleven-v4-1inworld-tts2-1inworld-tts2-experimental-1inworld-tts15-max-1inworld-tts15-mini-1fish-s2-inline-1fish-s2.1-inline-1fish-drama-3-inline-1cartesia-sonic36-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 objectrequiredmax 32 items

      One of 11 shapes:

      kind: "inworld.speaking_rate"

      • kind"inworld.speaking_rate"required
      • valuenumberrequired0.5–1.5

      kind: "inworld.delivery_mode"

      • kind"inworld.delivery_mode"required
      • valuestringrequired

        One ofstablebalancedcreative

      kind: "fish.speed"

      • kind"fish.speed"required
      • valuenumberrequired0.5–2

      kind: "fish.volume"

      • kind"fish.volume"required
      • valuenumberrequired-20–20

      kind: "openai.speed"

      • kind"openai.speed"required
      • valuenumberrequired0.25–4

      kind: "smallest.speed"

      • kind"smallest.speed"required
      • valuenumberrequired0.5–2

      kind: "chatterbox.exaggeration"

      • kind"chatterbox.exaggeration"required
      • valuenumberrequired0–1

      kind: "chatterbox.cfg"

      • kind"chatterbox.cfg"required
      • valuenumberrequired0–1

      kind: "zyphra.mode"

      • kind"zyphra.mode"required
      • valuestringrequired

        One ofstableexpressive

      kind: "zyphra.speaking_rate_bucket"

      • kind"zyphra.speaking_rate_bucket"required
      • valueintegerrequired0–7

      kind: "f5tts.speed"

      • kind"f5tts.speed"required
      • valuenumberrequired0.3–2
    • source_fingerprintstring | nullrequiredpattern ^[0-9a-f]{64}$
    • source_utf16_lengthinteger | nullrequired≥ 0

  kind: "remove_delivery_control_set"

  • kind"remove_delivery_control_set"required
  • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • providerstringrequiredpattern ^[a-z][a-z0-9_-]{0,63}$
  • modelstringrequired1–200 chars

  kind: "set_block_attribution"

  Target block IDs must be unique.

  • kind"set_block_attribution"required
  • targetsarray of objectrequired1–1000 items
    3 item attributes

    • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    • block_kindstringrequired

      One ofspeechnarrationunparsedexcluded

    • speaker_idstring | nullrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

  kind: "create_speaker"

  The speaker name must be trimmed. speaker_version is 1 for a new speaker, or restore_from_speaker_version+1. A non-null casting_default_key must equal the normalized speaker name and requires voice_id.

  • kind"create_speaker"required
  • speakerobjectrequired

    A speaker written by a document command. New full profiles use the strict provider/model request contract; saved-document reads retain their historical profile shape.

    5 child attributes

    • generation_profileobject | nullrequired

      Saved profile read shape, including historical options. For new full-profile requests use StudioGenerationProfileRequest; its provider/model branches list accepted option keys. Generation eligibility and actual audio readiness are separate reads.

      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}$
  • restore_from_speaker_versioninteger | nullrequired≥ 1
  • casting_default_keystring | nullrequired1–200 chars

  kind: "update_speaker"

  The name must be trimmed.

  • kind"update_speaker"required
  • speaker_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • namestringrequired1–200 chars

  kind: "delete_speaker"

  • kind"delete_speaker"required
  • speaker_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

  kind: "set_speaker_casting"

  A non-null casting_default_key requires a voice_id. The effective profile is validated in speaker context.

  • kind"set_speaker_casting"required
  • speaker_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • voice_idstring | nullrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
  • generation_profileobject | nullrequired

    Request-only provider/model-specific options for new full profiles. Catalog-only compatibility models can be saved but are unavailable for generation; check generation-availability. Historical document profiles remain permissive. Partial overrides are validated after inheriting their effective provider, model, and options. Stable Audio is for generated SFX, not speaker casting.

  • casting_default_keystring | nullrequired1–200 chars

  kind: "set_generation_profile_override"

  Target block IDs must be unique; effective options are validated against the inherited provider/model.

  • kind"set_generation_profile_override"required
  • targetsarray of objectrequired1–1000 items
    2 item attributes

    • block_idstringrequiredpattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    • generation_profile_overrideobject | nullrequired

      Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

      5 child attributes

      • controlsstring

        One ofstrictbest_effort

      • fallbackstring

        One ofstrictbest_effort

      • modelstring1–200 chars
      • optionsmap of object | null
      • providerstringpattern ^[a-z][a-z0-9_-]{0,63}$

  kind: "apply_source_document"

  Replaces the source document under the save request's version fences.

  • kind"apply_source_document"required
  • documentobjectrequired

    A replacement source document written by a command. Speaker profiles use the strict new-write request contract.

    10 child attributes

    • blocksarray of objectrequiredmax 100000 items

      One of 6 shapes:

      kind: "speech"

      • block_versionintegerrequired> 0
      • contentobjectrequired
        6 child attributes

        • annotationsarray of StudioAstTextAnnotationrequired
        • delivery_control_setsarray of StudioAstDeliveryControlSetrequiredmax 32 items
        • pointsarray of StudioAstPointNoderequired
        • 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

        Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

        5 child attributes

        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of StudioAstJsonValue
        • 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 StudioAstTextAnnotationrequired
        • delivery_control_setsarray of StudioAstDeliveryControlSetrequiredmax 32 items
        • pointsarray of StudioAstPointNoderequired
        • 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

        Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

        5 child attributes

        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of StudioAstJsonValue
        • 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 StudioAstTextAnnotationrequired
        • delivery_control_setsarray of StudioAstDeliveryControlSetrequiredmax 32 items
        • pointsarray of StudioAstPointNoderequired
        • 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

        Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

        5 child attributes

        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of StudioAstJsonValue
        • 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 StudioAstTextAnnotationrequired
        • delivery_control_setsarray of StudioAstDeliveryControlSetrequiredmax 32 items
        • pointsarray of StudioAstPointNoderequired
        • 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

        Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

        5 child attributes

        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of StudioAstJsonValue
        • 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

        Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

        5 child attributes

        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of StudioAstJsonValue
        • 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–3900000

          Generated sound effects (no source) allow up to 300000 ms; a pinned project sound allows up to 3900000 ms.

        • 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

          • kindobjectrequired
          • sound_effect_idobjectrequired
          • sound_effect_revision_idobjectrequired
      • generation_profile_overrideobject | nullrequired

        Partial saved profile. New document mutations validate the effective inherited provider/model and options against StudioGenerationProfileRequest. The read schema stays permissive for historical profiles. Join options with speaker context; an override is not a standalone full profile.

        5 child attributes

        • controlsstring

          One ofstrictbest_effort

        • fallbackstring

          One ofstrictbest_effort

        • modelstring1–200 chars
        • optionsmap of StudioAstJsonValue
        • 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_idobjectrequired
          • fractionobjectrequired
          • kindobjectrequired
          • positionobjectrequired

          kind: "section"

          • kindobjectrequired
          • positionobjectrequired

          kind: "unplaced"

          • kindobjectrequired
        • 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

        Saved profile read shape, including historical options. For new full-profile requests use StudioGenerationProfileRequest; its provider/model branches list accepted option keys. Generation eligibility and actual audio readiness are separate reads.

        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

Errors 400, 401, 403, 404, 409, 500 use the standard error envelope.