{"openapi":"3.1.0","info":{"title":"LyricWinter API","version":"1.0.0-beta","summary":"Turn stories into fully cast, multi-voice audio with LyricWinter Studio.","description":"The LyricWinter API is in beta. It exposes LyricWinter Studio: projects, sections, versioned story documents, speakers, asynchronous audio workflows, playback, exports, sharing, and the sound library.\n\nGuides: https://lyricwinter.com/docs. Markdown index for agents: https://lyricwinter.com/llms.txt. Remote MCP server: https://lyricwinter.com/mcp.\n\nEvery JSON response uses the envelope `{ \"data\": ..., \"request_id\": \"req_...\" }`; errors use `{ \"error\": { \"code\", \"message\", \"retryable\", \"details\" }, \"request_id\" }`.","termsOfService":"https://lyricwinter.com/tos","license":{"name":"Proprietary. Use is governed by the LyricWinter Terms of Service.","url":"https://lyricwinter.com/tos"},"contact":{"name":"LyricWinter support","url":"https://lyricwinter.com/docs","email":"support@lyricwinter.com"}},"servers":[{"url":"https://lyricwinter.com/api/v1","description":"Production"}],"security":[{"lyricwinterApiKey":[]}],"tags":[{"name":"Voice preparation","description":"Check whether an ElevenLabs voice is already prepared and whether new preparation is currently available. ElevenLabs v4 requires a paid plan. This read-only check does not create voices or reserve provider allowance.","externalDocs":{"url":"https://lyricwinter.com/docs/api/voice-preparation"}},{"name":"Account and API keys","description":"Check API health, read the account and available generation balance behind an API key, and create, list, or revoke scoped API keys.","externalDocs":{"url":"https://lyricwinter.com/docs/api/account"}},{"name":"Projects","description":"A Studio project groups ordered sections (chapters) that share one cast of speakers. Standalone stories appear as unassigned stories until you turn them into a named project.","externalDocs":{"url":"https://lyricwinter.com/docs/api/projects"}},{"name":"Sections","description":"A section is one chapter or scene of story text inside a project. Create a standalone story with one section, add sections to a project, reorder them, or delete them.","externalDocs":{"url":"https://lyricwinter.com/docs/api/sections"}},{"name":"Documents and speakers","description":"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.","externalDocs":{"url":"https://lyricwinter.com/docs/api/documents"}},{"name":"Workflows","description":"Workflows are durable, asynchronous jobs. A prepare workflow structures text into narration and dialogue; a Create Audio workflow casts voices and generates multi-voice audio. Poll a workflow until it reaches a terminal status. A provider-account limit is reported as a failed step with `STUDIO_WORKFLOW_PROVIDER_QUOTA_EXCEEDED`; generation-batch targets use `PROVIDER_QUOTA_EXCEEDED`. Completed audio remains available. For a shared provider limit, contact us to restore provider access before explicitly resuming. When the failure message says the account's monthly ElevenLabs voice preparation allowance is used up, choose a cached ElevenLabs voice or another engine, or wait for the allowance to reset on the first of the month (UTC). Do not automatically resubmit quota failures.","externalDocs":{"url":"https://lyricwinter.com/docs/api/workflows"}},{"name":"Media and playback","description":"Check whether generation can start separately from whether audio already exists. Read per-block media freshness and generation activity, compile a playback manifest for current audio, and mint short-lived URLs. Generation availability checks plan access, voice/compiler eligibility, and confirmed ElevenLabs preparation exhaustion; it is not a promise of audio, synthesis quota, or funding. Free accounts cannot generate with ElevenLabs v4, but existing audio remains playable.","externalDocs":{"url":"https://lyricwinter.com/docs/api/media"}},{"name":"Exports","description":"Render one section or a project's selected sections into downloadable MP3, WAV, M4B, synchronized EPUB, or SRT files. Poll a project job for every child export, then download files individually and fetch each child's immutable manifest for matching timings. No ZIP is produced. Freshness compares document, cast, and mastering versions only, not newer audio takes or artifact readiness.","externalDocs":{"url":"https://lyricwinter.com/docs/api/exports"}},{"name":"Sharing","description":"Publish a section or a whole project at a stable public link, read its sharing state, or revoke the link.","externalDocs":{"url":"https://lyricwinter.com/docs/api/sharing"}},{"name":"Sound library","description":"Upload sound effects and ambience up to 256 MiB and 65 minutes into the Studio sound library, manage their metadata, publish them to the public catalog, and link them to projects so Create Audio can place them automatically. Processing verifies duration; the sanitized WAV can be up to 720 MiB. Pinned project sounds can play as long ambience overlays; provider-generated SFX remain limited to five minutes.","externalDocs":{"url":"https://lyricwinter.com/docs/api/sounds"}},{"name":"Feedback","description":"Send product feedback with screenshots and other images so our team can see what you mean.","externalDocs":{"url":"https://lyricwinter.com/docs/api/feedback"}}],"externalDocs":{"description":"LyricWinter API and MCP documentation","url":"https://lyricwinter.com/docs"},"paths":{"/voices/preparation-status":{"get":{"operationId":"getVoicePreparationStatus","summary":"Check voice preparation readiness","description":"Check current ElevenLabs preparation availability and whether each accessible voice already has a prepared current-revision voice. ElevenLabs v4 requires an active paid plan, including when the voice is already prepared. Signed-in requests also check the requesting account's monthly custom voice clone allowance: MyWinter 20, UltraWinter 60; free accounts have no allowance. Each new or renewed clone counts; reuse of a current clone and other engines do not. Allowances reset on the first of each month at 00:00 UTC, including annual subscriptions. Anonymous requests check provider availability only. Pass up to 50 comma-separated UUIDs in voice_ids, or omit them for a new voice. The response status is available, exhausted, or unknown; the notice distinguishes an account limit from shared provider exhaustion. Paid accounts can still use prepared voices when cloning is unavailable. This check is read-only, does not reserve allowance, and may become stale. Free accounts must choose another engine; existing audio remains playable.","tags":["Voice preparation"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"voice_ids","in":"query","required":false,"description":"Up to 50 comma-separated UUIDs. Omit to check new voice preparation without selecting existing voices.","schema":{"type":"string"}}],"responses":{"200":{"description":"Current provider preparation state and cache readiness for accessible voices only.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["provider","status","voices","notice"],"properties":{"provider":{"const":"elevenlabs"},"status":{"type":"string","enum":["available","exhausted","unknown"]},"notice":{"type":["string","null"]},"voices":{"type":"array","items":{"type":"object","required":["voice_id","preparation_required"],"properties":{"voice_id":{"type":"string","format":"uuid"},"preparation_required":{"type":"boolean"}}}}}},"request_id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-api-key-scope":"voices:read"}},"/health":{"get":{"operationId":"getHealth","summary":"Check API health","description":"Returns a static payload when the LyricWinter API is reachable. It needs no authentication and performs no account checks.","tags":["Account and API keys"],"security":[],"responses":{"200":{"$ref":"#/components/responses/Health"}}}},"/me":{"get":{"operationId":"getCurrentAccountProfile","summary":"Get the current account","description":"Returns the profile of the account that owns the API key: its ID, username, display name, avatar URL, and email.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"responses":{"200":{"$ref":"#/components/responses/AccountProfile"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["account:read"],"x-lyricwinter-api-key-scope":"account:read"}},"/me/generation-preferences":{"get":{"operationId":"getGenerationPreferences","summary":"Read generation preferences","description":"Read the account's saved Allow fallbacks setting. New accounts start with it enabled. The preference is shared across devices.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"responses":{"200":{"description":"Saved generation preference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationPreferencesEnvelope"}}}},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["account:read"],"x-lyricwinter-api-key-scope":"account:read"},"patch":{"operationId":"updateGenerationPreferences","summary":"Save generation preferences","description":"Save Allow fallbacks by sending allow_fallbacks as true or false. The response contains the saved value. Changing this preference does not alter work already submitted.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationPreferences"}}}},"responses":{"200":{"description":"Saved generation preference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationPreferencesEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["account:write"],"x-lyricwinter-api-key-scope":"account:write"}},"/me/balance":{"get":{"operationId":"getCurrentAccountBalance","summary":"Get the current account balance","description":"Returns the caller's current account generation balance with `account:read`. `data.balance.snowcoins` is settled; `data.balance.available_snowcoins` is available after outstanding holds. For promotional credits and the combined Studio balance, use `/studio/account-capabilities` with `studio:read`. These values are current snapshots, not historical balances for billing activity. The server still reserves and charges credits atomically. Subscription state and usage history are separate resources.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"responses":{"200":{"$ref":"#/components/responses/AccountBalance"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["account:read"],"x-lyricwinter-api-key-scope":"account:read"}},"/studio/account-capabilities":{"get":{"operationId":"getStudioAccountCapabilities","summary":"Get available Studio funding and actions","description":"Returns the caller's account balance, promotional Studio credits, plan, and action capabilities with `studio:read`. `data.studio_funding.total_available_snowcoins` and `total_available_words` include both account and promotional funding after holds. `as_of` identifies the snapshot. Actions are advisory, not a live provider-health check or a guarantee that a later paid request will succeed. Reading this endpoint can claim an eligible account reward before returning the snapshot; repeated reads do not grant the same reward twice.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"responses":{"200":{"description":"Current Studio account capabilities from one consistent billing snapshot.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioAccountCapabilitiesEnvelope"}}}},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/api-keys":{"get":{"operationId":"listApiKeys","summary":"List API keys","description":"Lists metadata for the account's API keys, including name, scopes, expiry, last use, and revocation time. Raw keys are never returned.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"responses":{"200":{"$ref":"#/components/responses/ApiKeyList"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["api_keys:read"],"x-lyricwinter-api-key-scope":"api_keys:read"},"post":{"operationId":"createApiKey","summary":"Create an API key","description":"Creates a scoped API key. The response contains `raw_key` exactly once; LyricWinter stores only a hash. When you call this endpoint with an API key, the new key can only have scopes that the calling key already holds.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateRequest"}}}},"responses":{"201":{"$ref":"#/components/responses/ApiKeyCreated"},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["api_keys:write"],"x-lyricwinter-api-key-scope":"api_keys:write"}},"/api-keys/{apiKeyId}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","description":"Revokes one of the account's API keys immediately. Revoking a key that is already revoked succeeds without changes.","tags":["Account and API keys"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"apiKeyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"$ref":"#/components/responses/ApiKeyRevoked"},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["api_keys:write"],"x-lyricwinter-api-key-scope":"api_keys:write"}},"/studio/projects":{"get":{"operationId":"listStudioProjects","summary":"List projects and standalone stories","description":"Returns named projects in `projects` and standalone stories in `unassigned_sections`. Every standalone story still has a `project_id` that works with project-scoped endpoints.","tags":["Projects"],"security":[{"lyricwinterApiKey":[]}],"responses":{"200":{"description":"Named projects and unassigned Studio story summaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectsEnvelope"}}}},"401":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}":{"patch":{"operationId":"promoteStudioProject","summary":"Turn a standalone story into a project","description":"Gives a standalone story a project name so you can add more sections to it. Its section, cast, audio, and share links are kept.","tags":["Projects"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioPromoteProjectRequest"}}}},"responses":{"200":{"description":"The promoted named project, or the existing project when it is already named with the same name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"},"delete":{"operationId":"deleteStudioProject","summary":"Delete a project","description":"Deletes a project with all of its sections, in-progress work, playback, and share links. This cannot be undone through the API.","tags":["Projects"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectDeleteRequest"}}}},"responses":{"200":{"description":"Project deletion counts and optional AI-designed voice cleanup result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectDeleteEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/projects/{projectId}/deletion-info":{"get":{"operationId":"getStudioProjectDeletionInfo","summary":"Preview project deletion","description":"Returns counts of the sections, script blocks, generated audio, and active share links that deleting the project would remove. Call it before deleting.","tags":["Projects"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Project deletion preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectDeletionInfoEnvelope"}}}},"401":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/sections":{"post":{"operationId":"createStandaloneStudioSection","summary":"Create a standalone story","description":"Creates a standalone Studio story with one section containing the exact text you send. Returns `201` with the new project ID, section, and document, or `200` with `idempotent_replay: true` when the same `client_mutation_id` was already applied.","tags":["Sections"],"security":[{"lyricwinterApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateStandaloneSectionRequest"}}}},"responses":{"200":{"description":"Idempotent replay of the existing standalone story.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateSectionEnvelope"}}}},"201":{"description":"Standalone Studio story created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateSectionEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"}},"/studio/projects/{projectId}/sections":{"get":{"operationId":"listStudioProjectSections","summary":"List project sections","description":"Returns a project's sections in order with the project's `section_order_version` and `speaker_registry_version`. A project that has not been opened in Studio yet returns `initialized: false`.","tags":["Sections"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Studio project state and sections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSectionsEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"post":{"operationId":"createStudioSection","summary":"Add a section to a project","description":"Adds one section of unstructured text to a project. Standalone projects allow only one active section; adding another returns `400 STUDIO_COMMAND_REJECTED`. Use a named project created through `POST /projects` for multiple sections. Send the `section_order_version` you last read as `base_section_order_version`; a stale version returns `409`.","tags":["Sections"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateSectionRequest"}}}},"responses":{"200":{"description":"Idempotent replay of the existing section.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateSectionEnvelope"}}}},"201":{"description":"Studio section created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioCreateSectionEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"}},"/studio/projects/{projectId}/sections/{sectionId}":{"patch":{"operationId":"moveStudioSection","summary":"Move a section","description":"Moves a section to a new position in the project. Send the current `section_order_version`; a stale version returns `409`.","tags":["Sections"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioMoveSectionRequest"}}}},"responses":{"200":{"description":"Section move committed or replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionLifecycleEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"},"delete":{"operationId":"deleteStudioSection","summary":"Delete a section","description":"Deletes a section after checking both the section order version and the document version. This cannot be undone through the API.","tags":["Sections"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioDeleteSectionRequest"}}}},"responses":{"200":{"description":"Section deletion committed or replayed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionLifecycleEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"}},"/studio/projects/{projectId}/sections/{sectionId}/deletion-info":{"get":{"operationId":"getStudioSectionDeletionInfo","summary":"Preview section deletion","description":"Returns counts of the script blocks, generated clips, and active share links that deleting the section would make inaccessible.","tags":["Sections"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Section deletion preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionDeletionInfoEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/sections/{sectionId}/document":{"get":{"operationId":"getStudioDocument","summary":"Get a section document","description":"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.","tags":["Documents and speakers"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Canonical Studio document and optional recovery draft.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioDocumentEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"patch":{"operationId":"saveStudioDocument","summary":"Edit a section document","description":"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. For an existing pinned project-sound block, `content.duration_ms` must equal its immutable source revision's duration; changing it returns `400 STUDIO_PROJECT_SOUND_DURATION_MISMATCH` with expected_duration_ms and requested_duration_ms. Placement gain/fades do not trim the source or shorten the timeline. To change only the gaps between passages, send `set_section_pacing` with integer `same_speaker_gap_ms` and `different_speaker_gap_ms` from 0 through 1000; use empty target-version maps for this section-only command. This preserves the script and existing takes.","tags":["Documents and speakers"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioDocumentSaveRequest"}}}},"responses":{"200":{"description":"Authoritative document after commit or idempotent replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioDocumentEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"}},"/studio/sections/{sectionId}/script":{"post":{"operationId":"importStudioScript","summary":"Import a speaker-labeled script","description":"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.","tags":["Documents and speakers"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioScriptImportRequest"}}}},"responses":{"200":{"description":"Canonical Studio document after the import.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioDocumentEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"}},"/studio/projects/{projectId}/speakers":{"get":{"operationId":"getStudioProjectSpeakerUsage","summary":"List project speakers","description":"Returns the project's speakers with how many lines and sections each one appears in, plus the current `speaker_registry_version`.","tags":["Documents and speakers"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Project-wide character usage and current character registry authority.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSpeakerUsageEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}/speakers/{speakerId}/casting":{"patch":{"operationId":"updateStudioProjectSpeakerCasting","summary":"Assign a speaker's voice and model","description":"Updates one speaker across its project with a voice and full generation profile, or clears both together. Send current speaker and speaker-registry versions plus session/mutation IDs and a current section ID; the result contains the casting mutation and the current section document. Selecting ElevenLabs v4 requires an active paid plan; otherwise the request returns 403 VOICE_MODEL_SUBSCRIPTION_REQUIRED. Provider options are typed by provider/model. ElevenLabs v4 accepts optional stability (0-1) and integer seed (1-4294967295); empty options retain defaults. Seed is best-effort, not guaranteed deterministic. Speed and similarity_boost are not exposed by the connected transport. Unsupported keys fail before saving or generation. Author delivery directions through control sets. Partial block overrides inherit speaker settings and are checked against the resulting effective profile.","tags":["Documents and speakers"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"speakerId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSpeakerCastingRequest"}}}},"responses":{"200":{"description":"Project casting changed and the current section returned at the committed speaker authority.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSpeakerCastingEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"}},"/studio/projects/{projectId}/workflows":{"post":{"operationId":"createStudioWorkflow","summary":"Start a workflow","description":"Starts a `prepare_sections` workflow, which structures text into narration and dialogue, or a `create_audio` workflow, which prepares text, casts voices, directs performances, adds sound effects, and generates audio. Returns `202` with `data: { run, steps }`; poll the returned run ID until it reaches a terminal status. Replaying the same `client_mutation_id` returns the same workflow instead of starting another.","tags":["Workflows"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/StudioWorkflowPrepareSectionsRequest"},{"$ref":"#/components/schemas/StudioWorkflowCreateAudioV2Request"}]}}}},"responses":{"202":{"description":"Durable project workflow accepted and first advancement attempted. Replaying the same client_mutation_id with the same request returns the same workflow.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"body-client-mutation-id-bound-to-canonical-request-hash"},"get":{"operationId":"getLatestStudioWorkflow","summary":"Get the latest project workflow","description":"Returns the project's most recent workflow with its steps, or `null` if none has run. Pass `section_id` to get the most recent workflow that includes that section.","tags":["Workflows"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"section_id","in":"query","required":false,"description":"Restrict to the workflow that most recently added a step for this section. Returns null when none exists or that workflow belongs to another project.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Latest project workflow or null when none exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowLatestEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/workflows/{workflowRunId}":{"get":{"operationId":"getStudioWorkflow","summary":"Get a workflow","description":"Returns `data: { run, steps }` with a workflow run and its ordered steps, the same payload shape as workflow creation and resume. Poll this endpoint until `data.run.status` is `completed`, `partially_completed`, `failed`, or `cancelled`. For each section's current per-block audio freshness, activity, errors, and playback URLs, read `GET /studio/sections/{sectionId}/media` and join by `block_id`; generation eligibility is a separate check.","tags":["Workflows"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"workflowRunId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current workflow and ordered section steps. Poll until run.status is terminal (completed, partially_completed, failed, cancelled).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/workflows/{workflowRunId}/progress":{"get":{"operationId":"getStudioWorkflowProgress","summary":"Get workflow audio progress","description":"Returns ready/total audio clip counts. The default `schema_version=1` response is unchanged. Request `?schema_version=2` for failed-block issues with `section_id`, stable `block_id`, legacy one-based `block_number`, and zero-based `block_index` in the full document order captured when the issue was recorded. Use IDs to locate blocks after edits, not old indexes or text-chunk counters. Inspect each block's current freshness, activity, errors, and playback URL through `GET /studio/sections/{sectionId}/media`; `generation-availability` does not report current audio.","tags":["Workflows"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"workflowRunId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"schema_version","in":"query","required":false,"description":"1 (default) returns counts only. 2 adds failed-block issues using stable IDs and captured-document zero-based indexes.","schema":{"type":"integer","enum":[1,2],"default":1}}],"responses":{"200":{"description":"Current workflow audio counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowProgressEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/workflows/{workflowRunId}/cancel":{"post":{"operationId":"cancelStudioWorkflow","summary":"Cancel a workflow","description":"Requests cancellation of a prepare or Create Audio workflow. Pending steps are cancelled immediately; running steps stop cooperatively and their late results are discarded. A finished workflow is returned unchanged. Send no request body.","tags":["Workflows"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"workflowRunId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current workflow state, normally canceling or cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/workflows/{workflowRunId}/resume":{"post":{"operationId":"resumeStudioWorkflow","summary":"Resume a failed workflow","description":"Starts a new workflow linked to a failed or partially completed run and returns `202` with `data: { run, steps }`, the same shape as creation and polling. It picks up from each section's first failed stage instead of redoing finished work. Only runs with `resumable: true` can be resumed. If recovery returns a retryable error, retry the same body and `client_mutation_id` to preserve the original recovery request.","tags":["Workflows"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"workflowRunId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowResumeRequest"}}}},"responses":{"202":{"description":"The linked successor workflow and its recovery steps.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioWorkflowEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/sections/{sectionId}/media":{"get":{"operationId":"getStudioSectionMedia","summary":"Get section media","description":"Returns one entry per document block with audio freshness, independent generation activity, the latest generation/import error, and a short-lived signed playback_url for active audio. A failed retake can coexist with current playable audio. Available generation does not imply audio exists. Join by block_id. Request ?schema_version=2 for boundary_silence_handling from the active take's stored intent: timeline, fixed_in_asset, unsupported, or unavailable. The default response remains unchanged. Timeline handling applies only to boundary pauses; internal timed silences remain part of generated audio.","tags":["Media and playback"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"schema_version","in":"query","required":false,"description":"1 or omitted preserves the existing unversioned payload. 2 returns active-take boundary_silence_handling. Other values return 400.","schema":{"type":"integer","enum":[1,2],"default":1}}],"responses":{"200":{"description":"Current block media read model; schema_version=2 additionally describes active-take boundary silence handling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionMediaReadEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/sections/{sectionId}/generation-availability":{"get":{"operationId":"getStudioSectionGenerationAvailability","summary":"Check generation eligibility","description":"Returns each block's effective requested profile, plan access, voice/provider materialization requirements, and compiler diagnostics. ElevenLabs v4 is unavailable on free plans even for a prepared voice. On paid plans, confirmed ElevenLabs preparation exhaustion makes an unprepared ElevenLabs option unavailable; already prepared current-revision voices remain eligible. `generation.status: available` does not mean audio exists or guarantee live synthesis quota or funding. Use `/media` for freshness, activity, errors, and playable audio. Pinned project_sound blocks use library materialization rather than synthesis and have generation: null, as do blocks without provider generation. Null does not claim a sound is present or playable.","tags":["Media and playback"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current block generation eligibility, not existing-audio readiness or live provider-account health.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionGenerationAvailabilityEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/sections/{sectionId}/playback-manifest":{"get":{"operationId":"getStudioPlaybackManifest","summary":"Get a playback manifest","description":"Compiles the section's current speech, pauses, and sound-effect overlays into one timeline with signed asset URLs. Pass document_version and speaker_registry_version from the document. In sequential_units, unit_type: asset has the audio asset's own duration, unit_type: silence is an authored pause assembled separately on the timeline, and unit_type: spacing is an inter-block gap; sound effects are overlay_units. A speech or narration export block sums its contiguous asset and silence unit durations, excluding spacing, so do not equate its duration_ms with one asset unit's duration. Join blocks by stable block_id and per-unit records by unit_id, not by start_ms. Optional schema_version=2 adds unit_word_timings sidecars keyed by unit_id, block_id, and asset_id with provider-aligned section-relative words or word_timing: unavailable. Alignment is bound to the actual asset content hash; old/unsupported/invalid alignment is not estimated or transcribed. The default response and hashed audio manifest remain unchanged. Unknown query keys return 400.","tags":["Media and playback"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"document_version","in":"query","required":true,"description":"Saved section document version to compile. If it no longer matches the saved section, the request fails with 409 STUDIO_PLAYBACK_STALE.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"schema_version","in":"query","required":false,"description":"Opt in to provider word timing sidecars. The default retains the V1 response.","schema":{"type":"integer","enum":[1,2],"default":1}},{"name":"speaker_registry_version","in":"query","required":true,"description":"Saved speaker-registry (cast) version to compile. If it no longer matches, the request fails with 409 STUDIO_PLAYBACK_STALE.","schema":{"type":"integer","minimum":1,"maximum":9007199254740991}}],"responses":{"200":{"description":"Current private playback manifest and signed asset URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioPlaybackManifestReadEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"502":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/media-assets/{assetId}/access-url":{"post":{"operationId":"createStudioMediaAccessUrl","summary":"Create a media access URL","description":"Returns a signed URL for one audio asset: six hours for inline playback or twelve hours for download. The URL supports HTTP range requests, so audio players can seek.","tags":["Media and playback"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"assetId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioMediaAccessUrlRequest"},"example":{"schema_version":1,"disposition":"attachment","filename":"Chapter-1.mp3"}}}},"responses":{"200":{"description":"Short-lived signed media URL and asset metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioMediaAccessUrlEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}/mastering-profile":{"get":{"operationId":"getStudioMasteringProfile","summary":"Get the mastering profile","description":"Returns the project's loudness and mastering settings and its `mastering_version`, which exports require.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current mastering authority and profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioMasteringProfileEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}/exports":{"post":{"operationId":"createStudioProjectExport","summary":"Export a project's sections","description":"Creates a parent job with one section export per selected active section, in project order. Send `schema_version: 1`, `format`, and `pin: \"current\"` with an `Idempotency-Key` header. Optional `sections` selects 1-100 unique section UUIDs; omitting it selects all active sections, up to 100. The selection and saved document, cast, and mastering version plan are captured together and remain fixed. Audio takes are selected when each child compiles, not atomically at enqueue. Returns `202` for a new job or `200` for a database replay; an HTTP replay may retain the original `202`. Dispatch is asynchronous, without a fixed completion deadline. This does not generate speech or automatically retry failed paid generation. Poll the parent and download child files separately; `archive` is always null.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"Idempotency-Key","in":"header","required":true,"description":"Key for one intended project export. Retry the same request with the same key; reuse for a different request returns 409.","schema":{"type":"string","minLength":8,"maxLength":128,"pattern":"^[\\x21-\\x7E]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectExportCreateRequest"},"example":{"schema_version":1,"format":"mp3","pin":"current"}}}},"responses":{"200":{"description":"The existing parent was returned by database idempotency replay; this does not imply completion.","headers":{"Idempotency-Replayed":{"description":"true when the stored HTTP response is replayed; database replay is separately reflected by the 200 status.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectExportEnvelope"}}}},"202":{"description":"New durable project export work accepted, or its original accepted HTTP response replayed. Poll for current state.","headers":{"Idempotency-Replayed":{"description":"true when the original accepted HTTP response was replayed.","schema":{"type":"boolean"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectExportEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"required-header-bound-to-canonical-request-hash"},"get":{"operationId":"listStudioProjectExports","summary":"List project export jobs","description":"Lists parent jobs newest first, including their child exports. Optional `format` filters the list. `cursor` is an integer offset starting at 0; `limit` is 1-10 and defaults to 1. Pass the returned string `next_cursor` as the next offset; null means the end. Listing does not start exports or regenerate audio.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/StudioExportFormat"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":1}}],"responses":{"200":{"description":"A page of project export jobs and child statuses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectExportsEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}/exports/{exportId}":{"get":{"operationId":"getStudioProjectExport","summary":"Poll a project export job","description":"Returns the parent job and ordered `sections`, each with `section_id`, captured `title`, child `export_id`, captured `authority` versions, nullable `export`, and nullable `error`. If a child is moved to another project or deleted, `export` is null and `error.code` is `STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE`; the captured plan remains. Poll while `queued` or `running`. `completed`, `partial_failed`, and `failed` are terminal. Unavailable children count as failures; `percent` counts them and terminal failures as finished work, so 100 does not mean success. Download each available completed child's `export.artifact.download_url`; use its child ID for `/studio/exports/{exportId}/manifest` (including optional `schema_version=2` word timings) or `/cancel`. Transfers and cleanup are not blocked, and original child endpoints are not guaranteed to remain accessible. The parent ID is not a child ID. There is no combined archive or automatic re-export after edits.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"exportId","in":"path","required":true,"description":"The parent project export ID, not a child section export ID.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current project export parent and child states.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectExportEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}/export-freshness":{"get":{"operationId":"getStudioProjectExportFreshness","summary":"Compare section export versions","description":"Returns active sections in project order, their saved document, speaker registry, and mastering versions, and their latest export for `format` (default `mp3`). Deleted sections are omitted; at most 100 active sections are supported. `basis` is `document_cast_mastering_versions`. Without an export, `latest_export` and `matches_current_authority` are null. A true match is only a version comparison: it does not guarantee latest audio takes, successful completion, complete media, or a valid downloadable artifact. Inspect status and artifact separately. This read does not export or generate anything.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"$ref":"#/components/parameters/ProjectId"},{"name":"format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/StudioExportFormat","default":"mp3"}}],"responses":{"200":{"description":"Version comparisons for the project's active sections.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectExportFreshnessEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/exports":{"get":{"operationId":"listStudioExports","summary":"List exports","description":"Lists the account's exports, newest first. Completed exports include a download URL that is valid for twelve hours; the file itself is kept for thirty days.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"section_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/StudioExportFormat"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/StudioExportStatus"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"One export page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportsEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"post":{"operationId":"createStudioExport","summary":"Create an export","description":"Renders one section into `mp3`, `wav`, `m4b`, synchronized `epub`, or `srt`, pinned to the document, speaker registry, and mastering versions you send. Returns `202` for new work or `200` when an identical, unexpired file is reused. Requires an `Idempotency-Key` header.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Opaque caller key. The same key and request replay safely; the same key with a different request conflicts.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportCreateRequest"},"example":{"schema_version":1,"section_id":"11111111-1111-4111-8111-111111111111","document_version":7,"speaker_registry_version":3,"mastering_version":4,"format":"mp3"}}}},"responses":{"200":{"description":"An unexpired identical artifact was reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportEnvelope"}}}},"202":{"description":"New durable export work accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"502":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write","x-lyricwinter-idempotency":"required-header-bound-to-canonical-request-hash"}},"/studio/exports/{exportId}":{"get":{"operationId":"getStudioExport","summary":"Get an export","description":"Returns an export's status, phase, percent complete, and its completed, unexpired downloadable `artifact`. Historical files remain tied to their original export. `authority.is_current` compares document, cast, and mastering versions only, not the latest audio rendition. For timings matching this file, fetch `/studio/exports/{exportId}/manifest`.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"exportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current durable export state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/exports/{exportId}/manifest":{"get":{"operationId":"getStudioExportManifest","summary":"Get an export's immutable timeline","description":"Returns the exact pinned manifest identity (`id`, content `hash`, and `schema_version`), total duration, completeness, and block timings used by this export. The response's `timing_basis` is `media_and_intra_block_silence_excluding_inter_block_spacing`: speech and narration block durations sum their contiguous playback asset and separately assembled silence units, but exclude inter-block spacing units. An asset unit can share a block's `start_ms` yet have a shorter `duration_ms` when a trailing pause follows it; do not normalize either duration. Join block-level records by stable `block_id` and word sidecars by `unit_id`, not by start time or `block_index`. `block_index` is zero-based in the captured document's full block order. Optional `schema_version=2` adds section-relative provider word timing sidecars for the pinned immutable assets, not today's retakes; missing alignment is explicitly unavailable. Default V1 is unchanged. Returns `409` before a manifest is pinned. This read does not compile or generate media.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"exportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"schema_version","in":"query","required":false,"schema":{"type":"integer","enum":[1,2],"default":1}}],"responses":{"200":{"description":"The export's pinned block timeline and content-addressed manifest identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportTimelineReadEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/exports/{exportId}/cancel":{"post":{"operationId":"cancelStudioExport","summary":"Cancel an export","description":"Cancels a queued export immediately or asks a running one to stop. Files already produced for other requests are not deleted.","tags":["Exports"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"exportId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current cancelled or canceling export state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioExportEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/sections/{sectionId}/share":{"get":{"operationId":"getStudioPublicShare","summary":"Get section sharing","description":"Returns whether the section is public and its active public link, if any.","tags":["Sharing"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current section sharing state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionShareEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"post":{"operationId":"ensureStudioPublicShare","summary":"Share a section","description":"Creates a stable public link for the section, or returns the existing one. The public page always plays the latest saved version. Send an empty JSON object, or name the `source` surface you shared from.","tags":["Sharing"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionSharePublishRequest"}}}},"responses":{"201":{"description":"Section published with its active link (also returned when already public).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionShareEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"},"delete":{"operationId":"revokeStudioPublicShare","summary":"Stop sharing a section","description":"Revokes the section's public link and makes the section private.","tags":["Sharing"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"sectionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Section is private and the prior link is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSectionShareEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/projects/{projectId}/share":{"get":{"operationId":"getStudioProjectShareState","summary":"Get project sharing","description":"Returns whether the project has a public link and the active link, if any.","tags":["Sharing"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Current project public-link state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectShareEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"post":{"operationId":"publishStudioProject","summary":"Share a project","description":"Creates a stable public link for the whole project, or returns the existing one. Send an empty JSON object, or name the `source` surface you shared from.","tags":["Sharing"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSharePublishRequest"}}}},"responses":{"201":{"description":"Stable project public link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectShareEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"},"delete":{"operationId":"revokeStudioProjectShare","summary":"Stop sharing a project","description":"Revokes the project's public link. Send no request body.","tags":["Sharing"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Project sharing is revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectShareEnvelope"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/sounds":{"get":{"operationId":"listStudioSounds","summary":"List sounds","description":"Lists sounds in your library, sounds shared with you, or public sounds, filtered by `scope` and an optional search query. Results are cursor-paginated.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"scope","in":"query","schema":{"type":"string","enum":["mine","shared","public"],"default":"mine"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"project_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"in_project","in":"query","schema":{"type":"boolean"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"Cursor-paginated sound library.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundListEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"post":{"operationId":"createStudioSoundUpload","summary":"Start a sound upload","description":"Creates a sound and returns a signed upload session. Files accept up to 256 MiB; decoded audio must be at most 65 minutes. Upload the file to the session URL, then call the complete endpoint. Processing verifies duration and publishes it as `current_revision.duration_ms`; client-supplied duration is not accepted as authority. Set `is_public: true` to list the sound in the public catalog and on [lyricwinter.com/sounds](/sounds) once it is ready.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundUploadRequest"}}}},"responses":{"201":{"description":"Upload session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundUploadEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/sounds/{soundId}/uploads/{uploadId}/complete":{"post":{"operationId":"completeStudioSoundUpload","summary":"Complete a sound upload","description":"Tells LyricWinter the file has been uploaded so it can process the sound. Poll the latest upload status until the sound is ready.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"uploadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundUploadCompleteRequest"}}}},"responses":{"200":{"description":"Idempotent finalization result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundEnvelope"}}}},"202":{"description":"Sanitization accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/sounds/{soundId}/uploads/latest":{"get":{"operationId":"getStudioSoundUploadStatus","summary":"Get sound upload status","description":"Returns the processing status of the most recent upload for a sound you own.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Latest owner upload, independent of the playable revision; null when none exists.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"object","properties":{"schema_version":{"type":"string","enum":["studio-sound-upload-status-1"]},"sound_id":{"type":"string","format":"uuid"},"latest":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"revision_number":{"type":"integer","minimum":1},"is_replacement":{"type":"boolean"},"status":{"type":"string","enum":["pending_upload","processing","ready","failed","expired"]},"completed_revision_id":{"type":["string","null"],"format":"uuid"},"error":{"type":["object","null"],"properties":{"code":{"type":["string","null"]},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"}},"required":["id","revision_number","is_replacement","status","completed_revision_id","error","created_at","updated_at","expires_at"],"additionalProperties":false}},"required":["schema_version","sound_id","latest"],"additionalProperties":false}}}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/sounds/{soundId}":{"get":{"operationId":"getStudioSound","summary":"Get a sound","description":"Returns one sound's metadata and processing state.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"project_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Accessible sound detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"patch":{"operationId":"updateStudioSound","summary":"Update a sound","description":"Updates a sound's name, description, tags, or `is_public` visibility. Publishing a sound that is still processing returns `409`.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundMutationRequest"}}}},"responses":{"200":{"description":"Updated sound.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"},"delete":{"operationId":"deleteStudioSound","summary":"Delete a sound","description":"Deletes a sound you own.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundDeleteRequest"}}}},"responses":{"200":{"description":"Logical sound deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundDeleteEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/sounds/{soundId}/preview-url":{"post":{"operationId":"createStudioSoundPreviewUrl","summary":"Create a sound preview URL","description":"Returns a short-lived URL for listening to a sound.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Access-checked short-lived same-origin preview capability URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioSoundPreviewEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"}},"/studio/projects/{projectId}/sounds":{"get":{"operationId":"listStudioProjectSounds","summary":"List project sounds","description":"Lists the sounds linked to a project. Create Audio can place linked sounds automatically when `place_project_sounds` is on.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":500}}],"responses":{"200":{"description":"Project sound registry page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSoundListEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:read"],"x-lyricwinter-api-key-scope":"studio:read"},"post":{"operationId":"addStudioProjectSound","summary":"Link a sound to a project","description":"Links a ready sound from your library to a project so Create Audio can place it.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSoundMutationRequest"}}}},"responses":{"201":{"description":"Project sound membership updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSoundMutationEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/studio/projects/{projectId}/sounds/{soundId}":{"delete":{"operationId":"removeStudioProjectSound","summary":"Unlink a sound from a project","description":"Removes a sound from a project. The sound stays in your library.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSoundMutationRequest"}}}},"responses":{"200":{"description":"Project sound membership updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StudioProjectSoundMutationEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-required-scopes":["studio:write"],"x-lyricwinter-api-key-scope":"studio:write"}},"/sounds":{"get":{"operationId":"listPublicSounds","summary":"List public sounds","description":"Lists published sounds from the public catalog shown on [lyricwinter.com/sounds](/sounds). No sign-in is required. Filter with `q`, `tag`, or `category`, and page with `cursor`. Each sound includes its page URL and a preview URL valid for 12 hours.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"tag","in":"query","schema":{"type":"string","minLength":1,"maxLength":40}},{"name":"category","in":"query","schema":{"type":"string","pattern":"^[a-z0-9_-]{1,80}$"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":30}},{"name":"cursor","in":"query","schema":{"type":"string","pattern":"^[0-9]{1,6}$"}}],"responses":{"200":{"description":"One page of public sounds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSoundListEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-api-key-scope":"studio:read"}},"/sounds/{soundId}":{"get":{"operationId":"getPublicSound","summary":"Get a public sound","description":"Returns one published sound from the public catalog, with its page URL and a preview URL. Sounds that are private or still processing return `404`.","tags":["Sound library"],"security":[{"lyricwinterApiKey":[]}],"parameters":[{"name":"soundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Public sound.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSoundEnvelope"}}}},"default":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-api-key-scope":"studio:read"}},"/feedback":{"post":{"operationId":"submitFeedback","summary":"Send feedback and images","description":"Send feedback text as JSON, or use multipart/form-data to attach up to five PNG, JPEG, or WebP images by repeating the images field. Each image can be up to 5 MiB, with 15 MiB total and 32 megapixels per image. Screenshots can include circles or other annotations. Images are stored privately with your feedback. Sign in to use your account email, or supply replyEmail so our team can reply.","tags":["Feedback"],"security":[{"lyricwinterApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitRequest"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitMultipartRequest"},"encoding":{"images":{"contentType":"image/png, image/jpeg, image/webp"}}}}},"responses":{"201":{"$ref":"#/components/responses/FeedbackSubmitted"},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"},"500":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"x-lyricwinter-api-key-scope":"feedback:write","x-lyricwinter-rate-limit":"5 submissions per 15 minutes per x-forwarded-for/x-real-ip plus user-agent fingerprint"}}},"components":{"securitySchemes":{"lyricwinterApiKey":{"type":"http","scheme":"bearer","bearerFormat":"lw_*","description":"Scoped LyricWinter API key sent as `Authorization: Bearer lw_...`. Create keys at https://lyricwinter.com/dashboard under Developers. The raw key is shown once."}},"responses":{"ApiError":{"description":"Stable /api/v1 error envelope.","headers":{"Retry-After":{"description":"Optional minimum retry delay in whole seconds or an HTTP-date. Retryable application 429/503 errors supply this hint; nonretryable provider-account outages do not get a fabricated recovery time.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}}},"Health":{"description":"Stable API health response.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"Present when an Idempotency-Key was supplied. true means this response was replayed from the stored idempotency record; false means this request created the record.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthEnvelope"}}}},"AccountProfile":{"description":"Current account profile.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountProfileEnvelope"}}}},"AccountBalance":{"description":"Cached balance and subscription-adjacent state for the authenticated caller.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountBalanceEnvelope"}}}},"ApiKeyList":{"description":"Caller-owned API key metadata without raw key material or token hashes.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyListEnvelope"}}}},"ApiKeyCreated":{"description":"API key created. The raw key is returned only in this response.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreatedEnvelope"}}}},"ApiKeyRevoked":{"description":"Caller-owned API key was revoked, or was already revoked.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRevokedEnvelope"}}}},"FeedbackSubmitted":{"description":"Feedback was stored. Discord forwarding is best-effort and not reflected in this response.","headers":{"Cache-Control":{"description":"Always no-store.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackSubmitEnvelope"}}}}},"schemas":{"GenerationPreferencesEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/GenerationPreferences"},"request_id":{"type":"string"}},"additionalProperties":false},"GenerationPreferences":{"type":"object","required":["allow_fallbacks"],"properties":{"allow_fallbacks":{"type":"boolean"}},"additionalProperties":false},"StudioAccountCapabilitiesEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioAccountCapabilitiesPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"ApiKeyCreateRequest":{"type":"object","required":["name","scopes"],"properties":{"name":{"type":"string","minLength":1,"maxLength":80},"scopes":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ApiScope"},"description":"Duplicate scopes are accepted and deduplicated."},"expires_at":{"type":["string","null"],"format":"date-time","description":"Optional expiration timestamp. Null or omitted creates a non-expiring key."}},"additionalProperties":true},"StudioProjectsEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectsPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioPromoteProjectRequest":{"type":"object","required":["schema_version","name"],"properties":{"schema_version":{"type":"integer","const":1},"name":{"type":"string","minLength":1,"pattern":"\\S","description":"Project name. Leading and trailing whitespace is trimmed; the trimmed name must be 1-120 characters and must not contain null characters or malformed Unicode."}},"additionalProperties":false},"StudioProjectEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectDeleteRequest":{"type":"object","required":["schema_version","expected_project_kind","delete_ai_designed_voices"],"properties":{"schema_version":{"type":"integer","const":1},"expected_project_kind":{"type":"string","enum":["standalone","named"],"description":"The project kind the deleting client most recently observed. The server rejects deletion if the live kind has changed."},"delete_ai_designed_voices":{"type":"boolean"}},"additionalProperties":false},"StudioProjectDeleteEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectDeletePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectDeletionInfoEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectDeletionInfoPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioCreateStandaloneSectionRequest":{"type":"object","required":["schema_version","actor_session_id","client_mutation_id","title","raw_text"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid","description":"Idempotency key; a replay with the same canonical request returns the committed result."},"title":{"type":"string","maxLength":500,"description":"At most 500 UTF-16 code units. Must not contain null characters or malformed Unicode."},"raw_text":{"type":"string","description":"Exact section text stored as one unparsed block. At most 8 MiB of UTF-8 (the whole request body is also limited to 8 MiB). Must not contain null characters or malformed Unicode."}},"additionalProperties":false},"StudioCreateSectionEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioCreateSectionPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectSectionsEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectSectionsPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioCreateSectionRequest":{"type":"object","required":["schema_version","actor_session_id","client_mutation_id","base_section_order_version","title","raw_text"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid","description":"Idempotency key; a replay with the same canonical request returns the committed result."},"base_section_order_version":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Section-order version the client last observed; null when the project has not initialized Studio."},"title":{"type":"string","maxLength":500,"description":"At most 500 UTF-16 code units. Must not contain null characters or malformed Unicode."},"raw_text":{"type":"string","description":"Exact section text stored as one unparsed block. At most 8 MiB of UTF-8 (the whole request body is also limited to 8 MiB). Must not contain null characters or malformed Unicode."}},"additionalProperties":false},"StudioMoveSectionRequest":{"type":"object","required":["schema_version","actor_session_id","client_mutation_id","base_section_order_version","to_index"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid","description":"Idempotency key; a replay with the same canonical request returns the committed result."},"base_section_order_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"to_index":{"type":"integer","minimum":0,"maximum":4999,"description":"Zero-based target index in the active section order."}},"additionalProperties":false},"StudioSectionLifecycleEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSectionLifecyclePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioDeleteSectionRequest":{"type":"object","required":["schema_version","actor_session_id","client_mutation_id","base_section_order_version","base_document_version"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid","description":"Idempotency key; a replay with the same canonical request returns the committed result."},"base_section_order_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"base_document_version":{"type":"integer","minimum":1,"maximum":9007199254740991}},"additionalProperties":false},"StudioSectionDeletionInfoEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSectionDeletionInfoPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioDocumentEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioDocumentPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioDocumentSaveRequest":{"type":"object","required":["schema_version","actor_session_id","client_mutation_id","base_document_version","base_speaker_registry_version","target_block_versions","target_speaker_versions","commands"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid"},"base_document_version":{"type":"integer","minimum":1},"base_speaker_registry_version":{"type":"integer","minimum":1},"target_block_versions":{"type":"object","additionalProperties":{"type":"integer","minimum":1}},"target_speaker_versions":{"type":"object","additionalProperties":{"type":"integer","minimum":1}},"commands":{"type":"array","minItems":1,"maxItems":1000,"items":{"oneOf":[{"$ref":"#/components/schemas/StudioDocumentSetTitleCommand"},{"$ref":"#/components/schemas/StudioSetSectionPacingCommand"},{"$ref":"#/components/schemas/StudioSetSectionSfxEnabledCommand"},{"$ref":"#/components/schemas/StudioDocumentReplaceTextCommand"},{"$ref":"#/components/schemas/StudioDocumentInsertBlockCommand"},{"$ref":"#/components/schemas/StudioDocumentDeleteBlockCommand"},{"$ref":"#/components/schemas/StudioDocumentMoveBlockCommand"},{"$ref":"#/components/schemas/StudioDocumentCreateSfxCommand"},{"$ref":"#/components/schemas/StudioDocumentUpdateSfxCommand"},{"$ref":"#/components/schemas/StudioDocumentSplitBlocksCommand"},{"$ref":"#/components/schemas/StudioDocumentMergeBlocksCommand"},{"$ref":"#/components/schemas/StudioDocumentUpsertAnnotationCommand"},{"$ref":"#/components/schemas/StudioDocumentRemoveAnnotationCommand"},{"$ref":"#/components/schemas/StudioDocumentUpsertPointCommand"},{"$ref":"#/components/schemas/StudioDocumentRemovePointCommand"},{"$ref":"#/components/schemas/StudioDocumentUpsertDeliveryControlSetCommand"},{"$ref":"#/components/schemas/StudioDocumentRemoveDeliveryControlSetCommand"},{"$ref":"#/components/schemas/StudioDocumentSetBlockAttributionCommand"},{"$ref":"#/components/schemas/StudioDocumentCreateSpeakerCommand"},{"$ref":"#/components/schemas/StudioDocumentUpdateSpeakerCommand"},{"$ref":"#/components/schemas/StudioDocumentDeleteSpeakerCommand"},{"$ref":"#/components/schemas/StudioDocumentSetSpeakerCastingCommand"},{"$ref":"#/components/schemas/StudioDocumentSetGenerationProfileOverrideCommand"},{"$ref":"#/components/schemas/StudioDocumentApplySourceDocumentCommand"}]}}},"additionalProperties":false},"StudioScriptImportRequest":{"description":"Import a complete speaker-labeled script. To change only section spacing, use the set_section_pacing document command instead.","type":"object","required":["schema_version","actor_session_id","client_mutation_id","base_document_version","base_speaker_registry_version","script","speakers"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid"},"base_document_version":{"type":"integer","minimum":1},"base_speaker_registry_version":{"type":"integer","minimum":1},"script":{"type":"string","minLength":1,"description":"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."},"speakers":{"type":"object","description":"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.","additionalProperties":{"type":"object","required":["voice_id","generation_profile"],"properties":{"voice_id":{"type":["string","null"],"format":"uuid"},"generation_profile":{"$ref":"#/components/schemas/StudioGenerationProfileRequest"}},"additionalProperties":false}}},"additionalProperties":false},"StudioProjectSpeakerUsageEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectSpeakerUsagePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectSpeakerCastingRequest":{"type":"object","additionalProperties":false,"required":["schema_version","actor_session_id","client_mutation_id","current_section_id","base_speaker_registry_version","speaker_version","voice_id","generation_profile","casting_default_key"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid"},"client_mutation_id":{"type":"string","format":"uuid"},"current_section_id":{"type":"string","format":"uuid"},"base_speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"voice_id":{"type":["string","null"],"format":"uuid"},"generation_profile":{"anyOf":[{"$ref":"#/components/schemas/StudioGenerationProfileRequest"},{"type":"null"}]},"casting_default_key":{"type":["string","null"],"minLength":1,"maxLength":200}},"allOf":[{"if":{"properties":{"voice_id":{"type":"null"}}},"then":{"properties":{"generation_profile":{"type":"null"},"casting_default_key":{"type":"null"}}},"else":{"properties":{"generation_profile":{"$ref":"#/components/schemas/StudioGenerationProfileRequest"}}}}],"description":"Assign or clear a voice and complete profile together. Use a speech model for casting; Stable Audio profiles are for generated SFX. Partial overrides use document commands and are validated in their effective context."},"StudioProjectSpeakerCastingEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectSpeakerCastingPayload"},"request_id":{"type":"string"}}},"StudioWorkflowPrepareSectionsRequest":{"type":"object","required":["schema_version","workflow_kind","actor_session_id","client_mutation_id","section_ids"],"properties":{"schema_version":{"type":"integer","const":1},"workflow_kind":{"type":"string","const":"prepare_sections"},"actor_session_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Client session that issued the request."},"client_mutation_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Idempotency key; the workflow ID is derived from it. Reusing it for different content returns 409."},"section_ids":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"Sections to prepare, in order; values must be unique.","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}}},"additionalProperties":false,"description":"Start ordered section preparation."},"StudioWorkflowCreateAudioV2Request":{"type":"object","description":"Create Audio v2. Generated sound effects and automatic placement of linked project sounds are independent; when both run, project sounds are placed first. Section limit: 12 with both sound lanes enabled (the default), 14 with one, 16 with none. A target_scope requires exactly one section and both lanes set to false.","required":["schema_version","workflow_kind","actor_session_id","client_mutation_id","section_ids"],"properties":{"schema_version":{"type":"integer","const":2},"workflow_kind":{"type":"string","const":"create_audio"},"actor_session_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Client session that issued the request."},"client_mutation_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Idempotency key; the workflow ID is derived from it. Reusing it for different content returns 409."},"section_ids":{"type":"array","minItems":1,"maxItems":16,"uniqueItems":true,"description":"Sections to create audio for; values must be unique.","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"include_generated_sfx":{"type":"boolean","default":true,"description":"Enables the generated-SFX authoring lane."},"place_project_sounds":{"type":"boolean","default":true,"description":"Enables automatic matching and placement from ready, accessible sounds explicitly linked to this project."},"direct_emotion":{"type":"boolean","default":true,"description":"Enables automatic emotion: a direct_emotion step adds provider delivery directions to spoken blocks that have none for their engine. Direction text sent to the provider is billed (ElevenLabs v4 audio tags). For pre-run estimates, clients add about 18 ElevenLabs v4 tokens per untagged ElevenLabs v4 block while this is on; the charge is the tokens actually sent. Omitted means true."},"target_scope":{"description":"Optional focused source-block scope. Null or omitted targets the selected sections. Focused requests must set both optional sound lanes to false.","anyOf":[{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"},{"type":"null"}]}},"additionalProperties":false,"allOf":[{"if":{"allOf":[{"required":["include_generated_sfx"],"properties":{"include_generated_sfx":{"const":false}}},{"required":["place_project_sounds"],"properties":{"place_project_sounds":{"const":false}}}]},"then":{"properties":{"section_ids":{"maxItems":16}}},"else":{"if":{"anyOf":[{"required":["include_generated_sfx"],"properties":{"include_generated_sfx":{"const":false}}},{"required":["place_project_sounds"],"properties":{"place_project_sounds":{"const":false}}}]},"then":{"properties":{"section_ids":{"maxItems":14}}},"else":{"properties":{"section_ids":{"maxItems":12}}}}},{"if":{"required":["target_scope"],"properties":{"target_scope":{"type":"object"}}},"then":{"required":["include_generated_sfx","place_project_sounds"],"properties":{"section_ids":{"maxItems":1},"include_generated_sfx":{"const":false},"place_project_sounds":{"const":false}}}}]},"StudioWorkflowEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioWorkflowPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioWorkflowLatestEnvelope":{"type":"object","required":["data"],"properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/StudioWorkflowPayload"},{"type":"null"}],"description":"Latest matching workflow, or null when none exists."},"request_id":{"type":"string"}},"additionalProperties":false},"StudioWorkflowProgressEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/StudioWorkflowProgressPayload"},{"$ref":"#/components/schemas/StudioWorkflowProgressV2Payload"}]},"request_id":{"type":"string"}}},"StudioWorkflowResumeRequest":{"type":"object","required":["schema_version","actor_session_id","client_mutation_id"],"properties":{"schema_version":{"type":"integer","const":1},"actor_session_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Client session that issued the request."},"client_mutation_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Idempotency key; the successor workflow ID is derived from it. Reusing it for different content returns 409."}},"additionalProperties":false,"description":"Resume a failed or partially completed workflow as a new linked successor run."},"StudioSectionMediaReadEnvelope":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/StudioSectionMediaPayload"},{"$ref":"#/components/schemas/StudioSectionMediaPayloadV2"}]},"request_id":{"type":"string"}},"additionalProperties":false},"StudioSectionGenerationAvailabilityEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSectionGenerationAvailabilityPayload"},"request_id":{"type":"string"}}},"StudioPlaybackManifestReadEnvelope":{"type":"object","required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/StudioPlaybackManifestPayload"},{"$ref":"#/components/schemas/StudioPlaybackManifestPayloadV2"}]},"request_id":{"type":"string"}},"additionalProperties":false},"StudioMediaAccessUrlRequest":{"type":"object","required":["schema_version","disposition"],"properties":{"schema_version":{"const":1},"disposition":{"type":"string","enum":["inline","attachment"]},"filename":{"type":"string","minLength":1,"maxLength":255}},"additionalProperties":false},"StudioMediaAccessUrlEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioMediaAccessUrlPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioMasteringProfileEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioMasteringProfilePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectExportCreateRequest":{"type":"object","additionalProperties":false,"required":["schema_version","format","pin"],"properties":{"schema_version":{"type":"integer","const":1},"format":{"$ref":"#/components/schemas/StudioExportFormat"},"pin":{"type":"string","const":"current","description":"Capture saved document, speaker registry, and mastering versions at enqueue. This does not capture an atomic queue-time media revision."},"sections":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"description":"Active section IDs belonging to this project. Returned children follow project order, not request order. Omit to select all active sections; the resulting selection must contain one to 100 sections.","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}}}},"StudioProjectExportEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectExportPayload"},"request_id":{"type":"string"}}},"StudioExportFormat":{"type":"string","enum":["mp3","wav","m4b","epub","srt"]},"StudioProjectExportsEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectExportsPayload"},"request_id":{"type":"string"}}},"StudioProjectExportFreshnessEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectExportFreshnessPayload"},"request_id":{"type":"string"}}},"StudioExportStatus":{"type":"string","enum":["queued","running","retry_wait","canceling","completed","failed","cancelled","superseded"]},"StudioExportsEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioExportsPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioExportCreateRequest":{"type":"object","required":["schema_version","section_id","document_version","speaker_registry_version","mastering_version","format"],"properties":{"schema_version":{"const":1},"section_id":{"type":"string","format":"uuid"},"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"format":{"$ref":"#/components/schemas/StudioExportFormat"}},"additionalProperties":false},"StudioExportEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioExport"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioExportTimelineReadEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/StudioExportTimelinePayload"},{"$ref":"#/components/schemas/StudioExportTimelinePayloadV2"}]},"request_id":{"type":"string"}}},"StudioSectionShareEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSectionSharePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioSectionSharePublishRequest":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/StudioShareSource"}},"additionalProperties":false,"description":"Send {} or name the Studio surface the owner shared from."},"StudioProjectShareEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectSharePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectSharePublishRequest":{"type":"object","properties":{"source":{"$ref":"#/components/schemas/StudioShareSource"}},"additionalProperties":false,"description":"Send {} or name the Studio surface the owner shared from."},"StudioSoundListEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSoundListPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioSoundUploadRequest":{"type":"object","required":["schema_version","client_mutation_id","name","description","tags","is_public","rights_acknowledgment_version","file"],"properties":{"schema_version":{"type":"string","const":"studio-sound-upload-1"},"client_mutation_id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":1000},"tags":{"type":"array","minItems":1,"maxItems":12,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":40}},"is_public":{"type":"boolean"},"rights_acknowledgment_version":{"type":"string","const":"studio-sound-rights-1"},"file":{"$ref":"#/components/schemas/StudioSoundFile"}},"additionalProperties":false},"StudioSoundUploadEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSoundUploadPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioSoundUploadCompleteRequest":{"type":"object","required":["schema_version"],"properties":{"schema_version":{"type":"string","const":"studio-sound-upload-complete-1"}},"additionalProperties":false},"StudioSoundEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSoundEffect"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioSoundMutationRequest":{"type":"object","required":["schema_version","client_mutation_id","expected_metadata_version"],"properties":{"schema_version":{"type":"string","const":"studio-sound-mutation-1"},"client_mutation_id":{"type":"string","format":"uuid"},"expected_metadata_version":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":1000},"tags":{"type":"array","minItems":1,"maxItems":12,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":40}},"is_public":{"type":"boolean"}},"anyOf":[{"required":["name"]},{"required":["description"]},{"required":["tags"]},{"required":["is_public"]}],"additionalProperties":false},"StudioSoundDeleteRequest":{"type":"object","required":["schema_version","client_mutation_id","expected_metadata_version"],"properties":{"schema_version":{"type":"string","const":"studio-sound-mutation-1"},"client_mutation_id":{"type":"string","format":"uuid"},"expected_metadata_version":{"type":"integer","minimum":1}},"additionalProperties":false},"StudioSoundDeleteEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSoundDeletePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioSoundPreviewEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioSoundPreviewPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectSoundListEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectSoundListPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectSoundMutationRequest":{"type":"object","required":["schema_version","client_mutation_id","sound_effect_id","expected_registry_version"],"properties":{"schema_version":{"type":"string","const":"studio-project-sound-source-1"},"client_mutation_id":{"type":"string","format":"uuid"},"sound_effect_id":{"type":"string","format":"uuid"},"expected_registry_version":{"type":"integer","minimum":1}},"additionalProperties":false},"StudioProjectSoundMutationEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/StudioProjectSoundMutationPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"PublicSoundListEnvelope":{"type":"object","required":["data","pagination"],"properties":{"data":{"$ref":"#/components/schemas/PublicSoundListPayload"},"pagination":{"$ref":"#/components/schemas/Pagination"},"request_id":{"type":"string"}},"additionalProperties":false},"PublicSoundEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PublicSound"},"request_id":{"type":"string"}},"additionalProperties":false},"FeedbackSubmitRequest":{"type":"object","required":["message"],"properties":{"replyEmail":{"type":"string","format":"email","maxLength":254,"description":"Required when authentication does not provide an account email. Trimmed and stored privately; never added to Discord notifications. Authenticated account email takes precedence."},"message":{"type":"string","minLength":1,"maxLength":2000,"description":"Feedback text. The service trims whitespace before storage and Discord forwarding."},"type":{"type":"string","enum":["bug","feature","general","improvement"],"default":"general"},"source":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_]*$","default":"global","description":"Stable identifier for the originating product surface and client."}},"additionalProperties":true,"description":"Text-only JSON feedback. To attach images, send multipart/form-data instead.","not":{"required":["images"]}},"FeedbackSubmitMultipartRequest":{"type":"object","required":["message"],"properties":{"replyEmail":{"type":"string","format":"email","maxLength":254,"description":"Required when authentication does not provide an account email. Trimmed and stored privately; never added to Discord notifications. Authenticated account email takes precedence."},"message":{"type":"string","minLength":1,"maxLength":2000,"description":"Feedback text. The service trims whitespace before storage and Discord forwarding."},"type":{"type":"string","enum":["bug","feature","general","improvement"],"default":"general"},"source":{"type":"string","minLength":2,"maxLength":64,"pattern":"^[a-z][a-z0-9_]*$","default":"global","description":"Stable identifier for the originating product surface and client."},"images":{"type":"array","maxItems":5,"items":{"type":"string","format":"binary"},"description":"Repeat the images multipart field for each still PNG, JPEG, or WebP file. Up to five images, 5 MiB each, 15 MiB total, and 32 megapixels per decoded image. Unsupported, corrupt, or excessive images reject the whole submission. Any circles or annotations should already be rendered into the image pixels."}},"additionalProperties":false},"ApiErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ApiError"},"request_id":{"type":"string"}}},"HealthEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/HealthPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"AccountProfileEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AccountProfilePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"AccountBalanceEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/AccountBalancePayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioAccountCapabilitiesPayload":{"type":"object","required":["schema_version","as_of","plan","balance","studio_funding","campaign_dialogs","campaign_offers","purchases","actions"],"properties":{"schema_version":{"type":"string","const":"studio-account-capabilities-4"},"as_of":{"type":"string","format":"date-time"},"plan":{"type":"object","required":["tier","display_name","character_limit"],"properties":{"tier":{"type":"string","enum":["zerowinter","mywinter","ultrawinter","hyperwinter"]},"display_name":{"type":"string"},"character_limit":{"type":"integer","minimum":1}},"additionalProperties":false},"balance":{"type":"object","required":["settled_snowcoins","held_snowcoins","available_snowcoins","settled_words","held_words","available_words"],"properties":{"settled_snowcoins":{"type":"integer","minimum":0},"held_snowcoins":{"type":"integer","minimum":0},"available_snowcoins":{"type":"integer","minimum":0},"settled_words":{"type":"integer","minimum":0},"held_words":{"type":"integer","minimum":0},"available_words":{"type":"integer","minimum":0}},"additionalProperties":false},"studio_funding":{"type":"object","required":["promotional","total_available_snowcoins","total_held_snowcoins","total_available_words","total_held_words"],"properties":{"promotional":{"type":"object","required":["available_snowcoins","held_snowcoins","available_words","held_words","grants"],"properties":{"available_snowcoins":{"type":"integer","minimum":0},"held_snowcoins":{"type":"integer","minimum":0},"available_words":{"type":"integer","minimum":0},"held_words":{"type":"integer","minimum":0},"grants":{"type":"array","items":{"type":"object","required":["campaign_key","display_name","available_snowcoins","held_snowcoins","available_words","held_words","expires_at"],"properties":{"campaign_key":{"type":"string"},"display_name":{"type":"string"},"available_snowcoins":{"type":"integer","minimum":0},"held_snowcoins":{"type":"integer","minimum":0},"available_words":{"type":"integer","minimum":0},"held_words":{"type":"integer","minimum":0},"expires_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false}}},"additionalProperties":false},"total_available_snowcoins":{"type":"integer","minimum":0},"total_held_snowcoins":{"type":"integer","minimum":0},"total_available_words":{"type":"integer","minimum":0},"total_held_words":{"type":"integer","minimum":0}},"additionalProperties":false},"campaign_dialogs":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/StudioCampaignDialog"}},"campaign_offers":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/StudioCampaignDialog"}},"purchases":{"type":"object","required":["small_word_packs_eligible"],"properties":{"small_word_packs_eligible":{"type":"boolean"}},"additionalProperties":false},"actions":{"type":"object","required":["prepare_text","speech_generation","sfx_generation","voice_design","voice_cloning","final_render"],"properties":{"prepare_text":{"$ref":"#/components/schemas/StudioAccountActionCapability"},"speech_generation":{"$ref":"#/components/schemas/StudioAccountActionCapability"},"sfx_generation":{"$ref":"#/components/schemas/StudioAccountActionCapability"},"voice_design":{"$ref":"#/components/schemas/StudioAccountActionCapability"},"voice_cloning":{"$ref":"#/components/schemas/StudioAccountActionCapability"},"final_render":{"$ref":"#/components/schemas/StudioAccountActionCapability"}},"additionalProperties":false}},"additionalProperties":false},"ApiKeyListEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApiKeyListPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"ApiScope":{"type":"string","enum":["account:read","account:write","api_keys:read","api_keys:write","audio_runs:read","audio_runs:write","billing:read","billing:write","demo_videos:read","demo_videos:write","feedback:write","projects:read","projects:write","reactions:read","reactions:write","stories:read","stories:write","studio:read","studio:write","voice_pins:read","voice_pins:write","voice_actors:read","voice_shares:read","voice_shares:write","voices:read","voices:write"]},"ApiKeyCreatedEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApiKeyCreatedPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"ApiKeyRevokedEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApiKeyRevokedPayload"},"request_id":{"type":"string"}},"additionalProperties":false},"StudioProjectsPayload":{"type":"object","required":["projects","unassigned_sections"],"properties":{"projects":{"type":"array","items":{"$ref":"#/components/schemas/StudioProjectSummary"}},"unassigned_sections":{"type":"array","items":{"$ref":"#/components/schemas/StudioUnassignedSection"},"description":"Standalone Studio stories shown under the virtual Unassigned group, one section per hidden project."}},"additionalProperties":false},"StudioProjectPayload":{"type":"object","required":["project"],"properties":{"project":{"$ref":"#/components/schemas/StudioProjectSummary"}},"additionalProperties":false},"StudioProjectDeletePayload":{"type":"object","required":["success","project_id","mode","stories_deleted","audio_runs_deleted","clips_deleted","public_stories_deleted","shared_stories_deleted","active_share_links_deleted","studio_sections_deleted","studio_media_marked_for_deletion","files_deleted","ai_designed_voices_deleted","ai_designed_voices_retained"],"properties":{"success":{"type":"boolean","const":true},"project_id":{"type":"string","format":"uuid"},"mode":{"type":"string","const":"project_and_stories"},"stories_deleted":{"type":"integer","minimum":0},"audio_runs_deleted":{"type":"integer","minimum":0},"clips_deleted":{"type":"integer","minimum":0},"public_stories_deleted":{"type":"integer","minimum":0},"shared_stories_deleted":{"type":"integer","minimum":0},"active_share_links_deleted":{"type":"integer","minimum":0},"studio_sections_deleted":{"type":"integer","minimum":0},"studio_media_marked_for_deletion":{"type":"integer","minimum":0},"files_deleted":{"type":"integer","minimum":0},"ai_designed_voices_deleted":{"type":"integer","minimum":0},"ai_designed_voices_retained":{"type":"integer","minimum":0}},"additionalProperties":false},"StudioProjectDeletionInfoPayload":{"type":"object","required":["project_id","section_count","other_story_count","block_count","audio_run_count","clip_count","studio_media_count","active_share_link_count","ai_designed_voice_count"],"properties":{"project_id":{"type":"string","format":"uuid"},"section_count":{"type":"integer","minimum":0},"other_story_count":{"type":"integer","minimum":0},"block_count":{"type":"integer","minimum":0},"audio_run_count":{"type":"integer","minimum":0},"clip_count":{"type":"integer","minimum":0},"studio_media_count":{"type":"integer","minimum":0},"active_share_link_count":{"type":"integer","minimum":0},"ai_designed_voice_count":{"type":"integer","minimum":0}},"additionalProperties":false},"StudioCreateSectionPayload":{"type":"object","required":["project_id","section","document","section_order_version","speaker_registry_version","idempotent_replay"],"properties":{"project_id":{"type":"string","format":"uuid"},"section":{"$ref":"#/components/schemas/StudioSectionSummary"},"document":{"$ref":"#/components/schemas/StudioSectionDocument"},"section_order_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"idempotent_replay":{"type":"boolean","description":"True when client_mutation_id matched an already committed creation (HTTP 200); false for a new section (HTTP 201)."}},"additionalProperties":false},"StudioProjectSectionsPayload":{"type":"object","required":["project_id","initialized","casting_defaults_mode","default_automation_profile","section_order_version","speaker_registry_version","sections"],"properties":{"project_id":{"type":"string","format":"uuid"},"initialized":{"type":"boolean","description":"False when the owned project has no Studio state yet; the nullable fields are then null and sections is empty."},"casting_defaults_mode":{"type":["string","null"],"enum":["apply_exact","suggest","ignore",null]},"default_automation_profile":{"type":["string","null"],"enum":["quick","balanced","directed",null]},"section_order_version":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991},"sections":{"type":"array","items":{"$ref":"#/components/schemas/StudioSectionSummary"},"description":"Active sections in project order."}},"additionalProperties":false},"StudioSectionLifecyclePayload":{"type":"object","required":["operation","project_id","section_id","section_order_version","idempotent_replay"],"properties":{"operation":{"type":"string","enum":["move_section","delete_section"],"description":"move_section for PATCH and delete_section for DELETE."},"project_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"section_order_version":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Section-order version committed by this mutation."},"idempotent_replay":{"type":"boolean"}},"additionalProperties":false},"StudioSectionDeletionInfoPayload":{"type":"object","required":["project_id","section_id","block_count","generated_clip_count","active_share_link_count"],"properties":{"project_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"block_count":{"type":"integer","minimum":0},"generated_clip_count":{"type":"integer","minimum":0},"active_share_link_count":{"type":"integer","minimum":0}},"additionalProperties":false},"StudioDocumentPayload":{"type":"object","required":["actor_user_id","project_id","document","source_draft"],"properties":{"actor_user_id":{"type":"string","format":"uuid","description":"Authenticated caller; clients partition local recovery state by this ID."},"project_id":{"type":"string","format":"uuid"},"document":{"$ref":"#/components/schemas/StudioSectionDocument"},"source_draft":{"oneOf":[{"$ref":"#/components/schemas/StudioSourceDraft"},{"type":"null"}],"description":"The caller's saved, uncommitted Advanced Source draft for this section, or null."}},"additionalProperties":false},"StudioDocumentSetTitleCommand":{"type":"object","required":["kind","title"],"properties":{"kind":{"type":"string","const":"set_title"},"title":{"type":"string","maxLength":500}},"additionalProperties":false},"StudioSetSectionPacingCommand":{"type":"object","description":"Set silence between consecutive audible passages without replacing the script. Both gaps are required; normal document and cast version checks apply.","required":["kind","same_speaker_gap_ms","different_speaker_gap_ms"],"properties":{"kind":{"type":"string","const":"set_section_pacing"},"same_speaker_gap_ms":{"type":"integer","minimum":0,"maximum":1000},"different_speaker_gap_ms":{"type":"integer","minimum":0,"maximum":1000}},"additionalProperties":false},"StudioSetSectionSfxEnabledCommand":{"type":"object","required":["kind","sfx_enabled"],"properties":{"kind":{"type":"string","const":"set_section_sfx_enabled"},"sfx_enabled":{"type":"boolean","description":"Whether authored section sound effects are audible in playback and included in rendered exports. Disabling preserves authored SFX blocks and renditions."}},"additionalProperties":false},"StudioDocumentReplaceTextCommand":{"type":"object","required":["kind","block_id","start_utf16","end_utf16","expected_text_hash","text"],"properties":{"kind":{"type":"string","const":"replace_text"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"start_utf16":{"type":"integer","minimum":0,"maximum":9007199254740991},"end_utf16":{"type":"integer","minimum":0,"maximum":9007199254740991},"expected_text_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"text":{"type":"string"}},"additionalProperties":false,"description":"Offsets are UTF-16 indices. Runtime also verifies the expected text hash and range against the current block."},"StudioDocumentInsertBlockCommand":{"type":"object","required":["kind","index","block"],"properties":{"kind":{"type":"string","const":"insert_block"},"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block":{"$ref":"#/components/schemas/StudioAstScriptBlock"}},"additionalProperties":false},"StudioDocumentDeleteBlockCommand":{"type":"object","required":["kind","block_id"],"properties":{"kind":{"type":"string","const":"delete_block"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"}},"additionalProperties":false},"StudioDocumentMoveBlockCommand":{"type":"object","required":["kind","block_id","to_index"],"properties":{"kind":{"type":"string","const":"move_block"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"to_index":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"StudioDocumentCreateSfxCommand":{"type":"object","required":["kind","block_id","content","placement"],"properties":{"kind":{"type":"string","const":"create_sfx"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"content":{"$ref":"#/components/schemas/StudioAstSfxContent"},"placement":{"$ref":"#/components/schemas/StudioAstSfxPlacement"}},"additionalProperties":false,"description":"For an uploaded project sound, use content.source.kind=project_sound, seed=null, and a section or block placement anchor."},"StudioDocumentUpdateSfxCommand":{"type":"object","required":["kind","block_id","content","placement"],"properties":{"kind":{"type":"string","const":"update_sfx"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"content":{"$ref":"#/components/schemas/StudioAstSfxContent"},"placement":{"$ref":"#/components/schemas/StudioAstSfxPlacement"}},"additionalProperties":false},"StudioDocumentSplitBlocksCommand":{"type":"object","required":["kind","targets"],"properties":{"kind":{"type":"string","const":"split_blocks"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/StudioDocumentSplitBlockTarget"},"minItems":1,"maxItems":2}},"additionalProperties":false},"StudioDocumentMergeBlocksCommand":{"type":"object","required":["kind","left_block_id","right_block_id","expected_left_text_length_utf16"],"properties":{"kind":{"type":"string","const":"merge_blocks"},"left_block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"right_block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"expected_left_text_length_utf16":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false,"description":"Left and right block IDs must differ."},"StudioDocumentUpsertAnnotationCommand":{"type":"object","required":["kind","block_id","annotation"],"properties":{"kind":{"type":"string","const":"upsert_annotation"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"annotation":{"$ref":"#/components/schemas/StudioAstTextAnnotation"}},"additionalProperties":false},"StudioDocumentRemoveAnnotationCommand":{"type":"object","required":["kind","block_id","annotation_id"],"properties":{"kind":{"type":"string","const":"remove_annotation"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"annotation_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"}},"additionalProperties":false},"StudioDocumentUpsertPointCommand":{"type":"object","required":["kind","block_id","point"],"properties":{"kind":{"type":"string","const":"upsert_point"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"point":{"$ref":"#/components/schemas/StudioAstPointNode"}},"additionalProperties":false},"StudioDocumentRemovePointCommand":{"type":"object","required":["kind","block_id","point_id"],"properties":{"kind":{"type":"string","const":"remove_point"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"point_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"}},"additionalProperties":false},"StudioDocumentUpsertDeliveryControlSetCommand":{"type":"object","required":["kind","block_id","set"],"properties":{"kind":{"type":"string","const":"upsert_delivery_control_set"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"set":{"$ref":"#/components/schemas/StudioAstDeliveryControlSet"}},"additionalProperties":false},"StudioDocumentRemoveDeliveryControlSetCommand":{"type":"object","required":["kind","block_id","provider","model"],"properties":{"kind":{"type":"string","const":"remove_delivery_control_set"},"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"provider":{"type":"string","pattern":"^[a-z][a-z0-9_-]{0,63}$"},"model":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false},"StudioDocumentSetBlockAttributionCommand":{"type":"object","required":["kind","targets"],"properties":{"kind":{"type":"string","const":"set_block_attribution"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/StudioDocumentAttributionTarget"},"minItems":1,"maxItems":1000}},"additionalProperties":false,"description":"Target block IDs must be unique."},"StudioDocumentCreateSpeakerCommand":{"type":"object","required":["kind","speaker","restore_from_speaker_version","casting_default_key"],"properties":{"kind":{"type":"string","const":"create_speaker"},"speaker":{"$ref":"#/components/schemas/StudioDocumentSpeakerRequest"},"restore_from_speaker_version":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"null"}]},"casting_default_key":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"additionalProperties":false,"description":"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.","allOf":[{"if":{"properties":{"casting_default_key":{"type":"string"}},"required":["casting_default_key"]},"then":{"properties":{"speaker":{"properties":{"voice_id":{"type":"string"}}}}}}]},"StudioDocumentUpdateSpeakerCommand":{"type":"object","required":["kind","speaker_id","name"],"properties":{"kind":{"type":"string","const":"update_speaker"},"speaker_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"name":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false,"description":"The name must be trimmed."},"StudioDocumentDeleteSpeakerCommand":{"type":"object","required":["kind","speaker_id"],"properties":{"kind":{"type":"string","const":"delete_speaker"},"speaker_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"}},"additionalProperties":false},"StudioDocumentSetSpeakerCastingCommand":{"type":"object","required":["kind","speaker_id","voice_id","generation_profile","casting_default_key"],"properties":{"kind":{"type":"string","const":"set_speaker_casting"},"speaker_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"voice_id":{"anyOf":[{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},{"type":"null"}]},"generation_profile":{"anyOf":[{"$ref":"#/components/schemas/StudioGenerationProfileRequest"},{"type":"null"}]},"casting_default_key":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"additionalProperties":false,"description":"A non-null casting_default_key requires a voice_id. The effective profile is validated in speaker context.","allOf":[{"if":{"properties":{"casting_default_key":{"type":"string"}},"required":["casting_default_key"]},"then":{"properties":{"voice_id":{"type":"string"}}}}]},"StudioDocumentSetGenerationProfileOverrideCommand":{"type":"object","required":["kind","targets"],"properties":{"kind":{"type":"string","const":"set_generation_profile_override"},"targets":{"type":"array","items":{"$ref":"#/components/schemas/StudioDocumentProfileTarget"},"minItems":1,"maxItems":1000}},"additionalProperties":false,"description":"Target block IDs must be unique; effective options are validated against the inherited provider/model."},"StudioDocumentApplySourceDocumentCommand":{"type":"object","required":["kind","document"],"properties":{"kind":{"type":"string","const":"apply_source_document"},"document":{"$ref":"#/components/schemas/StudioDocumentSourceDocumentRequest"}},"additionalProperties":false,"description":"Replaces the source document under the save request's version fences."},"StudioGenerationProfileRequest":{"description":"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.","type":"object","additionalProperties":false,"required":["provider","model","fallback","controls","options"],"properties":{"provider":{"type":"string","pattern":"^[a-z][a-z0-9_-]{0,63}$"},"model":{"type":"string","minLength":1,"maxLength":200},"fallback":{"enum":["strict","best_effort"]},"controls":{"enum":["strict","best_effort"]},"options":{"type":"object"}},"oneOf":[{"properties":{"provider":{"const":"elevenlabs"},"model":{"const":"eleven_v4"},"options":{"$ref":"#/components/schemas/StudioProfileElevenLabsOptions"}}},{"properties":{"provider":{"const":"inworld"},"model":{"const":"inworld-2"},"options":{"$ref":"#/components/schemas/StudioProfileInworld2Options"}}},{"properties":{"provider":{"const":"inworld"},"model":{"const":"inworld-1.5-max"},"options":{"$ref":"#/components/schemas/StudioProfileInworld15Options"}}},{"properties":{"provider":{"const":"inworld"},"model":{"const":"inworld-1.5-mini"},"options":{"$ref":"#/components/schemas/StudioProfileInworld15Options"}}},{"properties":{"provider":{"const":"cartesia"},"model":{"const":"cartesia-sonic-3.6"},"options":{"$ref":"#/components/schemas/StudioProfileCartesiaOptions"}}},{"properties":{"provider":{"const":"cartesia"},"model":{"const":"cartesia-sonic-3.5"},"options":{"$ref":"#/components/schemas/StudioProfileCartesiaOptions"}}},{"properties":{"provider":{"const":"fish_audio"},"model":{"const":"fishaudio"},"options":{"$ref":"#/components/schemas/StudioProfileFishOptions"}}},{"properties":{"provider":{"const":"fish_audio"},"model":{"const":"fishaudio-s2.1-pro"},"options":{"$ref":"#/components/schemas/StudioProfileFishOptions"}}},{"properties":{"provider":{"const":"fish_audio"},"model":{"const":"fishaudio-drama-3"},"options":{"$ref":"#/components/schemas/StudioProfileFishOptions"}}},{"properties":{"provider":{"const":"smallest_ai"},"model":{"const":"lightning_v3.1"},"options":{"$ref":"#/components/schemas/StudioProfileEmptyOptions"}}},{"properties":{"provider":{"const":"openai"},"model":{"const":"gpt-4o-mini-tts"},"options":{"$ref":"#/components/schemas/StudioProfileEmptyOptions"}}},{"properties":{"provider":{"const":"openai"},"model":{"const":"tts-1-hd"},"options":{"$ref":"#/components/schemas/StudioProfileEmptyOptions"}}},{"properties":{"provider":{"const":"openai"},"model":{"const":"tts-1"},"options":{"$ref":"#/components/schemas/StudioProfileEmptyOptions"}}},{"properties":{"provider":{"const":"f5tts"},"model":{"const":"f5tts"},"options":{"$ref":"#/components/schemas/StudioProfileEmptyOptions"}}},{"properties":{"provider":{"const":"stable_audio"},"model":{"const":"stable-audio-3-medium"},"options":{"$ref":"#/components/schemas/StudioProfileStableAudioOptions"}}},{"$ref":"#/components/schemas/StudioProfileCatalogOnlyProfile"}]},"StudioProjectSpeakerUsagePayload":{"type":"object","required":["project_id","speaker_registry_version","speakers"],"properties":{"project_id":{"type":"string","format":"uuid"},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speakers":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/StudioSpeakerUsage"},"description":"Every active project speaker, including unused speakers with zero counts."}},"additionalProperties":false},"StudioProjectSpeakerCastingPayload":{"type":"object","additionalProperties":false,"required":["mutation","document"],"properties":{"mutation":{"$ref":"#/components/schemas/StudioProjectSpeakerCastingMutation"},"document":{"$ref":"#/components/schemas/StudioDocumentPayload"}}},"StudioWorkflowCreateAudioTargetScope":{"type":"object","required":["kind","blocks"],"properties":{"kind":{"type":"string","const":"source_blocks"},"blocks":{"type":"array","minItems":1,"maxItems":250,"uniqueItems":true,"description":"Focused source blocks; block_id values must be unique.","items":{"type":"object","required":["block_id","base_block_version","text_length_utf16","text_hash"],"properties":{"block_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"base_block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"text_length_utf16":{"type":"integer","minimum":1,"maximum":1000000},"text_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}},"additionalProperties":false}}},"additionalProperties":false,"description":"Focused Create Audio scope limited to specific source blocks of one section."},"StudioWorkflowPayload":{"type":"object","required":["run","steps"],"properties":{"run":{"$ref":"#/components/schemas/StudioWorkflowRun"},"steps":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/StudioWorkflowStep"},"description":"All steps in ascending step_index order."}},"additionalProperties":false,"description":"A workflow run with its ordered steps."},"StudioWorkflowProgressPayload":{"type":"object","additionalProperties":false,"required":["schema_version","workflow_run_id","ready","total"],"properties":{"schema_version":{"type":"integer","const":1},"workflow_run_id":{"type":"string","format":"uuid"},"ready":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"StudioWorkflowProgressV2Payload":{"type":"object","additionalProperties":false,"required":["schema_version","workflow_run_id","ready","total","block_issues"],"properties":{"schema_version":{"type":"integer","const":2},"workflow_run_id":{"type":"string","format":"uuid"},"ready":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_issues":{"type":"array","maxItems":2000,"items":{"$ref":"#/components/schemas/StudioWorkflowIndexedAudioIssue"}}}},"StudioSectionMediaPayload":{"type":"object","required":["section_id","playback_duration_ms","blocks"],"properties":{"section_id":{"type":"string","format":"uuid"},"playback_duration_ms":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991,"description":"Duration of the newest saved render manifest for the section's current document and speaker-registry versions; null when none exists."},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/StudioSectionMediaBlock"},"description":"One entry per document block, in document order."}},"additionalProperties":false,"description":"Current per-block media state for a Studio section."},"StudioSectionMediaPayloadV2":{"type":"object","required":["schema_version","section_id","blocks"],"properties":{"schema_version":{"type":"integer","const":2},"section_id":{"type":"string","format":"uuid"},"playback_duration_ms":{"type":["integer","null"],"minimum":0,"maximum":9007199254740991},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/StudioSectionMediaBlockV2"}}},"additionalProperties":false,"description":"Opt-in media response with authoritative active-take boundary silence handling."},"StudioSectionGenerationAvailabilityPayload":{"type":"object","additionalProperties":false,"required":["section_id","document_version","speaker_registry_version","blocks"],"properties":{"section_id":{"type":"string","format":"uuid"},"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"blocks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["block_id","generation"],"properties":{"block_id":{"type":"string","format":"uuid"},"generation":{"anyOf":[{"$ref":"#/components/schemas/StudioGenerationAvailability"},{"type":"null"}]}}}}}},"StudioPlaybackManifestPayload":{"type":"object","required":["schema_version","mastering_version","manifest_hash","manifest","assets"],"properties":{"schema_version":{"type":"integer","const":1},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"manifest_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 of the canonical manifest."},"manifest":{"$ref":"#/components/schemas/StudioPlaybackRenderManifest"},"assets":{"type":"array","maxItems":60000,"items":{"$ref":"#/components/schemas/StudioPlaybackAsset"},"description":"Exactly one entry per distinct asset_id referenced by asset sequential units and overlay units."}},"additionalProperties":false,"description":"Ephemeral current playback manifest with signed asset URLs; no render run is created."},"StudioPlaybackManifestPayloadV2":{"type":"object","required":["schema_version","mastering_version","manifest_hash","manifest","assets","unit_word_timings"],"properties":{"schema_version":{"type":"integer","const":2},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"manifest_hash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"SHA-256 of the canonical manifest."},"manifest":{"$ref":"#/components/schemas/StudioPlaybackRenderManifest"},"assets":{"type":"array","maxItems":60000,"items":{"$ref":"#/components/schemas/StudioPlaybackAsset"},"description":"Exactly one entry per distinct asset_id referenced by asset sequential units and overlay units."},"unit_word_timings":{"type":"array","maxItems":60000,"items":{"$ref":"#/components/schemas/StudioUnitWordTimings"}}},"additionalProperties":false,"description":"Opt-in playback payload with take-bound word timing sidecars. manifest_hash still hashes the unchanged audio manifest, not these optional sidecars."},"StudioMediaAccessUrlPayload":{"type":"object","required":["schema_version","asset_id","url","expires_at","content_type","size_bytes","disposition"],"properties":{"schema_version":{"const":1},"asset_id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"content_type":{"type":"string","minLength":1},"size_bytes":{"type":"integer","minimum":1},"disposition":{"type":"string","enum":["inline","attachment"]}},"additionalProperties":false},"StudioMasteringProfilePayload":{"type":"object","required":["schema_version","project_id","project_kind","mastering_version","scope","profile"],"properties":{"schema_version":{"const":1},"project_id":{"type":"string","format":"uuid"},"project_kind":{"type":"string","enum":["standalone","named"]},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"scope":{"type":"string","enum":["document","project"]},"profile":{"$ref":"#/components/schemas/StudioMasteringProfile"},"sfx_adjustments":{"type":"object","required":["nonzero_count","nonzero_section_count","fingerprint"],"properties":{"nonzero_count":{"type":"integer","minimum":0},"nonzero_section_count":{"type":"integer","minimum":0},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"additionalProperties":false}},"additionalProperties":false},"StudioProjectExportPayload":{"type":"object","additionalProperties":false,"required":["schema_version","id","project_id","format","status","percent","created_at","sections","archive"],"properties":{"schema_version":{"type":"integer","const":1},"id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Parent project export job ID."},"project_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"format":{"$ref":"#/components/schemas/StudioExportFormat"},"status":{"type":"string","enum":["queued","running","completed","partial_failed","failed"],"description":"queued when all children are queued; running while any child is active otherwise. Once all children are terminal or unavailable: completed if all succeeded, partial_failed if only some succeeded, or failed if none succeeded. Child cancellation, supersession, and unavailability count as failure, not successful completion."},"percent":{"type":"integer","minimum":0,"maximum":100,"description":"Floor of the mean child progress. Each terminal or unavailable child counts as 100, including failed, cancelled, or superseded children. Measures finished work, not success rate."},"created_at":{"type":"string","format":"date-time"},"sections":{"type":"array","minItems":1,"maxItems":100,"description":"Immutable selection and authority version plan in captured project order, with available child states or per-section unavailability errors.","items":{"type":"object","additionalProperties":false,"required":["section_id","title","export_id","authority","export","error"],"properties":{"section_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"title":{"type":"string","maxLength":500,"description":"Section title captured for this parent."},"export_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Captured child ID. Child status, manifest, and cancellation endpoints are usable only while the child remains accessible."},"authority":{"type":"object","additionalProperties":false,"required":["document_version","speaker_registry_version","mastering_version"],"description":"Immutable saved versions captured at enqueue, retained even if the child is moved or deleted.","properties":{"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991}}},"export":{"description":"Current ordinary child export payload, or null when the child is unavailable after transfer or deletion.","anyOf":[{"$ref":"#/components/schemas/StudioExport"},{"type":"null"}]},"error":{"description":"Per-section availability error, or null when the child is available. Unavailable children report STUDIO_PROJECT_EXPORT_SECTION_UNAVAILABLE and count as aggregate failure.","anyOf":[{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string"}}},{"type":"null"}]}}}},"archive":{"type":"null","description":"No combined archive or ZIP is produced. Download child artifacts individually."}}},"StudioProjectExportsPayload":{"type":"object","additionalProperties":false,"required":["schema_version","exports","next_cursor"],"properties":{"schema_version":{"type":"integer","const":1},"exports":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/StudioProjectExportPayload"}},"next_cursor":{"description":"Next integer offset encoded as a string, or null at the end. Pass it as cursor with the same format filter.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]}}},"StudioProjectExportFreshnessPayload":{"type":"object","additionalProperties":false,"required":["schema_version","project_id","format","basis","sections"],"properties":{"schema_version":{"type":"integer","const":1},"project_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"format":{"$ref":"#/components/schemas/StudioExportFormat"},"basis":{"type":"string","const":"document_cast_mastering_versions","description":"Saved version comparison only; not take freshness, artifact validity, or successful completion."},"sections":{"type":"array","maxItems":100,"description":"Active sections in project order; deleted sections are omitted. Projects exceeding 100 active sections return 400.","items":{"type":"object","additionalProperties":false,"required":["section_id","title","document_version","speaker_registry_version","mastering_version","latest_export","matches_current_authority"],"properties":{"section_id":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"title":{"type":"string","maxLength":500},"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"latest_export":{"description":"Latest section export for the requested format, regardless of status; null if none exists.","anyOf":[{"$ref":"#/components/schemas/StudioExport"},{"type":"null"}]},"matches_current_authority":{"description":"Whether the latest export's document, cast, and mastering versions match. Null without an export. true does not guarantee latest takes, completion, timeline completeness, or a valid artifact.","anyOf":[{"type":"boolean"},{"type":"null"}]}}}}}},"StudioExportsPayload":{"type":"object","required":["schema_version","exports","next_cursor"],"properties":{"schema_version":{"const":1},"exports":{"type":"array","items":{"$ref":"#/components/schemas/StudioExport"}},"next_cursor":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"additionalProperties":false},"StudioExport":{"type":"object","required":["schema_version","id","project_id","section_id","format","status","phase","percent","cache_result","authority","created_at","started_at","completed_at","error","artifact"],"properties":{"schema_version":{"const":1},"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"format":{"$ref":"#/components/schemas/StudioExportFormat"},"status":{"$ref":"#/components/schemas/StudioExportStatus"},"phase":{"$ref":"#/components/schemas/StudioExportPhase"},"percent":{"type":"integer","minimum":0,"maximum":100},"cache_result":{"type":"string","enum":["miss","reused","coalesced"]},"authority":{"type":"object","required":["document_version","speaker_registry_version","mastering_version","is_current"],"properties":{"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"is_current":{"type":"boolean"}},"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false},{"type":"null"}]},"artifact":{"anyOf":[{"$ref":"#/components/schemas/StudioExportArtifact"},{"type":"null"}]}},"additionalProperties":false},"StudioExportTimelinePayload":{"type":"object","additionalProperties":false,"required":["schema_version","export_id","project_id","section_id","manifest","source_authority","duration_ms","completeness","timing_basis","blocks"],"properties":{"schema_version":{"type":"integer","const":1},"export_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"manifest":{"$ref":"#/components/schemas/StudioExportManifestIdentity"},"source_authority":{"type":"object","additionalProperties":false,"required":["document_version","speaker_registry_version","mastering_version"],"properties":{"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991}}},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"completeness":{"type":"string","enum":["partial","complete"]},"timing_basis":{"type":"string","const":"media_and_intra_block_silence_excluding_inter_block_spacing"},"blocks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["block_id","block_index","media_kind","start_ms","duration_ms"],"properties":{"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Zero-based position in the export's captured document block order, including non-speech blocks."},"media_kind":{"type":"string","enum":["speech","narration","sfx"]},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Block span including internal authored silence but excluding inter-block spacing; SFX spans its overlay."}}}}}},"StudioExportTimelinePayloadV2":{"type":"object","additionalProperties":false,"required":["schema_version","export_id","project_id","section_id","manifest","source_authority","duration_ms","completeness","timing_basis","blocks","unit_word_timings"],"properties":{"schema_version":{"type":"integer","const":2},"export_id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"manifest":{"$ref":"#/components/schemas/StudioExportManifestIdentity"},"source_authority":{"type":"object","additionalProperties":false,"required":["document_version","speaker_registry_version","mastering_version"],"properties":{"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991}}},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"completeness":{"type":"string","enum":["partial","complete"]},"timing_basis":{"type":"string","const":"media_and_intra_block_silence_excluding_inter_block_spacing"},"blocks":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["block_id","block_index","media_kind","start_ms","duration_ms"],"properties":{"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Zero-based position in the export's captured document block order, including non-speech blocks."},"media_kind":{"type":"string","enum":["speech","narration","sfx"]},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Block span including internal authored silence but excluding inter-block spacing; SFX spans its overlay."}}}},"unit_word_timings":{"type":"array","maxItems":60000,"items":{"$ref":"#/components/schemas/StudioUnitWordTimings"}}},"description":"Opt-in export-bound timeline with word timing sidecars from the exact source assets in its immutable stored manifest, never current retakes."},"StudioSectionSharePayload":{"type":"object","required":["schema_version","section_id","is_public","share"],"properties":{"schema_version":{"type":"integer","const":1},"section_id":{"type":"string","format":"uuid"},"is_public":{"type":"boolean"},"share":{"anyOf":[{"$ref":"#/components/schemas/StudioSectionShareLink"},{"type":"null"}],"description":"Active link; non-null exactly when is_public is true."}},"additionalProperties":false,"description":"Section public-sharing state.","allOf":[{"if":{"properties":{"is_public":{"const":true}}},"then":{"properties":{"share":{"type":"object"}}},"else":{"properties":{"share":{"type":"null"}}}}]},"StudioShareSource":{"type":"string","enum":["toolbar","playback_menu","library","completion_prompt"],"description":"Studio surface the owner shared from."},"StudioProjectSharePayload":{"type":"object","required":["schema_version","project_id","is_public","share"],"properties":{"schema_version":{"type":"integer","const":1},"project_id":{"type":"string","format":"uuid"},"is_public":{"type":"boolean"},"share":{"anyOf":[{"$ref":"#/components/schemas/StudioProjectShareLink"},{"type":"null"}],"description":"Active link; non-null exactly when is_public is true."}},"additionalProperties":false,"description":"Project public-link state.","allOf":[{"if":{"properties":{"is_public":{"const":true}}},"then":{"properties":{"share":{"type":"object"}}},"else":{"properties":{"share":{"type":"null"}}}}]},"StudioSoundListPayload":{"type":"object","required":["schema_version","sounds","next_cursor"],"properties":{"schema_version":{"type":"string","const":"studio-sound-library-1"},"sounds":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/StudioSoundEffect"}},"next_cursor":{"type":["string","null"],"minLength":1,"maxLength":500}},"additionalProperties":false},"StudioSoundFile":{"type":"object","description":"Upload files up to 268435456 bytes (256 MiB) and 3900000 ms (65 minutes). Duration is verified from decoded audio during processing, not trusted from a client declaration. The sanitized revision reports its verified duration_ms.","required":["filename","content_type","size_bytes"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":255},"content_type":{"type":"string","enum":["audio/wav","audio/x-wav","audio/mpeg","audio/ogg","audio/opus","audio/flac","audio/mp4","audio/aac","audio/webm"]},"size_bytes":{"type":"integer","minimum":1,"maximum":268435456}},"additionalProperties":false},"StudioSoundUploadPayload":{"type":"object","required":["schema_version","sound","upload"],"properties":{"schema_version":{"type":"string","const":"studio-sound-upload-1"},"sound":{"$ref":"#/components/schemas/StudioSoundEffect"},"upload":{"$ref":"#/components/schemas/StudioSoundUploadSession"}},"additionalProperties":false},"StudioSoundEffect":{"type":"object","required":["id","name","description","tags","status","is_public","owner_display_name","is_owned_by_user","is_shared_with_user","incoming_share","is_in_project","can_edit","can_delete","can_share","metadata_version","current_revision","error","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":1000},"tags":{"type":"array","minItems":1,"maxItems":12,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":40}},"status":{"type":"string","enum":["uploading","processing","ready","failed"]},"is_public":{"type":"boolean"},"owner_display_name":{"type":["string","null"],"minLength":1,"maxLength":200},"is_owned_by_user":{"type":"boolean"},"is_shared_with_user":{"type":"boolean"},"incoming_share":{"$ref":"#/components/schemas/StudioSoundIncomingShare"},"is_in_project":{"type":"boolean"},"can_edit":{"type":"boolean"},"can_delete":{"type":"boolean"},"can_share":{"type":"boolean"},"metadata_version":{"type":"integer","minimum":1},"current_revision":{"oneOf":[{"$ref":"#/components/schemas/StudioSoundRevision"},{"type":"null"}]},"error":{"$ref":"#/components/schemas/StudioSoundError"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioSoundDeletePayload":{"type":"object","required":["sound_effect_id","deleted"],"properties":{"sound_effect_id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean","const":true}},"additionalProperties":false},"StudioSoundPreviewPayload":{"type":"object","required":["schema_version","url","expires_at"],"properties":{"schema_version":{"type":"string","const":"studio-sound-preview-1"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioProjectSoundListPayload":{"type":"object","required":["schema_version","sounds","next_cursor","sound_source_registry_version"],"properties":{"schema_version":{"type":"string","const":"studio-sound-library-1"},"sounds":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/StudioSoundEffect"}},"next_cursor":{"type":["string","null"],"minLength":1,"maxLength":500},"sound_source_registry_version":{"type":"integer","minimum":1}},"additionalProperties":false},"StudioProjectSoundMutationPayload":{"type":"object","required":["schema_version","project_id","sound_effect_id","linked","sound_source_registry_version"],"properties":{"schema_version":{"type":"string","const":"studio-project-sound-source-1"},"project_id":{"type":"string","format":"uuid"},"sound_effect_id":{"type":"string","format":"uuid"},"linked":{"type":"boolean"},"sound_source_registry_version":{"type":"integer","minimum":1}},"additionalProperties":false},"PublicSoundListPayload":{"type":"object","required":["schema_version","sounds","total"],"properties":{"schema_version":{"type":"string","const":"public-sound-catalog-1"},"sounds":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/PublicSound"}},"total":{"type":"integer","minimum":0}},"additionalProperties":false},"Pagination":{"type":"object","required":["next_cursor"],"properties":{"next_cursor":{"type":["string","null"]}}},"PublicSound":{"type":"object","required":["id","name","description","tags","category","duration_ms","page_url","preview","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"type":"string","minLength":1,"maxLength":1000},"tags":{"type":"array","minItems":1,"maxItems":12,"items":{"type":"string","minLength":1,"maxLength":40}},"category":{"type":"string","description":"Catalog slug derived from the first tag."},"duration_ms":{"type":"integer","minimum":100,"maximum":3900000},"page_url":{"type":"string","format":"uri"},"preview":{"type":"object","required":["url","expires_at"],"properties":{"url":{"type":"string","format":"uri","description":"Signed-out WAV preview that supports HTTP Range requests."},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"FeedbackSubmitEnvelope":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/FeedbackSubmitResult"},"request_id":{"type":"string"}},"additionalProperties":false},"ApiError":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"retry_after_ms":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Optional minimum retry delay in milliseconds. Only retry when retryable is true and preserve the original idempotency key. A generic delay is a backoff hint, not an estimate of recovery."},"details":{"type":"object","additionalProperties":true}}},"HealthPayload":{"type":"object","required":["ok","service","version"],"properties":{"ok":{"type":"boolean","const":true},"service":{"type":"string","const":"lyricwinter"},"version":{"type":"string","const":"v1"}},"additionalProperties":false},"AccountProfilePayload":{"type":"object","required":["profile"],"properties":{"profile":{"$ref":"#/components/schemas/AccountProfile"}},"additionalProperties":false},"AccountBalancePayload":{"type":"object","required":["balance"],"properties":{"balance":{"$ref":"#/components/schemas/AccountBalance"}},"additionalProperties":false},"StudioCampaignDialog":{"type":"object","required":["campaign_key","campaign_kind","priority","content_revision","interaction","title","body","primary_action_label","secondary_action_label","learn_more_url","available_until","rewards"],"properties":{"campaign_key":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{2,63}$"},"campaign_kind":{"type":"string","enum":["promotion","customer_referral","affiliate","announcement","product_update"]},"priority":{"type":"integer","minimum":-1000,"maximum":1000},"content_revision":{"type":"integer","minimum":1},"interaction":{"type":"string","enum":["claim","acknowledge"]},"title":{"type":"string","minLength":1,"maxLength":120},"body":{"type":"string","minLength":1,"maxLength":1000},"primary_action_label":{"type":"string","minLength":1,"maxLength":80},"secondary_action_label":{"type":["string","null"],"minLength":1,"maxLength":80},"learn_more_url":{"type":["string","null"],"format":"uri","pattern":"^https://"},"available_until":{"type":"string","format":"date-time"},"rewards":{"type":"array","maxItems":20,"items":{"type":"object","required":["reward_key","reward_type","amount_snowcoins","amount_words","expiration_policy","fixed_expires_at","expires_in_seconds"],"properties":{"reward_key":{"type":"string"},"reward_type":{"type":"string","const":"studio_words"},"amount_snowcoins":{"type":"integer","minimum":1},"amount_words":{"type":"integer","minimum":1},"expiration_policy":{"type":"string","enum":["none","fixed","rolling"]},"fixed_expires_at":{"type":["string","null"],"format":"date-time"},"expires_in_seconds":{"type":["integer","null"],"minimum":1}},"additionalProperties":false}}},"additionalProperties":false},"StudioAccountActionCapability":{"type":"object","required":["status","billing_mode"],"properties":{"status":{"type":"string","enum":["available","not_connected"]},"billing_mode":{"type":"string","enum":["included","metered_snowcoins","not_applicable"]}},"additionalProperties":false},"ApiKeyListPayload":{"type":"object","required":["api_keys"],"properties":{"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyMetadata"}}},"additionalProperties":false},"ApiKeyCreatedPayload":{"type":"object","required":["api_key","raw_key"],"properties":{"api_key":{"$ref":"#/components/schemas/ApiKeyMetadata"},"raw_key":{"type":"string","pattern":"^lw_[A-Za-z0-9_-]{8,32}_[A-Za-z0-9_-]+$","description":"Display-once raw API key. The server stores only a SHA-256 hash."}},"additionalProperties":false},"ApiKeyRevokedPayload":{"type":"object","required":["ok","api_key"],"properties":{"ok":{"type":"boolean","const":true},"api_key":{"$ref":"#/components/schemas/ApiKeyMetadata"}},"additionalProperties":false},"StudioProjectSummary":{"type":"object","required":["id","name","project_kind"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"project_kind":{"type":"string","const":"named"}},"additionalProperties":false},"StudioUnassignedSection":{"type":"object","required":["project_id","section"],"properties":{"project_id":{"type":"string","format":"uuid","description":"Hidden standalone project container that owns the story."},"section":{"$ref":"#/components/schemas/StudioSectionSummary"}},"additionalProperties":false},"StudioSectionSummary":{"type":"object","required":["id","project_id","title","document_version","source_text_length","activity_status","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"project_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"source_text_length":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Length of the section's exact source-text projection in UTF-16 code units."},"activity_status":{"type":"string","enum":["blank","working","needs_audio","audio_ready","audio_failed"],"description":"Navigator state: working (active workflow or pending audio), audio_failed (latest audio attempt failed), audio_ready (every generatable block has current audio and no unparsed text remains), needs_audio (generatable or unparsed text without complete current audio), or blank (nothing to generate)."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioSectionDocument":{"additionalProperties":false,"properties":{"blocks":{"items":{"$ref":"#/components/schemas/StudioAstScriptBlock"},"type":"array","maxItems":100000},"different_speaker_gap_ms":{"type":"integer","minimum":0,"maximum":1000,"description":"Silence in milliseconds inserted between adjacent spoken blocks with different speakers."},"document_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"sfx_enabled":{"type":"boolean","description":"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_ms":{"type":"integer","minimum":0,"maximum":1000,"description":"Silence in milliseconds inserted between adjacent spoken blocks with the same speaker."},"schema_version":{"const":"studio-ast-2","type":"string"},"section_id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string","description":"Canonical lowercase UUID of the section."},"speaker_registry_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer","description":"Project-wide speaker registry version the speakers list was read at."},"speakers":{"items":{"$ref":"#/components/schemas/StudioAstSpeaker"},"type":"array","description":"Every active speaker in the project registry, not only speakers referenced by this section."},"title":{"maxLength":500,"type":"string"}},"required":["schema_version","section_id","title","document_version","speaker_registry_version","sfx_enabled","same_speaker_gap_ms","different_speaker_gap_ms","speakers","blocks"],"type":"object","description":"The canonical structured script of one section (studio-ast-2): its versions, speakers, and ordered blocks."},"StudioSourceDraft":{"type":"object","required":["source_text","base_document_version","base_speaker_registry_version","base_speaker_versions","diagnostics","updated_at"],"properties":{"source_text":{"type":"string"},"base_document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"base_speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"base_speaker_versions":{"type":"object","propertyNames":{"format":"uuid"},"additionalProperties":{"type":"integer","minimum":1,"maximum":9007199254740991},"description":"Speaker versions keyed by speaker ID when the draft began."},"diagnostics":{"type":"array","maxItems":1000,"items":{"$ref":"#/components/schemas/StudioSourceDiagnostic"}},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioDocumentCommandUuid":{"type":"string","pattern":"^[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}$"},"StudioAstScriptBlock":{"discriminator":{"propertyName":"kind","mapping":{"excluded":"#/components/schemas/StudioAstExcludedBlock","narration":"#/components/schemas/StudioAstNarrationBlock","note":"#/components/schemas/StudioAstNoteBlock","sfx":"#/components/schemas/StudioAstSfxBlock","speech":"#/components/schemas/StudioAstSpeechBlock","unparsed":"#/components/schemas/StudioAstUnparsedBlock"}},"oneOf":[{"$ref":"#/components/schemas/StudioAstSpeechBlock"},{"$ref":"#/components/schemas/StudioAstNarrationBlock"},{"$ref":"#/components/schemas/StudioAstUnparsedBlock"},{"$ref":"#/components/schemas/StudioAstExcludedBlock"},{"$ref":"#/components/schemas/StudioAstNoteBlock"},{"$ref":"#/components/schemas/StudioAstSfxBlock"}]},"StudioAstSfxContent":{"additionalProperties":false,"allOf":[{"if":{"required":["source"]},"then":{"properties":{"seed":{"type":"null"}}},"else":{"properties":{"duration_ms":{"maximum":300000}}}}],"properties":{"duration_ms":{"description":"Generated sound effects (no source) allow up to 300000 ms; a pinned project sound allows up to 3900000 ms.","maximum":3900000,"minimum":100,"type":"integer"},"prompt":{"maxLength":4000,"minLength":1,"type":"string"},"schema_version":{"const":"studio-ast-2","type":"string"},"seed":{"anyOf":[{"maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"},{"type":"null"}]},"type":{"const":"sfx","type":"string"},"source":{"$ref":"#/components/schemas/StudioAstProjectSoundSource","description":"Present only when the SFX block plays an uploaded project sound; seed is then null."}},"required":["schema_version","type","prompt","duration_ms","seed"],"type":"object"},"StudioAstSfxPlacement":{"additionalProperties":false,"properties":{"anchor":{"$ref":"#/components/schemas/StudioAstSfxAnchor"},"fade_in_ms":{"maximum":300000,"minimum":0,"type":"integer"},"fade_out_ms":{"maximum":300000,"minimum":0,"type":"integer"},"gain_db":{"maximum":24,"minimum":-60,"type":"number"},"offset_ms":{"maximum":300000,"minimum":-300000,"type":"integer"}},"required":["anchor","offset_ms","gain_db","fade_in_ms","fade_out_ms"],"type":"object"},"StudioDocumentSplitBlockTarget":{"type":"object","required":["block_id","split_offsets_utf16","new_block_ids","annotation_fragment_ids"],"properties":{"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"split_offsets_utf16":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991},"minItems":1,"maxItems":2},"new_block_ids":{"type":"array","items":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"minItems":1,"maxItems":2},"annotation_fragment_ids":{"type":"object","propertyNames":{"pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"},"additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"minItems":1,"maxItems":2}}},"additionalProperties":false,"description":"Each target has 1-2 strictly increasing positive UTF-16 offsets; new_block_ids length equals split_offsets_utf16 length. Targets and allocated IDs must be unique across the command."},"StudioAstTextAnnotation":{"discriminator":{"propertyName":"kind","mapping":{"exclusion":"#/components/schemas/StudioAstExclusionAnnotation","extension":"#/components/schemas/StudioAstExtensionAnnotation","pronunciation":"#/components/schemas/StudioAstPronunciationAnnotation"}},"oneOf":[{"$ref":"#/components/schemas/StudioAstExclusionAnnotation"},{"$ref":"#/components/schemas/StudioAstPronunciationAnnotation"},{"$ref":"#/components/schemas/StudioAstExtensionAnnotation"}]},"StudioAstPointNode":{"discriminator":{"propertyName":"kind","mapping":{"extension":"#/components/schemas/StudioAstExtensionPoint","timed_silence":"#/components/schemas/StudioAstTimedSilencePoint"}},"oneOf":[{"$ref":"#/components/schemas/StudioAstTimedSilencePoint"},{"$ref":"#/components/schemas/StudioAstExtensionPoint"}]},"StudioAstDeliveryControlSet":{"additionalProperties":false,"allOf":[{"if":{"required":["provider_text_override"]},"then":{"properties":{"format":{"const":"inworld-tts2-1"},"model":{"const":"inworld-2"},"provider":{"const":"inworld"},"schema_version":{"const":"studio-delivery-control-set-2"},"source_fingerprint":{"pattern":"^[0-9a-f]{64}$","type":"string"},"source_utf16_length":{"maximum":9007199254740991,"minimum":0,"type":"integer"}}}}],"properties":{"capability_revision":{"maxLength":200,"minLength":1,"type":"string"},"directives":{"items":{"$ref":"#/components/schemas/StudioAstDeliveryDirective"},"maxItems":256,"type":"array"},"format":{"enum":["eleven-v4-1","inworld-tts2-1","inworld-tts2-experimental-1","inworld-tts15-max-1","inworld-tts15-mini-1","fish-s2-inline-1","fish-s2.1-inline-1","fish-drama-3-inline-1","cartesia-sonic36-1","cartesia-sonic35-1","openai-gpt4o-mini-tts-1","openai-tts1-hd-1","openai-tts1-1","smallest-lightning31-1","chatterbox-classic-1","zyphra-zonos2-cloud-1","f5tts-v1-1","misotts-8b-1"],"type":"string"},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"model":{"maxLength":200,"minLength":1,"type":"string"},"provider":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"provider_text_override":{"maxLength":65536,"minLength":1,"pattern":"[\\s\\S]*\\S[\\s\\S]*","type":"string"},"schema_version":{"enum":["studio-delivery-control-set-1","studio-delivery-control-set-2"],"type":"string"},"settings":{"items":{"$ref":"#/components/schemas/StudioAstDeliverySetting"},"maxItems":32,"type":"array"},"source_fingerprint":{"anyOf":[{"pattern":"^[0-9a-f]{64}$","type":"string"},{"type":"null"}]},"source_utf16_length":{"anyOf":[{"maximum":9007199254740991,"minimum":0,"type":"integer"},{"type":"null"}]}},"required":["id","schema_version","provider","model","format","capability_revision","source_fingerprint","source_utf16_length","settings","directives"],"type":"object","description":"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."},"StudioDocumentAttributionTarget":{"type":"object","required":["block_id","block_kind","speaker_id"],"properties":{"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"block_kind":{"type":"string","enum":["speech","narration","unparsed","excluded"]},"speaker_id":{"anyOf":[{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},{"type":"null"}]}},"additionalProperties":false,"description":"Unparsed and excluded blocks cannot have a speaker.","allOf":[{"if":{"properties":{"block_kind":{"enum":["unparsed","excluded"]}},"required":["block_kind"]},"then":{"properties":{"speaker_id":{"type":"null"}}}}]},"StudioDocumentSpeakerRequest":{"description":"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.","allOf":[{"$ref":"#/components/schemas/StudioAstSpeaker"},{"type":"object","properties":{"generation_profile":{"anyOf":[{"$ref":"#/components/schemas/StudioGenerationProfileRequest"},{"type":"null"}]}}}]},"StudioDocumentProfileTarget":{"type":"object","required":["block_id","generation_profile_override"],"properties":{"block_id":{"$ref":"#/components/schemas/StudioDocumentCommandUuid"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]}},"additionalProperties":false},"StudioDocumentSourceDocumentRequest":{"description":"A replacement source document written by a command. Speaker profiles use the strict new-write request contract.","allOf":[{"$ref":"#/components/schemas/StudioSectionDocument"},{"type":"object","properties":{"speakers":{"type":"array","items":{"$ref":"#/components/schemas/StudioDocumentSpeakerRequest"}}}}]},"StudioProfileElevenLabsOptions":{"type":"object","additionalProperties":false,"description":"Connected ElevenLabs v4 dialogue controls. Seed is best-effort, not guaranteed deterministic. Empty options retain provider defaults. Speed is unsupported on v4; similarity_boost is not exposed by this transport.","properties":{"stability":{"type":"number","minimum":0,"maximum":1},"seed":{"type":"integer","minimum":1,"maximum":4294967295}}},"StudioProfileInworld2Options":{"type":"object","additionalProperties":false,"properties":{"apply_text_normalization":{"enum":["APPLY_TEXT_NORMALIZATION_UNSPECIFIED","ON","OFF"]}}},"StudioProfileInworld15Options":{"type":"object","additionalProperties":false,"properties":{"speaking_rate":{"type":"number","minimum":0.5,"maximum":1.5},"temperature":{"type":"number","exclusiveMinimum":0,"maximum":2},"apply_text_normalization":{"enum":["APPLY_TEXT_NORMALIZATION_UNSPECIFIED","ON","OFF"]}}},"StudioProfileCartesiaOptions":{"type":"object","additionalProperties":false,"properties":{"speed":{"type":"number","minimum":0.6,"maximum":1.5},"volume":{"type":"number","minimum":0.5,"maximum":2}}},"StudioProfileFishOptions":{"type":"object","additionalProperties":false,"properties":{"temperature":{"type":"number","minimum":0,"maximum":1},"top_p":{"type":"number","minimum":0,"maximum":1},"latency":{"enum":["low","normal","balanced"]},"chunk_length":{"type":"integer","minimum":100,"maximum":300},"normalize":{"type":"boolean"},"condition_on_previous_chunks":{"type":"boolean"}}},"StudioProfileEmptyOptions":{"description":"No provider options for this model.","type":"object","additionalProperties":false,"properties":{}},"StudioProfileStableAudioOptions":{"type":"object","additionalProperties":false,"properties":{"steps":{"type":"integer","minimum":1,"maximum":50}}},"StudioProfileCatalogOnlyProfile":{"description":"Catalog-only compatibility profile. Options are retained as JSON without asserting supported controls; these four models have no current connected Studio speech compiler. Generation availability is checked separately and remains unavailable.","oneOf":[{"properties":{"provider":{"const":"inworld"},"model":{"const":"inworld-2-experimental"},"options":{"type":"object","additionalProperties":true}}},{"properties":{"provider":{"const":"chatterbox_fal"},"model":{"const":"chatterbox_fal"},"options":{"type":"object","additionalProperties":true}}},{"properties":{"provider":{"const":"zyphra"},"model":{"const":"zyphra"},"options":{"type":"object","additionalProperties":true}}},{"properties":{"provider":{"const":"misotts"},"model":{"const":"misotts"},"options":{"type":"object","additionalProperties":true}}}]},"StudioSpeakerUsage":{"type":"object","required":["speaker_id","line_count","block_override_count","section_count"],"properties":{"speaker_id":{"type":"string","format":"uuid"},"line_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Active speech and narration blocks assigned to the speaker across active sections."},"block_override_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Of those blocks, how many carry a block-level generation profile override."},"section_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Active sections containing at least one of those blocks."}},"additionalProperties":false},"StudioProjectSpeakerCastingMutation":{"type":"object","additionalProperties":false,"required":["mutation_id","reverted_mutation_id","project_id","speaker_id","speaker_registry_version","speaker_version","affected_block_count","affected_section_count","idempotent_replay"],"properties":{"mutation_id":{"type":"string","format":"uuid"},"reverted_mutation_id":{"type":["string","null"],"format":"uuid"},"project_id":{"type":"string","format":"uuid"},"speaker_id":{"type":"string","format":"uuid"},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"affected_block_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"affected_section_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"idempotent_replay":{"type":"boolean"}}},"StudioWorkflowRun":{"type":"object","required":["id","project_id","requested_by_user_id","payer_user_id","workflow_kind","automation_profile","profile_snapshot","status","current_stage","step_count","completed_step_count","progress","error_summary","cancel_requested_at","cancel_acknowledged_at","created_at","updated_at","started_at","completed_at","resumes_workflow_run_id","resumable"],"properties":{"id":{"type":"string","format":"uuid","description":"Workflow run ID."},"project_id":{"type":"string","format":"uuid"},"requested_by_user_id":{"type":"string","format":"uuid"},"payer_user_id":{"type":["string","null"],"format":"uuid","description":"User billed for Create Audio work; null for prepare_sections workflows."},"workflow_kind":{"type":"string","enum":["prepare_sections","create_audio"]},"automation_profile":{"type":["string","null"],"enum":["quick","balanced","directed",null],"description":"Create Audio profile label from profile_snapshot.profile; null for prepare_sections."},"profile_snapshot":{"description":"Empty object for prepare_sections workflows; the frozen Create Audio options for create_audio workflows.","oneOf":[{"type":"object","maxProperties":0},{"$ref":"#/components/schemas/StudioWorkflowCreateAudioProfileSnapshot"}]},"status":{"$ref":"#/components/schemas/StudioWorkflowRunStatus"},"current_stage":{"anyOf":[{"$ref":"#/components/schemas/StudioWorkflowStage"},{"type":"null"}],"description":"Stage of the next unfinished step while the run is queued, running, or canceling. Null once the run is terminal, or when the next unfinished step is render_section."},"step_count":{"type":"integer","minimum":1,"maximum":100},"completed_step_count":{"type":"integer","minimum":0,"maximum":100,"description":"Steps in a terminal status (succeeded, skipped, failed, conflict, cancelled)."},"progress":{"type":"object","description":"Step counts by status. Currently contains integer counts pending, active, succeeded (succeeded or skipped), failed (failed or conflict), cancelled, completed (all terminal), and total; treat unknown keys as additive.","properties":{"pending":{"type":"integer","minimum":0,"maximum":9007199254740991},"active":{"type":"integer","minimum":0,"maximum":9007199254740991},"succeeded":{"type":"integer","minimum":0,"maximum":9007199254740991},"failed":{"type":"integer","minimum":0,"maximum":9007199254740991},"cancelled":{"type":"integer","minimum":0,"maximum":9007199254740991},"completed":{"type":"integer","minimum":0,"maximum":9007199254740991},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":true},"error_summary":{"type":"array","maxItems":100,"description":"One entry per failed or conflict step in step order. Entries currently contain step_id, section_id, step_kind, code, and message; treat unknown keys as additive.","items":{"type":"object","properties":{"step_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"step_kind":{"$ref":"#/components/schemas/StudioWorkflowStepKind"},"code":{"type":["string","null"]},"message":{"type":["string","null"]}},"additionalProperties":true}},"cancel_requested_at":{"type":["string","null"],"format":"date-time","description":"When cancellation was first requested."},"cancel_acknowledged_at":{"type":["string","null"],"format":"date-time","description":"When the run reached cancelled."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time","description":"When execution first started; null before then."},"completed_at":{"type":["string","null"],"format":"date-time","description":"Set when the run reaches a terminal status (completed, partially_completed, failed, cancelled); null otherwise."},"resumes_workflow_run_id":{"type":["string","null"],"format":"uuid","description":"Predecessor run this run resumes; null for an original run."},"resumable":{"type":"boolean","description":"True when status is failed or partially_completed and at least one step is failed or conflict. Only resumable runs can be resumed."}},"additionalProperties":false,"description":"Durable Studio project workflow run."},"StudioWorkflowStep":{"type":"object","required":["id","workflow_run_id","section_id","step_key","step_index","step_kind","status","requested_document_version","execution_document_version","assistant_batch_id","render_run_id","result_summary","issue_kind","error_code","error_message","created_at","updated_at","started_at","completed_at"],"properties":{"id":{"type":"string","format":"uuid"},"workflow_run_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"step_key":{"type":"string","minLength":1,"maxLength":200,"description":"Stable key of the step within its workflow."},"step_index":{"type":"integer","minimum":0,"maximum":99,"description":"Zero-based position; steps are returned in ascending step_index order."},"step_kind":{"$ref":"#/components/schemas/StudioWorkflowStepKind"},"status":{"$ref":"#/components/schemas/StudioWorkflowStepStatus"},"requested_document_version":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"Section document version the step was planned against."},"execution_document_version":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Section document version the step executed against, when recorded."},"assistant_batch_id":{"type":["string","null"],"format":"uuid","description":"Child assistant batch started by an assistant-driven step."},"render_run_id":{"type":["string","null"],"format":"uuid","description":"Render run started by a render_section step."},"result_summary":{"type":"object","additionalProperties":true,"description":"Step-specific result data, typed by the contract as an open JSON object. generate_stale_audio steps may carry the StudioWorkflowAudioResultSummary fields; steps cancelled before starting carry cancelled_before_start: true."},"issue_kind":{"anyOf":[{"$ref":"#/components/schemas/StudioWorkflowIssueKind"},{"type":"null"}],"description":"Set for failed and conflict steps; null for every other status."},"error_code":{"type":["string","null"],"minLength":1,"maxLength":200},"error_message":{"type":["string","null"],"maxLength":10000},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false,"description":"One ordered unit of workflow work for one section."},"StudioWorkflowIndexedAudioIssue":{"type":"object","required":["block_id","block_number","block_kind","speaker_name","reason","recovery","section_id","block_index"],"properties":{"block_id":{"type":"string","format":"uuid"},"block_number":{"type":"integer","minimum":1,"maximum":50000},"block_kind":{"type":"string","enum":["speech","narration","sfx","unparsed","excluded"]},"speaker_name":{"type":["string","null"],"minLength":1,"maxLength":200},"reason":{"type":"string","minLength":1,"maxLength":1000},"recovery":{"type":"string","minLength":1,"maxLength":1000},"section_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":49999,"description":"Zero-based position in the full document order captured when the issue was recorded. Join current resources using block_id, not an index after edits."}},"additionalProperties":false,"description":"A block that audio generation could not complete, with a recovery hint."},"StudioSectionMediaBlock":{"allOf":[{"$ref":"#/components/schemas/StudioSectionMediaBlockFields"}],"unevaluatedProperties":false},"StudioSectionMediaBlockV2":{"allOf":[{"$ref":"#/components/schemas/StudioSectionMediaBlockFields"},{"type":"object","required":["boundary_silence_handling"],"properties":{"boundary_silence_handling":{"$ref":"#/components/schemas/StudioBoundarySilenceHandling"}}}],"unevaluatedProperties":false},"StudioGenerationAvailability":{"type":"object","additionalProperties":false,"required":["requested_profile","status","reason","diagnostics","options"],"description":"Whether generation can be requested under current voice/compiler authority, including confirmed ElevenLabs voice-preparation exhaustion for uncached voices. Available does not mean audio exists; check /media freshness, activity, and playback_url. This is not a general provider synthesis quota or billing check.","properties":{"requested_profile":{"$ref":"#/components/schemas/StudioGenerationProfile"},"status":{"type":"string","enum":["available","materialization_required","unavailable"]},"reason":{"type":["string","null"]},"reason_code":{"type":"string","enum":["provider_asset_missing","acoustic_revision_changed"]},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/StudioGenerationAvailabilityDiagnostic"}},"options":{"type":"array","items":{"$ref":"#/components/schemas/StudioProviderAvailabilityOption"}}}},"StudioPlaybackRenderManifest":{"type":"object","required":["schema_version","project_id","section_id","document_version","speaker_registry_version","mastering_version","mastering_profile_hash","mastering_profile","completeness","duration_ms","sequential_units","overlay_units","timed_text_units","gaps"],"properties":{"schema_version":{"type":"string","const":"studio-render-manifest-2"},"project_id":{"type":"string","format":"uuid"},"section_id":{"type":"string","format":"uuid"},"document_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_registry_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"mastering_profile_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"mastering_profile":{"$ref":"#/components/schemas/StudioMasteringProfile"},"completeness":{"type":"string","enum":["partial","complete"],"description":"complete exactly when gaps is empty."},"duration_ms":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Latest end point of any sequential or overlay unit."},"sequential_units":{"type":"array","maxItems":50000,"items":{"$ref":"#/components/schemas/StudioPlaybackSequentialUnit"},"description":"Contiguous from 0 ms in canonical block order; unit IDs are unique across sequential and overlay units."},"overlay_units":{"type":"array","maxItems":10000,"items":{"$ref":"#/components/schemas/StudioPlaybackOverlayUnit"},"description":"Ordered by start_ms, block_index, block_id, unit_id."},"timed_text_units":{"type":"array","maxItems":50000,"items":{"$ref":"#/components/schemas/StudioPlaybackTimedTextUnit"},"description":"Ordered by start_ms, block_index, block_id, unit_id."},"gaps":{"type":"array","maxItems":50000,"items":{"$ref":"#/components/schemas/StudioPlaybackGap"},"description":"Ordered by block_index, media_kind, block_id."}},"additionalProperties":false,"description":"Compiled playback timeline for one saved section document and speaker-registry version.","allOf":[{"if":{"properties":{"completeness":{"const":"complete"}}},"then":{"properties":{"gaps":{"maxItems":0}}},"else":{"properties":{"gaps":{"minItems":1}}}}]},"StudioPlaybackAsset":{"type":"object","required":["asset_id","url","expires_at","content_type","size_bytes"],"properties":{"asset_id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Short-lived signed inline URL."},"expires_at":{"type":"string","format":"date-time"},"content_type":{"type":"string","minLength":1},"size_bytes":{"type":"integer","minimum":1,"maximum":9007199254740991}},"additionalProperties":false,"description":"Signed delivery URL for one project-owned media asset."},"StudioUnitWordTimings":{"oneOf":[{"type":"object","additionalProperties":false,"required":["unit_id","block_id","asset_id","word_timing","words"],"properties":{"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"word_timing":{"const":"provider"},"words":{"type":"array","minItems":1,"maxItems":10000,"items":{"$ref":"#/components/schemas/StudioWordTiming"}}}},{"type":"object","additionalProperties":false,"required":["unit_id","block_id","asset_id","word_timing"],"properties":{"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"asset_id":{"type":"string","format":"uuid"},"word_timing":{"const":"unavailable"}}}],"description":"Joins the unchanged audio manifest by unit_id. Provider timing is present only for validated alignment tied to the referenced immutable asset and its content hash; absent, invalid, unsupported, or payload-budget-exceeded alignment is unavailable."},"StudioMasteringProfile":{"type":"object","required":["schema_version","enabled","target_lufs","strength","max_boost_db","max_reduction_db","silence_threshold_lufs","peak_ceiling_db","speaker_adjustments_db","sfx_bus_gain_db"],"properties":{"schema_version":{"const":1},"enabled":{"type":"boolean"},"target_lufs":{"type":"number","minimum":-30,"maximum":-10},"strength":{"type":"number","minimum":0,"maximum":1},"max_boost_db":{"type":"number","minimum":0,"maximum":24},"max_reduction_db":{"type":"number","minimum":0,"maximum":24},"silence_threshold_lufs":{"type":"number","minimum":-120,"maximum":-20},"peak_ceiling_db":{"type":"number","minimum":-12,"maximum":-0.1},"speaker_adjustments_db":{"type":"object","maxProperties":500,"propertyNames":{"format":"uuid"},"additionalProperties":{"type":"number","minimum":-24,"maximum":24}},"sfx_bus_gain_db":{"type":"number","minimum":-24,"maximum":24,"default":0}},"additionalProperties":false},"StudioExportPhase":{"type":"string","enum":["queued","compiling","claiming_artifact","downloading","mixing","encoding","packaging","uploading","complete","failed","cancelled"]},"StudioExportArtifact":{"type":"object","required":["asset_id","filename","content_type","size_bytes","download_url","download_url_expires_at","artifact_expires_at"],"properties":{"asset_id":{"type":"string","format":"uuid"},"filename":{"type":"string","minLength":1,"maxLength":255},"content_type":{"type":"string","minLength":1},"size_bytes":{"type":"integer","minimum":1},"download_url":{"type":"string","format":"uri"},"download_url_expires_at":{"type":"string","format":"date-time"},"artifact_expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioExportManifestIdentity":{"type":"object","additionalProperties":false,"required":["id","hash","schema_version"],"properties":{"id":{"type":"string","format":"uuid"},"hash":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Content hash of the exact immutable render manifest used by the export."},"schema_version":{"type":"string","enum":["studio-render-manifest-1","studio-render-manifest-2"]}}},"StudioSectionShareLink":{"type":"object","required":["id","url","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Public section page URL of the form <origin>/s/<token>."},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false,"description":"Active revocable public link for a section."},"StudioProjectShareLink":{"type":"object","required":["id","url","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","description":"Public project page URL of the form <origin>/p/<token>."},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false,"description":"Active revocable public link for a project."},"StudioSoundUploadSession":{"type":"object","required":["id","url","method","headers","expires_at"],"properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"method":{"type":"string","const":"PUT"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioSoundIncomingShare":{"type":["object","null"],"required":["id","status"],"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","accepted","declined"]}},"additionalProperties":false},"StudioSoundRevision":{"type":"object","required":["id","revision_number","duration_ms","mime_type","file_size_bytes","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"revision_number":{"type":"integer","minimum":1},"duration_ms":{"type":"integer","minimum":100,"maximum":3900000},"mime_type":{"type":"string","minLength":1,"maxLength":200},"file_size_bytes":{"type":"integer","minimum":1,"maximum":754974720},"created_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioSoundError":{"type":["object","null"],"required":["code","message"],"properties":{"code":{"type":["string","null"],"maxLength":200},"message":{"type":"string","minLength":1,"maxLength":1000}},"additionalProperties":false},"FeedbackSubmitResult":{"type":"object","required":["success","message","id"],"properties":{"success":{"type":"boolean","const":true},"message":{"type":"string"},"id":{"type":"string","description":"Inserted feedback row id."}},"additionalProperties":false},"AccountProfile":{"type":"object","required":["id","username","name","image","email"],"properties":{"id":{"type":"string"},"username":{"type":["string","null"],"minLength":3,"maxLength":30},"name":{"type":["string","null"],"maxLength":100},"image":{"type":["string","null"],"format":"uri"},"email":{"type":["string","null"],"format":"email"}},"additionalProperties":false},"AccountBalance":{"type":"object","required":["snowcoins","available_snowcoins","billing_debt","subscription_tier","subscription_provider","subscription_status","has_active_subscription","parse_limit_characters","unlimited_f5_tts","auto_reload_enabled","auto_reload_threshold","small_word_packs_eligible","small_word_pack_eligibility"],"properties":{"snowcoins":{"type":["integer","null"],"minimum":0,"description":"Current settled account Snowcoins."},"available_snowcoins":{"type":["integer","null"],"minimum":0,"description":"Current spendable account Snowcoins after active holds."},"billing_debt":{"type":"integer","minimum":0},"subscription_tier":{"type":"string","enum":["zerowinter","mywinter","ultrawinter","hyperwinter"]},"subscription_provider":{"type":["string","null"],"enum":["stripe","app_store",null]},"subscription_status":{"type":"string","enum":["free","active","grace_period","billing_retry","expired","revoked"]},"has_active_subscription":{"type":"boolean"},"parse_limit_characters":{"type":"integer","minimum":1},"unlimited_f5_tts":{"type":"boolean"},"auto_reload_enabled":{"type":"boolean"},"auto_reload_threshold":{"type":["number","null"]},"small_word_packs_eligible":{"type":"boolean"},"small_word_pack_eligibility":{"type":"object","additionalProperties":false,"required":["canUseSmallWordPacks","activeSubscription","previousSuccessfulPayment","engagedReturningUser","completedAudioRunsLast30Days","accountAgeDays","accountCreatedAt"],"properties":{"canUseSmallWordPacks":{"type":"boolean"},"activeSubscription":{"type":"boolean"},"previousSuccessfulPayment":{"type":"boolean"},"engagedReturningUser":{"type":"boolean"},"completedAudioRunsLast30Days":{"type":"integer","minimum":0},"accountAgeDays":{"type":["integer","null"],"minimum":0},"accountCreatedAt":{"type":["string","null"],"format":"date-time"}}}},"additionalProperties":false},"ApiKeyMetadata":{"type":"object","required":["id","name","token_prefix","scopes","expires_at","last_used_at","revoked_at","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1,"maxLength":80},"token_prefix":{"type":"string","pattern":"^lw_[A-Za-z0-9_-]{8,32}$","description":"Safe display prefix for identifying a key."},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiScope"}},"expires_at":{"type":["string","null"],"format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"additionalProperties":false},"StudioAstSpeaker":{"additionalProperties":false,"properties":{"generation_profile":{"anyOf":[{"$ref":"#/components/schemas/StudioGenerationProfile"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"name":{"maxLength":200,"minLength":1,"type":"string"},"speaker_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"voice_id":{"anyOf":[{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},{"type":"null"}]}},"required":["id","speaker_version","name","voice_id","generation_profile"],"type":"object"},"StudioSourceDiagnostic":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_SOURCE","STALE_SOURCE"]},"message":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"StudioAstSpeechBlock":{"additionalProperties":false,"properties":{"block_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"content":{"$ref":"#/components/schemas/StudioAstTextContent"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"speech","type":"string"},"placement":{"type":"null"},"speaker_id":{"anyOf":[{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},{"type":"null"}]}},"required":["id","block_version","generation_profile_override","kind","speaker_id","content","placement"],"type":"object"},"StudioAstNarrationBlock":{"additionalProperties":false,"properties":{"block_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"content":{"$ref":"#/components/schemas/StudioAstTextContent"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"narration","type":"string"},"placement":{"type":"null"},"speaker_id":{"anyOf":[{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},{"type":"null"}]}},"required":["id","block_version","generation_profile_override","kind","speaker_id","content","placement"],"type":"object"},"StudioAstUnparsedBlock":{"additionalProperties":false,"properties":{"block_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"content":{"$ref":"#/components/schemas/StudioAstTextContent"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"unparsed","type":"string"},"placement":{"type":"null"},"speaker_id":{"type":"null"}},"required":["id","block_version","generation_profile_override","kind","speaker_id","content","placement"],"type":"object"},"StudioAstExcludedBlock":{"additionalProperties":false,"properties":{"block_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"content":{"$ref":"#/components/schemas/StudioAstTextContent"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"excluded","type":"string"},"placement":{"type":"null"},"speaker_id":{"type":"null"}},"required":["id","block_version","generation_profile_override","kind","speaker_id","content","placement"],"type":"object"},"StudioAstNoteBlock":{"additionalProperties":false,"properties":{"block_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"content":{"$ref":"#/components/schemas/StudioAstNoteContent"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"note","type":"string"},"placement":{"type":"null"},"speaker_id":{"type":"null"}},"required":["id","block_version","generation_profile_override","kind","speaker_id","content","placement"],"type":"object"},"StudioAstSfxBlock":{"additionalProperties":false,"properties":{"block_version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"},"content":{"$ref":"#/components/schemas/StudioAstSfxContent"},"generation_profile_override":{"anyOf":[{"$ref":"#/components/schemas/StudioAstGenerationProfileOverride"},{"type":"null"}]},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"sfx","type":"string"},"placement":{"$ref":"#/components/schemas/StudioAstSfxPlacement"},"speaker_id":{"type":"null"}},"required":["id","block_version","generation_profile_override","kind","speaker_id","content","placement"],"type":"object"},"StudioAstProjectSoundSource":{"type":"object","required":["kind","sound_effect_id","sound_effect_revision_id"],"properties":{"kind":{"type":"string","const":"project_sound"},"sound_effect_id":{"type":"string","pattern":"^[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_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"additionalProperties":false},"StudioAstSfxAnchor":{"discriminator":{"propertyName":"kind","mapping":{"block":"#/components/schemas/StudioAstBlockAnchor","section":"#/components/schemas/StudioAstSectionAnchor","unplaced":"#/components/schemas/StudioAstUnplacedAnchor"}},"oneOf":[{"$ref":"#/components/schemas/StudioAstBlockAnchor"},{"$ref":"#/components/schemas/StudioAstSectionAnchor"},{"$ref":"#/components/schemas/StudioAstUnplacedAnchor"}]},"StudioAstExclusionAnnotation":{"additionalProperties":false,"properties":{"end_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"exclusion","type":"string"},"reason":{"enum":["speaker_label","stage_direction","metadata","user"],"type":"string"},"start_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["id","start_utf16","end_utf16","kind","reason"],"type":"object"},"StudioAstPronunciationAnnotation":{"additionalProperties":false,"properties":{"alphabet":{"enum":["ipa","x-sampa","cmu","alias"],"type":"string"},"end_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"pronunciation","type":"string"},"start_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"value":{"maxLength":500,"minLength":1,"type":"string"}},"required":["id","start_utf16","end_utf16","kind","alphabet","value"],"type":"object"},"StudioAstExtensionAnnotation":{"additionalProperties":false,"properties":{"end_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"extension","type":"string"},"name":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"namespace":{"pattern":"^[a-z][a-z0-9_.-]{0,63}$","type":"string"},"payload":{"$ref":"#/components/schemas/StudioAstJsonValue"},"start_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"}},"required":["id","start_utf16","end_utf16","kind","namespace","name","version","payload"],"type":"object"},"StudioAstTimedSilencePoint":{"additionalProperties":false,"properties":{"duration_ms":{"maximum":300000,"minimum":1,"type":"integer"},"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"timed_silence","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"}},"required":["id","offset_utf16","kind","duration_ms"],"type":"object"},"StudioAstExtensionPoint":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"extension","type":"string"},"name":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"},"namespace":{"pattern":"^[a-z][a-z0-9_.-]{0,63}$","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"payload":{"$ref":"#/components/schemas/StudioAstJsonValue"},"version":{"exclusiveMinimum":0,"maximum":9007199254740991,"type":"integer"}},"required":["id","offset_utf16","kind","namespace","name","version","payload"],"type":"object"},"StudioAstDeliveryDirective":{"discriminator":{"mapping":{"cartesia.emotion":"#/components/schemas/StudioAstCartesiaEmotion","cartesia.laughter":"#/components/schemas/StudioAstCartesiaLaughter","chatterbox.nonverbal":"#/components/schemas/StudioAstChatterboxNonverbal","elevenlabs.audio_tag":"#/components/schemas/StudioAstElevenLabsAudioTag","fish.inline_instruction":"#/components/schemas/StudioAstFishInlineInstruction","inworld.nonverbal":"#/components/schemas/StudioAstInworldNonverbal","inworld.turn_instruction":"#/components/schemas/StudioAstInworldTurnInstruction","openai.instructions":"#/components/schemas/StudioAstOpenAiInstructions"},"propertyName":"kind"},"oneOf":[{"$ref":"#/components/schemas/StudioAstInworldTurnInstruction"},{"$ref":"#/components/schemas/StudioAstInworldNonverbal"},{"$ref":"#/components/schemas/StudioAstFishInlineInstruction"},{"$ref":"#/components/schemas/StudioAstElevenLabsAudioTag"},{"$ref":"#/components/schemas/StudioAstCartesiaEmotion"},{"$ref":"#/components/schemas/StudioAstCartesiaLaughter"},{"$ref":"#/components/schemas/StudioAstOpenAiInstructions"},{"$ref":"#/components/schemas/StudioAstChatterboxNonverbal"}]},"StudioAstDeliverySetting":{"discriminator":{"propertyName":"kind","mapping":{"chatterbox.cfg":"#/components/schemas/StudioAstChatterboxCfg","chatterbox.exaggeration":"#/components/schemas/StudioAstChatterboxExaggeration","f5tts.speed":"#/components/schemas/StudioAstF5Speed","fish.speed":"#/components/schemas/StudioAstFishSpeed","fish.volume":"#/components/schemas/StudioAstFishVolume","inworld.delivery_mode":"#/components/schemas/StudioAstInworldDeliveryMode","inworld.speaking_rate":"#/components/schemas/StudioAstInworldSpeakingRate","openai.speed":"#/components/schemas/StudioAstOpenAiSpeed","smallest.speed":"#/components/schemas/StudioAstSmallestSpeed","zyphra.mode":"#/components/schemas/StudioAstZyphraMode","zyphra.speaking_rate_bucket":"#/components/schemas/StudioAstZyphraSpeakingRateBucket"}},"oneOf":[{"$ref":"#/components/schemas/StudioAstInworldSpeakingRate"},{"$ref":"#/components/schemas/StudioAstInworldDeliveryMode"},{"$ref":"#/components/schemas/StudioAstFishSpeed"},{"$ref":"#/components/schemas/StudioAstFishVolume"},{"$ref":"#/components/schemas/StudioAstOpenAiSpeed"},{"$ref":"#/components/schemas/StudioAstSmallestSpeed"},{"$ref":"#/components/schemas/StudioAstChatterboxExaggeration"},{"$ref":"#/components/schemas/StudioAstChatterboxCfg"},{"$ref":"#/components/schemas/StudioAstZyphraMode"},{"$ref":"#/components/schemas/StudioAstZyphraSpeakingRateBucket"},{"$ref":"#/components/schemas/StudioAstF5Speed"}]},"StudioAstGenerationProfileOverride":{"additionalProperties":false,"description":"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.","minProperties":1,"properties":{"controls":{"enum":["strict","best_effort"],"type":"string"},"fallback":{"enum":["strict","best_effort"],"type":"string"},"model":{"maxLength":200,"minLength":1,"type":"string"},"options":{"additionalProperties":{"$ref":"#/components/schemas/StudioAstJsonValue"},"type":"object"},"provider":{"pattern":"^[a-z][a-z0-9_-]{0,63}$","type":"string"}},"type":"object"},"StudioWorkflowCreateAudioProfileSnapshot":{"description":"Create Audio options frozen when the workflow was created; resumed workflows copy the predecessor's snapshot. Stored rows keep their original profile_version, so readers must accept every version; new workflows currently use studio-create-audio-profile-6, whose direct_emotion is false only when the request turned automatic emotion off. render_format is non-null exactly when render_output is true. target_scope is present only with generation_scope selection, include_sfx false, and render_output false. Stored SFX flags agree: direct_pronunciation_sfx/direct_sfx equal include_sfx (and include_generated_sfx in profile 6).","allOf":[{"if":{"required":["render_output"],"properties":{"render_output":{"const":true}}},"then":{"required":["render_format"],"properties":{"render_format":{"type":"string"}}},"else":{"properties":{"render_format":{"type":"null"}}}},{"if":{"required":["target_scope"]},"then":{"properties":{"generation_scope":{"const":"selection"},"include_sfx":{"const":false},"render_output":{"const":false}}}}],"oneOf":[{"type":"object","required":["profile_version","profile","assign_missing_speakers","match_existing_voices","create_missing_voices","generation_scope","control_policy","include_sfx","render_output"],"properties":{"profile_version":{"type":"string","const":"studio-create-audio-profile-1"},"profile":{"type":"string","enum":["quick","balanced"]},"assign_missing_speakers":{"type":"boolean"},"match_existing_voices":{"type":"boolean","const":true},"create_missing_voices":{"type":"boolean","const":true},"generation_scope":{"type":"string","enum":["stale","selection"]},"control_policy":{"type":"string","const":"best_effort"},"include_sfx":{"type":"boolean"},"preferred_voice_contexts":{"type":"array","maxItems":50,"description":"Preferred voices captured at creation; voice_id values are unique.","items":{"$ref":"#/components/schemas/StudioWorkflowPreferredVoiceContext"}},"render_output":{"type":"boolean"},"render_format":{"type":["string","null"],"enum":["mp3","wav",null]},"target_scope":{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"}},"additionalProperties":false},{"type":"object","required":["profile_version","profile","assign_missing_speakers","match_existing_voices","create_missing_voices","generation_scope","control_policy","include_sfx","direct_section_delivery","direct_pronunciation_sfx","render_output","render_format"],"properties":{"profile_version":{"type":"string","const":"studio-create-audio-profile-2"},"profile":{"type":"string","enum":["balanced","directed"]},"assign_missing_speakers":{"type":"boolean","const":true},"match_existing_voices":{"type":"boolean","const":true},"create_missing_voices":{"type":"boolean","const":true},"generation_scope":{"type":"string","enum":["stale","selection"]},"control_policy":{"type":"string","const":"best_effort"},"include_sfx":{"type":"boolean"},"direct_section_delivery":{"type":"boolean","const":true},"direct_pronunciation_sfx":{"type":"boolean"},"preferred_voice_contexts":{"type":"array","maxItems":50,"description":"Preferred voices captured at creation; voice_id values are unique.","items":{"$ref":"#/components/schemas/StudioWorkflowPreferredVoiceContext"}},"render_output":{"type":"boolean"},"render_format":{"type":["string","null"],"enum":["mp3","wav",null]},"target_scope":{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"}},"additionalProperties":false},{"type":"object","required":["profile_version","profile","assign_missing_speakers","match_existing_voices","create_missing_voices","generation_scope","control_policy","include_sfx","direct_section_delivery","direct_sfx","render_output","render_format"],"properties":{"profile_version":{"type":"string","const":"studio-create-audio-profile-3"},"profile":{"type":"string","enum":["balanced","directed"]},"assign_missing_speakers":{"type":"boolean","const":true},"match_existing_voices":{"type":"boolean","const":true},"create_missing_voices":{"type":"boolean","const":true},"generation_scope":{"type":"string","enum":["stale","selection"]},"control_policy":{"type":"string","const":"best_effort"},"include_sfx":{"type":"boolean"},"direct_section_delivery":{"type":"boolean","const":true},"direct_sfx":{"type":"boolean"},"preferred_voice_contexts":{"type":"array","maxItems":50,"description":"Preferred voices captured at creation; voice_id values are unique.","items":{"$ref":"#/components/schemas/StudioWorkflowPreferredVoiceContext"}},"render_output":{"type":"boolean"},"render_format":{"type":["string","null"],"enum":["mp3","wav",null]},"target_scope":{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"}},"additionalProperties":false},{"type":"object","required":["profile_version","profile","assign_missing_speakers","match_existing_voices","create_missing_voices","generation_scope","control_policy","include_sfx","direct_sfx","render_output","render_format"],"properties":{"profile_version":{"type":"string","const":"studio-create-audio-profile-4"},"profile":{"type":"string","enum":["balanced","directed"]},"assign_missing_speakers":{"type":"boolean","const":true},"match_existing_voices":{"type":"boolean","const":true},"create_missing_voices":{"type":"boolean","const":true},"generation_scope":{"type":"string","enum":["stale","selection"]},"control_policy":{"type":"string","const":"best_effort"},"include_sfx":{"type":"boolean"},"direct_sfx":{"type":"boolean"},"preferred_voice_contexts":{"type":"array","maxItems":50,"description":"Preferred voices captured at creation; voice_id values are unique.","items":{"$ref":"#/components/schemas/StudioWorkflowPreferredVoiceContext"}},"render_output":{"type":"boolean"},"render_format":{"type":["string","null"],"enum":["mp3","wav",null]},"target_scope":{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"}},"additionalProperties":false},{"type":"object","required":["profile_version","profile","assign_missing_speakers","match_existing_voices","create_missing_voices","generation_scope","control_policy","include_sfx","direct_emotion","direct_sfx","render_output","render_format"],"properties":{"profile_version":{"type":"string","const":"studio-create-audio-profile-5"},"profile":{"type":"string","enum":["balanced","directed"]},"assign_missing_speakers":{"type":"boolean","const":true},"match_existing_voices":{"type":"boolean","const":true},"create_missing_voices":{"type":"boolean","const":true},"generation_scope":{"type":"string","enum":["stale","selection"]},"control_policy":{"type":"string","const":"best_effort"},"include_sfx":{"type":"boolean"},"direct_emotion":{"type":"boolean","const":true},"direct_sfx":{"type":"boolean"},"preferred_voice_contexts":{"type":"array","maxItems":50,"description":"Preferred voices captured at creation; voice_id values are unique.","items":{"$ref":"#/components/schemas/StudioWorkflowPreferredVoiceContext"}},"render_output":{"type":"boolean"},"render_format":{"type":["string","null"],"enum":["mp3","wav",null]},"target_scope":{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"}},"additionalProperties":false},{"type":"object","required":["profile_version","profile","assign_missing_speakers","match_existing_voices","create_missing_voices","generation_scope","control_policy","include_sfx","include_generated_sfx","place_project_sounds","direct_emotion","direct_sfx","render_output","render_format"],"properties":{"profile_version":{"type":"string","const":"studio-create-audio-profile-6"},"profile":{"type":"string","enum":["balanced","directed"]},"assign_missing_speakers":{"type":"boolean","const":true},"match_existing_voices":{"type":"boolean","const":true},"create_missing_voices":{"type":"boolean","const":true},"generation_scope":{"type":"string","enum":["stale","selection"]},"control_policy":{"type":"string","const":"best_effort"},"include_sfx":{"type":"boolean"},"include_generated_sfx":{"type":"boolean","description":"Whether generated sound effects were requested."},"place_project_sounds":{"type":"boolean","description":"Whether linked project sounds are placed automatically."},"direct_emotion":{"type":"boolean","description":"Whether the workflow planned an automatic emotion (direct_emotion) step. False only for requests that turned automatic emotion off."},"direct_sfx":{"type":"boolean"},"preferred_voice_contexts":{"type":"array","maxItems":50,"description":"Preferred voices captured at creation; voice_id values are unique.","items":{"$ref":"#/components/schemas/StudioWorkflowPreferredVoiceContext"}},"render_output":{"type":"boolean"},"render_format":{"type":["string","null"],"enum":["mp3","wav",null]},"target_scope":{"$ref":"#/components/schemas/StudioWorkflowCreateAudioTargetScope"}},"additionalProperties":false}]},"StudioWorkflowRunStatus":{"type":"string","enum":["queued","running","completed","partially_completed","failed","canceling","cancelled"],"description":"Workflow run status, recomputed from step statuses after every step transition. Non-terminal: queued (unfinished steps remain and none is active), running (at least one step is active), canceling (cancellation was requested and unfinished steps remain). Terminal (completed_at is set and the status no longer changes): completed (every step succeeded or was skipped), partially_completed (at least one failed or conflict step and at least one succeeded or skipped step), failed (failed or conflict steps and no succeeded or skipped step), cancelled (all steps finished after cancellation was requested)."},"StudioWorkflowStage":{"type":"string","enum":["preparing_sections","assigning_speakers","casting_voices","planning_emotion","directing_delivery","placing_project_sounds","directing_sfx","preparing_voices","generating_audio"],"description":"User-facing stage derived from the step kind of the first active step, or else the first pending step: prepare_section=preparing_sections, assign_speakers=assigning_speakers, cast_voices=casting_voices, direct_emotion=planning_emotion, direct_section_delivery=directing_delivery, place_project_sounds=placing_project_sounds, direct_sfx=directing_sfx, prepare_voices=preparing_voices, generate_stale_audio=generating_audio."},"StudioWorkflowStepKind":{"type":"string","enum":["prepare_section","assign_speakers","cast_voices","direct_emotion","direct_section_delivery","place_project_sounds","direct_sfx","prepare_voices","generate_stale_audio","render_section"],"description":"Kind of work a step performs. prepare_sections workflows contain only prepare_section steps. direct_section_delivery and render_section come from older Create Audio profiles (and successors resumed from them); new workflows do not plan them."},"StudioWorkflowStepStatus":{"type":"string","enum":["pending","active","succeeded","skipped","failed","conflict","cancelled"],"description":"Step status. pending and active are non-terminal; succeeded, skipped, failed, conflict, and cancelled are terminal. The run counts skipped as success and conflict as failure. conflict means the section document changed underneath the step."},"StudioWorkflowIssueKind":{"type":"string","enum":["document_changed","service_out_of_sync","assistant_failed","workflow_failed"],"description":"Classification of a failed or conflict step: document_changed (the section changed before the result could apply), service_out_of_sync (a Studio service contract mismatch; resume after services update), assistant_failed (an assistant step failed), workflow_failed (any other failure)."},"StudioSectionMediaBlockFields":{"type":"object","description":"Media read model for one block.","required":["block_id","freshness","activity","active_block_version","requested_block_version","active_rendition_id","audio_version_count","generation_batch_id","playback_url","playback_url_expires_at","content_type","size_bytes","analysis_integrated_lufs","analysis_sample_peak_dbfs","provider","model","error"],"properties":{"block_id":{"type":"string","format":"uuid"},"freshness":{"type":"string","enum":["absent","current","stale","unsupported"],"description":"absent: no active rendition. current: the active rendition matches the block's current generation intent. stale: it differs (see stale_reasons). unsupported: the block kind is not speech, narration, or sfx."},"activity":{"type":"string","enum":["idle","generating","failed"],"description":"generating: a pending rendition is queued, running, or waiting to retry, or imported audio is being copied. failed: the latest request or import failed. idle otherwise. Independent of freshness."},"active_block_version":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Block version the active rendition was requested for."},"requested_block_version":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991,"description":"Block version of the pending rendition or import, if any."},"active_rendition_id":{"type":["string","null"],"format":"uuid"},"audio_version_count":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Number of completed audio versions for the block."},"generation_batch_id":{"type":["string","null"],"format":"uuid","description":"Generation batch of the pending rendition."},"playback_url":{"type":["string","null"],"format":"uri","description":"Short-lived signed URL for the active rendition's audio; null without an active asset."},"playback_url_expires_at":{"type":["string","null"],"format":"date-time"},"content_type":{"type":["string","null"]},"size_bytes":{"type":["integer","null"],"minimum":1,"maximum":9007199254740991},"analysis_integrated_lufs":{"type":["number","null"],"minimum":-120,"maximum":24},"analysis_sample_peak_dbfs":{"type":["number","null"],"minimum":-200,"maximum":24},"provider":{"type":["string","null"],"description":"Provider that actually produced the active rendition (stored metadata for imports)."},"model":{"type":["string","null"],"description":"Model that actually produced the active rendition (stored metadata for imports)."},"error":{"type":["string","null"],"description":"Latest generation or import error message."},"stale_reasons":{"type":"array","items":{"type":"string","enum":["block_kind","text","pronunciation","excluded_text","timing","voice","generation_profile","delivery_controls","sound_effect"]},"description":"Present for speech, narration, and sfx blocks; non-empty only when freshness is stale."}}},"StudioBoundarySilenceHandling":{"type":"string","enum":["timeline","fixed_in_asset","unsupported","unavailable"],"description":"Boundary silence handling of the active take, not a promise about internal pauses. timeline: stored intent uses timeline-v1, so boundary pauses are assembled outside synthesis. fixed_in_asset: generated speech uses legacy baked timing. unsupported: the active media does not expose supported boundary-pause semantics. unavailable: no active media. Internal timed silences remain fixed in the asset even with timeline handling."},"StudioGenerationProfile":{"type":"object","description":"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.","required":["provider","model","fallback","controls","options"],"properties":{"provider":{"type":"string","pattern":"^[a-z][a-z0-9_-]{0,63}$"},"model":{"type":"string","minLength":1,"maxLength":200},"fallback":{"type":"string","enum":["strict","best_effort"]},"controls":{"type":"string","enum":["strict","best_effort"]},"options":{"type":"object","additionalProperties":true}},"additionalProperties":false},"StudioGenerationAvailabilityDiagnostic":{"type":"object","additionalProperties":false,"required":["code","severity","message"],"properties":{"code":{"type":"string","minLength":1},"severity":{"type":"string","enum":["warning","error"]},"message":{"type":"string","minLength":1}}},"StudioProviderAvailabilityOption":{"type":"object","additionalProperties":false,"required":["provider","model","status","reason","diagnostics"],"properties":{"provider":{"type":"string","minLength":1},"model":{"type":"string","minLength":1},"status":{"type":"string","enum":["available","materialization_required","unavailable"]},"reason":{"type":["string","null"]},"reason_code":{"type":"string","enum":["provider_asset_missing","acoustic_revision_changed"]},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/StudioGenerationAvailabilityDiagnostic"}}}},"StudioPlaybackSequentialUnit":{"description":"Sequential timeline unit, discriminated by unit_type: asset (speech audio), silence (a rendered pause), or spacing (inter-passage gap).","oneOf":[{"type":"object","required":["unit_id","block_id","block_index","block_version","block_kind","start_ms","duration_ms","rendition_id","rendition_intent_hash","unit_type","asset_id","asset_content_hash","source_ranges","speaker_id","analysis_integrated_lufs","analysis_sample_peak_dbfs","effective_gain_db"],"properties":{"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"block_kind":{"type":"string","enum":["speech","narration"]},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991},"rendition_id":{"type":"string","format":"uuid"},"rendition_intent_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"unit_type":{"type":"string","const":"asset"},"asset_id":{"type":"string","format":"uuid","description":"Key into the payload's assets array."},"asset_content_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"source_ranges":{"type":"array","minItems":1,"maxItems":10000,"items":{"$ref":"#/components/schemas/StudioPlaybackSourceRange"}},"speaker_id":{"type":"string","format":"uuid"},"analysis_integrated_lufs":{"type":"number","minimum":-120,"maximum":12},"analysis_sample_peak_dbfs":{"type":"number","minimum":-200,"maximum":12},"effective_gain_db":{"type":"number","minimum":-24,"maximum":24}},"additionalProperties":false},{"type":"object","required":["unit_id","block_id","block_index","block_version","block_kind","start_ms","duration_ms","rendition_id","rendition_intent_hash","unit_type"],"properties":{"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"block_kind":{"type":"string","enum":["speech","narration"]},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991},"rendition_id":{"type":"string","format":"uuid"},"rendition_intent_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"unit_type":{"type":"string","const":"silence"}},"additionalProperties":false},{"type":"object","required":["unit_id","block_id","block_index","block_version","block_kind","start_ms","duration_ms","unit_type","spacing_kind"],"properties":{"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"block_kind":{"type":"string","enum":["speech","narration"]},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991},"unit_type":{"type":"string","const":"spacing"},"spacing_kind":{"type":"string","const":"inter_passage"}},"additionalProperties":false}]},"StudioPlaybackOverlayUnit":{"type":"object","required":["unit_type","unit_id","block_id","block_index","block_version","intent_hash","asset_id","asset_content_hash","start_ms","duration_ms","gain_db","fade_in_ms","fade_out_ms"],"properties":{"unit_type":{"type":"string","const":"sfx"},"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"intent_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"asset_id":{"type":"string","format":"uuid","description":"Key into the payload's assets array."},"asset_content_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991},"gain_db":{"type":"number","minimum":-60,"maximum":24},"fade_in_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"fade_out_ms":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false,"description":"Sound-effect overlay mixed over the sequential timeline; fade_in_ms + fade_out_ms <= duration_ms."},"StudioPlaybackTimedTextUnit":{"type":"object","required":["unit_id","block_id","block_index","block_version","speaker_id","start_ms","duration_ms","text","text_hash","source_ranges"],"properties":{"unit_id":{"type":"string","format":"uuid"},"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"speaker_id":{"type":"string","format":"uuid"},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"duration_ms":{"type":"integer","minimum":1,"maximum":9007199254740991},"text":{"type":"string","minLength":1,"maxLength":100000},"text_hash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"source_ranges":{"type":"array","minItems":1,"maxItems":10000,"items":{"$ref":"#/components/schemas/StudioPlaybackSourceRange"}}},"additionalProperties":false,"description":"Text shown during a timeline interval; never extends past the manifest duration."},"StudioPlaybackGap":{"description":"Block media missing from the timeline, discriminated by media_kind; at most one gap per block and media kind.","oneOf":[{"type":"object","required":["block_id","block_index","block_version","media_kind","reason","source_ranges"],"properties":{"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"media_kind":{"type":"string","const":"speech"},"reason":{"type":"string","enum":["missing","stale","failed","unsupported","unassigned","unresolved"]},"source_ranges":{"type":"array","minItems":1,"maxItems":10000,"items":{"$ref":"#/components/schemas/StudioPlaybackSourceRange"}}},"additionalProperties":false},{"type":"object","required":["block_id","block_index","block_version","media_kind","reason","source_ranges"],"properties":{"block_id":{"type":"string","format":"uuid"},"block_index":{"type":"integer","minimum":0,"maximum":9007199254740991},"block_version":{"type":"integer","minimum":1,"maximum":9007199254740991},"media_kind":{"type":"string","const":"sfx"},"reason":{"type":"string","enum":["missing","stale","failed","unsupported","unplaced"]},"source_ranges":{"type":"array","maxItems":0}},"additionalProperties":false}]},"StudioWordTiming":{"type":"object","additionalProperties":false,"required":["text","start_ms","end_ms"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4096},"start_ms":{"type":"integer","minimum":0,"maximum":9007199254740991},"end_ms":{"type":"integer","minimum":0,"maximum":9007199254740991}},"description":"Provider-aligned word with section-relative integer milliseconds. end_ms is at least start_ms; not an ASR transcript or a text-length estimate."},"StudioAstTextContent":{"additionalProperties":false,"properties":{"annotations":{"items":{"$ref":"#/components/schemas/StudioAstTextAnnotation"},"type":"array"},"delivery_control_sets":{"items":{"$ref":"#/components/schemas/StudioAstDeliveryControlSet"},"maxItems":32,"type":"array"},"points":{"items":{"$ref":"#/components/schemas/StudioAstPointNode"},"type":"array"},"schema_version":{"const":"studio-ast-2","type":"string"},"text":{"type":"string","maxLength":65536,"description":"Exact block text; at most 65,536 UTF-16 code units. Annotation, point, and delivery offsets are UTF-16 offsets into this string."},"type":{"const":"text","type":"string"}},"required":["schema_version","type","text","annotations","points","delivery_control_sets"],"type":"object"},"StudioAstNoteContent":{"additionalProperties":false,"properties":{"schema_version":{"const":"studio-ast-2","type":"string"},"text":{"maxLength":20000,"type":"string"},"type":{"const":"note","type":"string"}},"required":["schema_version","type","text"],"type":"object"},"StudioAstBlockAnchor":{"additionalProperties":false,"properties":{"block_id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"fraction":{"anyOf":[{"maximum":1,"minimum":0,"type":"number"},{"type":"null"}]},"kind":{"const":"block","type":"string"},"position":{"enum":["start","fraction","end","after"],"type":"string"}},"required":["kind","block_id","position","fraction"],"type":"object"},"StudioAstSectionAnchor":{"additionalProperties":false,"properties":{"kind":{"const":"section","type":"string"},"position":{"enum":["start","end"],"type":"string"}},"required":["kind","position"],"type":"object"},"StudioAstUnplacedAnchor":{"additionalProperties":false,"properties":{"kind":{"const":"unplaced","type":"string"}},"required":["kind"],"type":"object"},"StudioAstJsonValue":{"anyOf":[{"type":"boolean"},{"type":"string"},{"maximum":9007199254740991,"minimum":-9007199254740991,"type":"integer"},{"not":{"type":"integer"},"type":"number"},{"items":{"$ref":"#/components/schemas/StudioAstJsonValue"},"type":"array"},{"additionalProperties":{"$ref":"#/components/schemas/StudioAstJsonValue"},"type":"object"},{"type":"null"}]},"StudioAstInworldTurnInstruction":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"instruction":{"maxLength":4000,"minLength":1,"type":"string"},"kind":{"const":"inworld.turn_instruction","type":"string"},"scope":{"$ref":"#/components/schemas/StudioAstDeliveryScope"}},"required":["id","kind","instruction"],"type":"object"},"StudioAstInworldNonverbal":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"inworld.nonverbal","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"ordinal":{"maximum":255,"minimum":0,"type":"integer"},"value":{"enum":["laugh","breathe","clear_throat","sigh","cough","yawn"],"type":"string"}},"required":["id","kind","offset_utf16","ordinal","value"],"type":"object"},"StudioAstFishInlineInstruction":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"instruction":{"maxLength":4000,"minLength":1,"type":"string"},"kind":{"const":"fish.inline_instruction","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"ordinal":{"maximum":255,"minimum":0,"type":"integer"}},"required":["id","kind","offset_utf16","ordinal","instruction"],"type":"object"},"StudioAstElevenLabsAudioTag":{"type":"object","required":["id","kind","instruction","scope"],"properties":{"id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"kind":{"type":"string","const":"elevenlabs.audio_tag"},"instruction":{"type":"string","minLength":1,"maxLength":200,"description":"Trimmed audio-tag text without square brackets or control characters."},"scope":{"$ref":"#/components/schemas/StudioAstDeliveryScope"}},"additionalProperties":false},"StudioAstCartesiaEmotion":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"cartesia.emotion","type":"string"},"scope":{"$ref":"#/components/schemas/StudioAstDeliveryScope"},"value":{"enum":["neutral","happy","excited","enthusiastic","elated","euphoric","triumphant","amazed","surprised","flirtatious","curious","content","peaceful","serene","calm","grateful","affectionate","trust","sympathetic","anticipation","mysterious","angry","mad","outraged","frustrated","agitated","threatened","disgusted","contempt","envious","sarcastic","ironic","sad","dejected","melancholic","disappointed","hurt","guilty","bored","tired","rejected","nostalgic","wistful","apologetic","hesitant","insecure","confused","resigned","anxious","panicked","alarmed","scared","proud","confident","distant","skeptical","contemplative","determined"],"type":"string"}},"required":["id","kind","scope","value"],"type":"object"},"StudioAstCartesiaLaughter":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"cartesia.laughter","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"ordinal":{"maximum":255,"minimum":0,"type":"integer"}},"required":["id","kind","offset_utf16","ordinal"],"type":"object"},"StudioAstOpenAiInstructions":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"instruction":{"maxLength":4000,"minLength":1,"type":"string"},"kind":{"const":"openai.instructions","type":"string"}},"required":["id","kind","instruction"],"type":"object"},"StudioAstChatterboxNonverbal":{"additionalProperties":false,"properties":{"id":{"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","type":"string"},"kind":{"const":"chatterbox.nonverbal","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"ordinal":{"maximum":255,"minimum":0,"type":"integer"},"value":{"enum":["laugh","chuckle","sigh","cough","sniffle","groan","yawn","gasp"],"type":"string"}},"required":["id","kind","offset_utf16","ordinal","value"],"type":"object"},"StudioAstInworldSpeakingRate":{"additionalProperties":false,"properties":{"kind":{"const":"inworld.speaking_rate","type":"string"},"value":{"maximum":1.5,"minimum":0.5,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstInworldDeliveryMode":{"additionalProperties":false,"properties":{"kind":{"const":"inworld.delivery_mode","type":"string"},"value":{"enum":["stable","balanced","creative"],"type":"string"}},"required":["kind","value"],"type":"object"},"StudioAstFishSpeed":{"additionalProperties":false,"properties":{"kind":{"const":"fish.speed","type":"string"},"value":{"maximum":2,"minimum":0.5,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstFishVolume":{"additionalProperties":false,"properties":{"kind":{"const":"fish.volume","type":"string"},"value":{"maximum":20,"minimum":-20,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstOpenAiSpeed":{"additionalProperties":false,"properties":{"kind":{"const":"openai.speed","type":"string"},"value":{"maximum":4,"minimum":0.25,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstSmallestSpeed":{"additionalProperties":false,"properties":{"kind":{"const":"smallest.speed","type":"string"},"value":{"maximum":2,"minimum":0.5,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstChatterboxExaggeration":{"additionalProperties":false,"properties":{"kind":{"const":"chatterbox.exaggeration","type":"string"},"value":{"maximum":1,"minimum":0,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstChatterboxCfg":{"additionalProperties":false,"properties":{"kind":{"const":"chatterbox.cfg","type":"string"},"value":{"maximum":1,"minimum":0,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioAstZyphraMode":{"additionalProperties":false,"properties":{"kind":{"const":"zyphra.mode","type":"string"},"value":{"enum":["stable","expressive"],"type":"string"}},"required":["kind","value"],"type":"object"},"StudioAstZyphraSpeakingRateBucket":{"additionalProperties":false,"properties":{"kind":{"const":"zyphra.speaking_rate_bucket","type":"string"},"value":{"maximum":7,"minimum":0,"type":"integer"}},"required":["kind","value"],"type":"object"},"StudioAstF5Speed":{"additionalProperties":false,"properties":{"kind":{"const":"f5tts.speed","type":"string"},"value":{"maximum":2,"minimum":0.3,"type":"number"}},"required":["kind","value"],"type":"object"},"StudioWorkflowPreferredVoiceContext":{"type":"object","required":["voice_id","speaker_name","role","age","interests","story_notes","is_narrator"],"properties":{"voice_id":{"type":"string","format":"uuid"},"speaker_name":{"type":"string","minLength":1,"maxLength":200},"role":{"type":"string","minLength":1,"maxLength":100},"age":{"type":["integer","null"],"minimum":0,"maximum":120},"interests":{"type":["string","null"],"maxLength":2000},"story_notes":{"type":["string","null"],"maxLength":4000},"is_narrator":{"type":"boolean"}},"additionalProperties":false,"description":"Voice the workflow was asked to prefer when casting, with its casting context."},"StudioPlaybackSourceRange":{"type":"object","required":["start_utf16","end_utf16"],"properties":{"start_utf16":{"type":"integer","minimum":0,"maximum":9007199254740991},"end_utf16":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false,"description":"Nonempty UTF-16 range of block text (start_utf16 < end_utf16). Range lists are sorted, disjoint, and non-adjacent."},"StudioAstDeliveryScope":{"discriminator":{"propertyName":"kind","mapping":{"block":"#/components/schemas/StudioAstDeliveryBlockScope","point":"#/components/schemas/StudioAstDeliveryPointScope"}},"oneOf":[{"$ref":"#/components/schemas/StudioAstDeliveryBlockScope"},{"$ref":"#/components/schemas/StudioAstDeliveryPointScope"}]},"StudioAstDeliveryBlockScope":{"additionalProperties":false,"properties":{"kind":{"const":"block","type":"string"}},"required":["kind"],"type":"object"},"StudioAstDeliveryPointScope":{"additionalProperties":false,"properties":{"kind":{"const":"point","type":"string"},"offset_utf16":{"maximum":9007199254740991,"minimum":0,"type":"integer"},"ordinal":{"maximum":255,"minimum":0,"type":"integer"}},"required":["kind","offset_utf16","ordinal"],"type":"object"}},"parameters":{"ProjectId":{"name":"projectId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}}}}