{
  "openapi": "3.1.0",
  "info": {
    "title": "Jutusta Speech API",
    "version": "1.0.0",
    "summary": "ElevenLabs-compatible text-to-speech and speech-to-text for Estonian-first models.",
    "description": "An ElevenLabs-compatible HTTP API for the Jutusta speech stack. Covers text-to-speech (synchronous + streaming), voice clones, and speech-to-text in two flavours: a synchronous `POST /speech-to-text` (≤ 100 MB inline) and the async recognition flow — presigned upload via `POST /recognition/uploads` → R2 PUT → `POST /recognition/jobs/{job_id}/start` → poll `GET /recognition/jobs/{job_id}` (or have the result POSTed to a registered webhook). Most ElevenLabs SDKs work by pointing `baseUrl` at this service. See `x-compatibility` for known deviations.",
    "contact": {
      "name": "Jutusta",
      "url": "https://jutusta.ee"
    }
  },
  "servers": [
    {
      "url": "https://www.jutusta.ee/api/v1",
      "description": "This deployment"
    }
  ],
  "x-compatibility": {
    "emulates": "api.elevenlabs.io/v1",
    "deviations": [
      {
        "field": "output_format",
        "note": "Only `wav`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100` are honoured. MP3 variants return 415."
      },
      {
        "field": "voice_settings",
        "note": "All fields are accepted for compatibility and currently ignored. `speed` is validated and clamped to [0.5, 2] but not applied: the streaming engine has no tempo control, so audio plays at the voice's natural pace. `stability`, `similarity_boost`, `style`, `use_speaker_boost` have no effect."
      },
      {
        "field": "previous_text / next_text",
        "note": "Accepted for ElevenLabs SDK compatibility and ignored. Voice continuity across sequential requests is not implemented today — each request is synthesized independently. The voice id and, optionally, a fixed `seed` are the only consistency mechanisms; see the `seed` field."
      },
      {
        "field": "seed",
        "note": "Honoured as a best-effort sampling seed, not a guarantee of byte-identical audio. The accepted range is 0–2147483647: ElevenLabs allows up to 4294967295, but a larger value is rejected rather than folded, as is a negative, a fraction or a string — each returns `400 invalid_seed`. The same seed is used for every sentence segment of a request; on the WebSocket `stream-input` endpoint it is passed as the `?seed=` query parameter of the upgrade and used for every chunk of the session. When omitted, a fixed server-side default seed applies, so repeating an identical request returns the same audio; to get a different take of the same text, send a different seed. The default can change, so send an explicit seed to pin a result. On the non-stream endpoint (and on `/stream` for voices the streaming engine cannot serve) the seed applies to the first attempt only: a sentence that fails an internal quality check (looping, wrong length, misread text) is regenerated with a new seed. Identical requests can also differ slightly when the GPU processes several requests together."
      },
      {
        "field": "model_id",
        "note": "TTS recognises `jutusta_v1` and `jutusta_v2`. `jutusta_v2` (Estonian, non-streaming endpoint only) renders inline tags and `instructions`; it is chosen automatically when a request carries either, and asking for it where it cannot serve is a `400 model_unsupported` (or `409 voice_incompatible` for a voice it has no reference for). Any other value, `jutusta_v1` included, is treated as if `model_id` were omitted."
      },
      {
        "field": "text-to-speech/stream-input",
        "note": "The WebSocket `stream-input` endpoint emits RAW PCM (s16le, 24 kHz, mono) as base64 strings — there is no WAV header on the wire and `output_format` is ignored. Your own voice clones are accepted as `voice_id` too; a clone with no full reference transcript on file answers `409 voice_not_streamable` (use `POST /text-to-speech/{voice_id}/stream` for it). Idle sockets are closed after 60 s with code 1011."
      },
      {
        "field": "speech-to-text/file",
        "note": "Inline `file` uploads are capped at 100 MB. Larger files must use the deployment-specific `/api/v1/recognition/uploads` presigned flow."
      },
      {
        "field": "speech-to-text/model_id",
        "note": "Any non-empty model id is accepted; the engine is the Jutusta ASR model. `scribe_v1`/`scribe_v2` values are accepted for SDK compatibility."
      },
      {
        "field": "speech-to-text/timestamps_granularity",
        "note": "`word` (default) and `none` are honoured. `character` falls back to `word`."
      },
      {
        "field": "speech-to-text/additional_formats",
        "note": "Honoured for `srt`, `txt` and `segmented_json` — generated files are returned in the response `additional_formats` array (and on the webhook payload). `docx`, `html` and `pdf` are accepted-and-skipped. The numeric segmentation knobs (`max_characters_per_line`, `max_segment_chars`, `max_segment_duration_s`, `segment_on_silence_longer_than_s`) are ignored; the subtitle chunker uses its own heuristic. `srt` always carries timecodes and no speaker labels; `segmented_json` follows Jutusta's segments schema."
      },
      {
        "field": "speech-to-text/ignored-fields",
        "note": "tag_audio_events, num_speakers, temperature, seed, entity_detection, entity_redaction, entity_redaction_mode, no_verbatim, detect_speaker_roles, keyterms, use_multi_channel, file_format, enable_logging — all accepted for SDK compatibility and ignored."
      },
      {
        "field": "speech-to-text/webhook-delivery",
        "note": "Webhooks are delivered on a best-effort basis from the Worker that handled the request. For long-running transcriptions where the request Worker is recycled before completion, delivery may be deferred until a subsequent `GET /recognition/jobs/{id}` poll observes the terminal transition, or until the cron-driven `webhook-poller` worker picks the row up on its next sweep."
      },
      {
        "field": "speech-to-text/language_probability",
        "note": "The Jutusta ASR backend does not emit a calibrated language-detection confidence today, so `language_probability` is reported as `1` when `language_code` names a language and `0` when it is `unknown`. `language_code` is the detected language, or the one you named in the request when nothing was detected; it is `unknown` when nothing was detected and the request named no language (omitted or `auto`). Treat the value as a coarse \"known/unknown\" flag, not a real probability."
      }
    ]
  },
  "security": [
    {
      "XiApiKey": []
    }
  ],
  "tags": [
    {
      "name": "voices",
      "description": "List and inspect available voices."
    },
    {
      "name": "text-to-speech",
      "description": "Synthesize speech from text."
    },
    {
      "name": "speech-to-text",
      "description": "Transcribe audio and video files."
    },
    {
      "name": "recognition",
      "description": "Async transcription jobs: presigned R2 upload, start, list, and poll. Use this flow for files larger than the 100 MB inline cap on `/speech-to-text`, or any time you want progress reporting."
    },
    {
      "name": "webhooks",
      "description": "Manage webhook subscriptions used for async transcriptions."
    },
    {
      "name": "summaries",
      "description": "LLM-generated meeting summaries for finished transcription jobs, or for a transcript the caller sends (`POST /summarize`). Templates are catalog-defined; callers pick one per request or rely on their per-user default."
    },
    {
      "name": "translate",
      "description": "Append-only chunk translation. Each call returns text to concatenate to what the caller has rendered so far — earlier output is never rewritten."
    },
    {
      "name": "models",
      "description": "Available TTS models."
    },
    {
      "name": "audio-detection",
      "description": "Check whether audio carries the AI-generated mark of Jutusta speech synthesis."
    }
  ],
  "paths": {
    "/voices": {
      "get": {
        "tags": [
          "voices"
        ],
        "summary": "List voices",
        "operationId": "listVoices",
        "description": "Returns all preset voices plus any voice clones owned by the caller. Cloned voices are marked with `category: \"cloned\"`.",
        "responses": {
          "200": {
            "description": "Available voices for the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoicesList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/voices/add": {
      "post": {
        "tags": [
          "voices"
        ],
        "summary": "Create a voice clone",
        "operationId": "addVoice",
        "description": "Creates a voice clone owned by the API key holder. Accepts the audio file under the standard ElevenLabs `files` field; the deployment-specific `audio` field is also accepted. Send one sample of 6–45 seconds of clean speech; 30–45 seconds gives the closest likeness. The returned `voice_id` can be used directly with `/text-to-speech/{voice_id}`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/AddVoiceRequest"
              },
              "encoding": {
                "files": {
                  "contentType": "audio/*"
                },
                "audio": {
                  "contentType": "audio/*"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Voice clone created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AddVoiceResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/voices/{voice_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VoiceId"
        }
      ],
      "get": {
        "tags": [
          "voices"
        ],
        "summary": "Get voice",
        "operationId": "getVoice",
        "responses": {
          "200": {
            "description": "Single voice.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Voice"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/text-to-speech/{voice_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VoiceId"
        },
        {
          "$ref": "#/components/parameters/OutputFormat"
        }
      ],
      "post": {
        "tags": [
          "text-to-speech"
        ],
        "summary": "Synthesize speech",
        "operationId": "textToSpeech",
        "description": "Returns the whole clip as one WAV file.\n\n**Voice direction (Estonian).** For Estonian text (`language_code: \"et\"`, or an Estonian voice) this endpoint renders inline tags and an `instructions` field. A tag is written in square brackets where it should take effect: a mood or delivery tag lasts to the end of its paragraph (or until the next one), a sound or pause happens once. Tags are written in Estonian (the English names are accepted too): `[rõõmsalt]` → `[happy]`, `[elevil]` → `[excited]`, `[uhkelt]` → `[proud]`, `[mänguliselt]` → `[playful]`, `[rahulolevalt]` → `[content]`, `[sihikindlalt]` → `[determined]`, `[aukartusega]` → `[in awe]`, `[sarkastiliselt]` → `[sarcastic]`, `[vihaselt]` → `[angry]`, `[kurvalt]` → `[sad]`, `[väsinult]` → `[tired]`, `[hirmunult]` → `[scared]`, `[ehmunult]` → `[startled]`, `[närviliselt]` → `[nervous]`, `[sosinal]` → `[whispers]`, `[vaikselt]` → `[softly]`, `[karjudes]` → `[shouts]`, `[aeglaselt]` → `[slowly]`, `[kiirustades]` → `[rushed]`, `[murduva häälega]` → `[voice breaking]`, `[naerab]` → `[laughs]`, `[muheleb]` → `[chuckling]`, `[itsitab]` → `[giggles]`, `[ohkab]` → `[sighs]`, `[ahhetab]` → `[gasps]`, `[hingab sisse]` → `[inhales]`, `[hingab välja]` → `[exhales]`, `[köhatab]` → `[clears throat]`, `[paus]` → `[pause]`, `[pikk paus]` → `[long pause]`. Other bracketed text is read as text. `instructions` describes the delivery in Estonian or English (at most 300 characters) and is translated server-side. Direction works with the Estonian preset voices and with clones that have a complete reference transcript; elsewhere an `instructions` field is refused (`400 instructions_unsupported`, `409 voice_incompatible`) and tags are removed from the text. Direction is not available on `/stream` or `stream-input`. Tags are not billed; the words are.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TextToSpeechBufferedRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synthesized audio bytes.",
            "headers": {
              "x-audio-duration-ms": {
                "description": "Approximate duration of the returned audio in milliseconds.",
                "schema": {
                  "type": "string"
                }
              },
              "x-audio-sample-rate": {
                "description": "Sample rate of the returned audio.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "audio/basic": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          },
          "503": {
            "description": "`loop_detected`: every attempt at one passage failed the quality check, so no audio is returned and nothing is charged. Reword that passage slightly and retry. `service_unavailable`: the speech engine is not available right now. `direction_unavailable`: voice direction (tags, `instructions`) cannot be processed right now.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/text-to-speech/{voice_id}/stream": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VoiceId"
        },
        {
          "$ref": "#/components/parameters/OutputFormat"
        }
      ],
      "post": {
        "tags": [
          "text-to-speech"
        ],
        "summary": "Synthesize speech (streamed)",
        "description": "Same request contract as `POST /text-to-speech/{voice_id}` with one extra body field: `sentence_chunking` (boolean, default `true`). When sentence chunking is on, the input is split into sentence-sized segments and each segment is synthesized independently; a segment of 120 characters or more is split further, within its first 100 characters: at a sentence end, else at clause punctuation (`,` `;` `:`), else at a space — except in Chinese, Cantonese, Japanese and Thai, which are written without spaces. The leading silence of a piece that follows a cut at a space or inside a word is shortened. The Worker stitches the resulting PCM into a single streaming WAV, so playback can begin as soon as the first audio is generated instead of after the entire text — with the streaming engine the first bytes typically arrive within a few hundred milliseconds, while the first sentence is still being rendered. Text is always sentence-chunked: `sentence_chunking: false` is accepted for compatibility and has no effect. The response sets `x-streaming-mode: sentence` and `x-sentence-count: <n>` when chunking is in effect, and the WAV header carries placeholder length fields (0xFFFFFFFF) because total duration is not known up-front.\n\n**Mid-stream failures.** Errors that occur on the first segment are returned with the usual HTTP status (4xx/5xx) before any audio is sent. Once the response has started no status can change; a failure on segment N is logged server-side and the connection is then terminated abruptly (aborted, not a clean end-of-stream), so reading the response body raises a network error instead of ending normally. Treat any such error as a partial result and discard or retry — do not play or cache the truncated WAV. Nothing is billed for a request that fails mid-stream.",
        "operationId": "textToSpeechStream",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TextToSpeechRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Streamed audio bytes.",
            "headers": {
              "x-streaming-mode": {
                "description": "`sentence` when chunking is active, `single` when a single synth was returned.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "sentence",
                    "single"
                  ]
                }
              },
              "x-sentence-count": {
                "description": "Number of sentence-level segments concatenated into the response (only present in `sentence` mode).",
                "schema": {
                  "type": "string"
                }
              },
              "x-audio-sample-rate": {
                "description": "Sample rate of the returned audio.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "audio/wav": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/text-to-speech/{voice_id}/stream-input": {
      "parameters": [
        {
          "$ref": "#/components/parameters/VoiceId"
        },
        {
          "$ref": "#/components/parameters/StreamInputApiKeyQuery"
        },
        {
          "$ref": "#/components/parameters/StreamInputLanguageQuery"
        },
        {
          "$ref": "#/components/parameters/StreamInputLanguageHeader"
        },
        {
          "$ref": "#/components/parameters/StreamInputSeedQuery"
        }
      ],
      "get": {
        "tags": [
          "text-to-speech"
        ],
        "summary": "Synthesize speech (WebSocket stream-input)",
        "operationId": "textToSpeechStreamInput",
        "description": "WebSocket endpoint that mirrors ElevenLabs `stream-input`. Open the connection with `wss://…/api/v1/text-to-speech/{voice_id}/stream-input`, then push JSON text frames as your LLM emits tokens; the server returns base64-encoded PCM audio frames. Voice continuity across chunks is handled server-side: the voice's reference anchor is fixed on the streaming engine, so identity stays stable across frames and the client never carries voice tokens. Set the spoken language via the `?language=` query parameter or `X-Speak-Language` header; it defaults to the voice's own language.\n\n**Authentication.** Send `Authorization: Bearer sk_jt_…` or `xi-api-key: sk_jt_…` on the upgrade request, OR pass `?xi_api_key=sk_jt_…` on the URL (browsers cannot set custom headers on a `WebSocket()` upgrade). The key is stripped from the URL before the request reaches our application logs, but a URL can still be recorded by proxies and tooling on the way — server-side clients should use a header.\n\n**Client → server frames** (JSON text):\n- `{\"text\": \" \"}` — init (literal single space). Voice metadata is already resolved server-side from the path.\n- `{\"text\": \"Hello \"}` — append to the synth buffer. Synthesized when a sentence boundary is reached and the buffer is ≥ 40 chars. A buffer that reaches 120 chars without one is cut at the last sentence end, clause punctuation (`,` `;` `:`) or, failing those, space within its first 100 chars (punctuation counts only when it leaves a piece of at least 40 chars; text with no space to cut at is cut at 100 chars), so no single piece of speech runs much past six seconds. The piece after a cut at a space or inside a word has its leading silence shortened, so the cut is not heard as a pause. Chinese, Cantonese, Japanese and Thai are written without spaces and are not cut this way: a buffer in those languages is cut only when it reaches 240 chars.\n- `{\"text\": \"...\", \"try_trigger_generation\": true}` — synth the current buffer immediately. Use sparingly; mid-clause splits hurt prosody.\n- `{\"text\": \"...\", \"voice_settings\": {\"speed\": 1.1}}` — accepted on any frame; `speed` is clamped to [0.5, 2] but currently not applied (the streaming engine has no tempo control). Other `voice_settings` fields are accepted and ignored (see `x-compatibility`).\n- `{\"flush\": true}` (with or without `text`) — force-synth the buffered text immediately and keep the session open. Use this at the end of each LLM response in a voice-agent loop; the socket survives for the next response.\n- `{\"cancel\": true}` — barge-in: drop the buffered text and everything not yet spoken, stop the audio being generated, and keep the session open. The server answers `{\"audio\": null, \"cancelDone\": true}` and sends no more audio of the cancelled text. The same frame may carry `text` (and `flush`), which is then spoken as the new response. An extension — not part of the ElevenLabs protocol.\n- `{\"text\": \"\"}` — end of stream: flush the remaining buffer, emit `{audio:null,isFinal:true}`, and close cleanly with code 1000.\n\n**Server → client frames** (JSON text):\n- `{\"audio\": \"<base64 PCM s16le 24 kHz mono>\", \"isFinal\": false}` — one per synthesized chunk. Audio is RAW PCM with no WAV header; decode by reading int16 little-endian samples at 24000 Hz.\n- `{\"audio\": null, \"flushDone\": true}` — sent once a `flush` has fully drained its audio. Marks the end of that flushed segment; the session stays open for the next response. Older clients that only read `audio`/`isFinal` can ignore it.\n- `{\"audio\": null, \"cancelDone\": true}` — acknowledges a `cancel`. Audio frames received before it belong to the cancelled text and can be discarded; a flush that was cancelled gets no `flushDone`.\n- `{\"audio\": null, \"isFinal\": true}` — sent right before a clean close (1000), only on end of stream (`{\"text\": \"\"}`).\n- `{\"error\": {\"code\": \"...\", \"message\": \"...\"}}` — sent before a 1011 close when the upstream synth fails mid-session.\n\n**Voice clones are not yet supported on this endpoint** — clone ids return 404 with a pointer to `POST /text-to-speech/{voice_id}`. This is a deployment limitation (the WS sidecar Worker has no R2/D1 bindings) and will be lifted in a later release.\n\n**Idle timeout.** The server closes the socket with code 1011 after 60 seconds with no inbound frame. Voice-agent clients pace by LLM token output, so longer gaps mean the client is gone.\n\n**Billing.** Same basis as `POST /text-to-speech/{voice_id}`: 250 characters = 1 credit (500 on the Starter and Pro subscriptions and on accounts without a subscription that bought a credit pack), settled per synthesized chunk in 0.001-credit steps, so a session pays for exactly the text it spoke. A chunk you cut short — with `cancel`, or by closing the socket while it is being generated — is charged pro rata for the audio already sent. Nothing is charged for opening the socket; the upgrade only requires a balance that covers 250 characters (`402 insufficient_credits` otherwise). If the wallet runs dry mid-session the current chunk's audio is still delivered, then the server sends `{\"error\": {\"code\": \"insufficient_credits\"}}` and closes with code 4002; code 4003 (`billing_unavailable`) means the meter itself failed and you should reconnect.",
        "x-websocket": true,
        "x-message-schemas": {
          "client": {
            "$ref": "#/components/schemas/StreamInputClientFrame"
          },
          "serverAudio": {
            "$ref": "#/components/schemas/StreamInputAudioFrame"
          },
          "serverError": {
            "$ref": "#/components/schemas/StreamInputErrorFrame"
          }
        },
        "responses": {
          "101": {
            "description": "Switching Protocols — WebSocket upgrade succeeded. See the description for the frame protocol."
          },
          "400": {
            "description": "Invalid upgrade parameters: an unknown `language` (`invalid_language`), one the streaming engine does not speak (`language_unsupported`), or an invalid `seed` (`invalid_seed`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamInputUpgradeError"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key or access token (`unauthorized`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamInputUpgradeError"
                }
              }
            }
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "description": "OAuth access token without the `tts` scope (`insufficient_scope`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamInputUpgradeError"
                }
              }
            }
          },
          "404": {
            "description": "No preset voice and no voice clone of yours with this id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamInputUpgradeError"
                }
              }
            }
          },
          "503": {
            "description": "WebSocket sidecar (TTS_SESSION binding) not configured on this deployment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StreamInputUpgradeError"
                }
              }
            }
          }
        }
      }
    },
    "/speech-to-text": {
      "post": {
        "tags": [
          "speech-to-text"
        ],
        "summary": "Transcribe an audio or video file",
        "operationId": "speechToText",
        "description": "Transcribe an audio/video file uploaded inline or referenced by an https URL. Returns the transcript synchronously by default. Pass `webhook=true` together with a previously-registered `webhook_id` to have the transcript delivered to your endpoint instead — the immediate response then contains only `task_id`/`transcription_id`. Inline files are capped at 100 MB; for larger inputs use the `/recognition/uploads` presigned-PUT flow.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/SpeechToTextRequest"
              },
              "encoding": {
                "file": {
                  "contentType": "audio/*, video/*"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Synchronous transcription result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SpeechToTextResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/speech-to-text/transcripts/{transcription_id}": {
      "parameters": [
        {
          "name": "transcription_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "The `transcription_id` returned by `POST /speech-to-text`."
        }
      ],
      "delete": {
        "tags": [
          "speech-to-text"
        ],
        "summary": "Delete a transcript",
        "operationId": "deleteSpeechToTextTranscript",
        "description": "Deletes the transcript, its audio and the job behind it for good, as `DELETE /recognition/jobs/{job_id}?purge=true` does. Afterwards the id answers 404. The processed duration is still billed.",
        "responses": {
          "200": {
            "description": "Transcript deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/DeletedRecognitionJob"
                    },
                    {
                      "type": "object",
                      "required": [
                        "transcription_id"
                      ],
                      "properties": {
                        "transcription_id": {
                          "type": "string"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/recognition/uploads": {
      "post": {
        "tags": [
          "recognition"
        ],
        "summary": "Create a presigned upload for a transcription job",
        "operationId": "createRecognitionUpload",
        "description": "Reserves a job row and returns a presigned R2 `PUT` URL that the client uses to upload the source file directly (expiry scales with `size_bytes`, from 30 minutes to 4 hours). On a successful PUT, call `POST /recognition/jobs/{job_id}/start` to enqueue transcription. Anonymous callers are allowed up to 25 MB; authed callers go up to the deployment cap. Send an `Idempotency-Key` header to make the call safe to retry, and `webhook_id` to have delivery survive a lost `…/start`.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUploadRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent replay: the `Idempotency-Key` matched a job you already created, and nothing new was created. `idempotent_replay` is true.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateUploadResponse"
                }
              }
            }
          },
          "201": {
            "description": "Job row created and presigned PUT URL issued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateUploadResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "description": "`webhook_not_found`: the `webhook_id` is not an active subscription of yours.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "`idempotency_conflict`: the `Idempotency-Key` was already used for a different upload (`filename`, `content_type` or `size_bytes` differ). A key identifies one file; use a new key for a new file.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          }
        }
      }
    },
    "/recognition/jobs": {
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "List recent transcription jobs",
        "operationId": "listRecognitionJobs",
        "description": "Returns recent jobs owned by the caller. Most-recent first. Requires authentication. By default only upload-driven jobs (`source=file`) are listed; pass `source` to list live-microphone sessions or Google Meet / Microsoft Teams integration jobs instead, or `source=all` for everything.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "description": "`YYYY-MM` — scopes the listing to jobs created in that calendar month (UTC).",
            "schema": {
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}$",
              "examples": [
                "2026-07"
              ]
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Which surface produced the jobs: `file` (uploads), `live` (browser-mic sessions), `meet` / `teams` (meeting integrations), or `all`. A value outside the enum is rejected with 400 rather than quietly falling back to the default.",
            "schema": {
              "type": "string",
              "enum": [
                "file",
                "live",
                "meet",
                "teams",
                "all"
              ],
              "default": "file"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Recognition job summaries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "jobs",
                    "limit",
                    "offset",
                    "source",
                    "has_more"
                  ],
                  "properties": {
                    "jobs": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RecognitionJobSummary"
                      }
                    },
                    "limit": {
                      "type": "integer",
                      "description": "Page size applied."
                    },
                    "offset": {
                      "type": "integer",
                      "description": "Offset applied."
                    },
                    "month": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Month filter applied, if any."
                    },
                    "source": {
                      "type": "string",
                      "enum": [
                        "file",
                        "live",
                        "meet",
                        "teams",
                        "all"
                      ],
                      "description": "Source filter applied."
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "True when the page came back full, i.e. another page may exist — request it with `offset + limit`."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/recognition/jobs/{job_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "Get a transcription job",
        "operationId": "getRecognitionJob",
        "description": "Returns the current state of a transcription job. Poll this until `state` is one of `succeeded`, `failed`, or `cancelled`. On `succeeded`, `result` carries the transcript; on `failed`, `error` is populated.\n\nA recording long enough to be split is transcribed as several part jobs, and this endpoint answers for the whole recording by default (`view=group`): `state` is terminal only once every part is, `result` is the parts stitched onto one timeline with a unified speaker roster, and `processed_duration_seconds` sums what was actually decoded. Check `is_complete` before treating a transcript as the full recording, and compare `processed_duration_seconds` with `original_duration_seconds` to confirm nothing was left out. Pass `view=part` to read this one job row instead.\n\nPolling the primary job also nudges its unfinished parts along, so one poll loop on one id is enough.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/JobView"
          }
        ],
        "responses": {
          "200": {
            "description": "Job status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecognitionJobStatus"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "recognition"
        ],
        "summary": "Cancel or delete a transcription job",
        "operationId": "deleteRecognitionJob",
        "description": "Without `purge`, cancels a job that is still running and keeps it, with its upload (unless it was created with `retain: false`), so it can be restarted; a job already finished is 409 `invalid_state`.\n\nWith `purge=true`, deletes the job for good, whatever its state: any work still running is cancelled, the uploaded file and the playback copy are deleted, and the transcript, edits, summaries, filename and metadata are erased. A split recording is deleted as a whole. A file whose upload finishes after the delete is removed about 12 h after the delete. Afterwards the job id answers 404. While a `…/start` for the job is still being processed the delete is 409 `start_in_progress`; retry it a moment later. Requires an API key or a session; the processed duration is still billed.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "purge",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            },
            "description": "`true` deletes the job for good."
          }
        ],
        "responses": {
          "200": {
            "description": "Job cancelled, or deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": [
                        "job_id",
                        "state"
                      ],
                      "properties": {
                        "job_id": {
                          "type": "string"
                        },
                        "state": {
                          "type": "string",
                          "enum": [
                            "cancelled"
                          ]
                        }
                      }
                    },
                    {
                      "$ref": "#/components/schemas/DeletedRecognitionJob"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/recognition/jobs/{job_id}/media": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "delete": {
        "tags": [
          "recognition"
        ],
        "summary": "Delete a job’s audio, keep the text",
        "operationId": "deleteRecognitionJobMedia",
        "description": "Deletes the uploaded file, the playback copy and every other stored audio or video of the job — the whole recording when it was split — and keeps the transcript, edits and summaries. Afterwards `media_deleted_at` is set on the job, and asking for its audio answers 410 `media_deleted`; the job cannot be restarted. Idempotent: a job whose audio is already gone answers 204 again. While any part is still running the delete is 409 `invalid_state`. Requires an API key, an OAuth token or a session; a job that is not yours answers 404.",
        "security": [
          {
            "XiApiKey": []
          }
        ],
        "responses": {
          "204": {
            "description": "Audio deleted (or already gone)."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/recognition/jobs/{job_id}/start": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "post": {
        "tags": [
          "recognition"
        ],
        "summary": "Start a transcription job after upload",
        "operationId": "startRecognitionJob",
        "description": "Call after the presigned R2 PUT has landed. Enqueues the job and transitions it from `uploading` to `pending`. Returns immediately; poll `GET /recognition/jobs/{job_id}` for progress, or pass `webhook: true` with a `webhook_id` to have the finished transcript delivered instead.\n\nThere is no 60-minute limit. A recording longer than the split threshold (1 h for Estonian, 45 min for other languages on this deployment) is transcribed as several windowed part jobs, up to 24 parts — roughly 24 hours of audio. The response tells you what happened: `part_count`, `group_id` and `part_job_ids`. Nothing about the polling flow changes, because `GET /recognition/jobs/{job_id}` answers for the whole recording.\n\nSend an `Idempotency-Key` header to make the call safe to retry: replaying the key returns the job that attempt started rather than starting — and charging for — a second one. The replay answers the same way even after that job has failed or been cancelled; to run it again deliberately, send a new key.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartJobRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Job enqueued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StartJobResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`invalid_state`: the job is already started (or is a split multi-part job, which cannot be restarted — upload again). `upload_missing`: no object has been PUT to the upload URL yet. `start_in_progress`: another start request for this same job is being processed right now — a concurrent duplicate; poll `GET /recognition/jobs/{job_id}`, or retry in a moment. A duplicate that carries the same `Idempotency-Key` as the request in flight waits for it briefly and replays its response instead.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "The job’s audio has been deleted — `media_deleted` when you deleted it, `media_expired` when the retention rules did. The transcript is kept; upload the file again to transcribe it anew.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/recognition/jobs/{job_id}/transcript": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "Download the finished transcript of the whole recording",
        "operationId": "getRecognitionTranscript",
        "description": "Renders the finished transcript as a single document, in the format you ask for. Always whole-recording: given any part of an auto-split recording it renders the group — absolute timestamps, one speaker roster, no stitching left to you. Speaker names you have saved (in the app or via the transcript editor) are used in place of `SPEAKER_00`-style labels.\n\nAnswers 409 `transcript_not_ready` while any part is still running, rather than handing back half a recording that looks complete.\n\nThe response carries an `ETag`. Send it back as `If-None-Match` to revalidate: a 304 means the transcript has not changed since (no edit, no speaker rename), and costs neither you nor us a re-download. `Cache-Control: private, no-cache` — cache it, but ask first.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "`json` (default) — the combined result with `segments[]`, absolute timestamps and per-word timings. `segmented_json` — speaker-paragraph JSON, the shape the app’s own export writes. `txt` — `Speaker: text` lines. `md` — Markdown with a timestamped heading per speaker turn. `srt` / `vtt` — subtitles.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "segmented_json",
                "txt",
                "md",
                "srt",
                "vtt"
              ],
              "default": "json"
            }
          },
          {
            "name": "download",
            "in": "query",
            "required": false,
            "description": "`true` sets `Content-Disposition: attachment` so a browser saves the file instead of displaying it.",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "required": false,
            "description": "The `ETag` of a transcript you already hold. Answers 304 with no body when it is still current.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The combined transcript.",
            "headers": {
              "ETag": {
                "description": "Validator for this rendering; changes when the transcript does.",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "application/x-subrip": {
                "schema": {
                  "type": "string"
                }
              },
              "text/vtt": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "Not modified: the `If-None-Match` you sent still matches. No body."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "The recording is not finished (`transcript_not_ready`) or produced no text (`transcript_empty`).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          }
        }
      }
    },
    "/recognition/speakers": {
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "List saved speakers",
        "operationId": "listSpeakers",
        "description": "Returns the caller’s saved speaker library — voiceprints enrolled from earlier diarized transcriptions and matched automatically when `speaker_recognition` is requested.",
        "responses": {
          "200": {
            "description": "Saved speakers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "speakers"
                  ],
                  "properties": {
                    "speakers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpeakerProfile"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "recognition"
        ],
        "summary": "Save a speaker from a finished job",
        "operationId": "enrollSpeaker",
        "description": "Enrolls a voiceprint from a succeeded diarized job that ran with speaker recognition enabled. `speakerLabel` is the raw diarization label (e.g. `SPEAKER_00`). The voiceprint is biometric data: it is stored only on this explicit call and can be deleted at any time via `DELETE /recognition/speakers/{id}`. No audio is stored or re-processed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "jobId",
                  "speakerLabel",
                  "name"
                ],
                "properties": {
                  "jobId": {
                    "type": "string"
                  },
                  "speakerLabel": {
                    "type": "string",
                    "examples": [
                      "SPEAKER_00"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Speaker saved.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "speaker"
                  ],
                  "properties": {
                    "speaker": {
                      "$ref": "#/components/schemas/SpeakerProfile"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          }
        }
      }
    },
    "/recognition/speakers/voiceprints": {
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "Export the saved speakers with their voiceprints",
        "operationId": "exportSpeakerVoiceprints",
        "description": "Same library as `GET /recognition/speakers`, plus the raw voiceprint vectors, for callers that do the matching themselves — e.g. a meeting daemon that names speakers before summarizing without mirroring the recording into Jutusta. The vectors are biometric data: the response is scoped to the caller and is never cached.",
        "responses": {
          "200": {
            "description": "Saved speakers with vectors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "speakers"
                  ],
                  "properties": {
                    "speakers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpeakerVoiceprint"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/recognition/speakers/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Saved speaker id."
        }
      ],
      "patch": {
        "tags": [
          "recognition"
        ],
        "summary": "Rename a saved speaker",
        "operationId": "renameSpeaker",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Speaker renamed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "speaker"
                  ],
                  "properties": {
                    "speaker": {
                      "$ref": "#/components/schemas/SpeakerProfile"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "recognition"
        ],
        "summary": "Delete a saved speaker",
        "operationId": "deleteSpeaker",
        "description": "Permanently deletes the voiceprint (hard delete of the biometric data). Future transcriptions will no longer recognise this speaker.",
        "responses": {
          "200": {
            "description": "Speaker deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/recognition/dictionaries": {
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "List ASR dictionaries",
        "operationId": "listDictionaries",
        "description": "Dictionaries are named lists of terms — names, products, jargon — that file transcription is corrected towards (`POST /recognition/jobs/{job_id}/start` and `POST /speech-to-text` take a `dictionary_id`). At most one dictionary per account is the default; it applies automatically whenever a request omits `dictionary_id`.",
        "responses": {
          "200": {
            "description": "The caller’s dictionaries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "dictionaries"
                  ],
                  "properties": {
                    "dictionaries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DictionarySummary"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "recognition"
        ],
        "summary": "Create an ASR dictionary",
        "operationId": "createDictionary",
        "description": "Terms are stored in their base (nominative) form; Estonian inflection is handled by the recognizer. Terms are deduplicated case-insensitively and their variants merged. `is_default: true` makes this the account default and clears the flag on the previous one.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DictionaryInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Dictionary created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "dictionary"
                  ],
                  "properties": {
                    "dictionary": {
                      "$ref": "#/components/schemas/Dictionary"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/recognition/dictionaries/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Dictionary id (`dict_…`)."
        }
      ],
      "get": {
        "tags": [
          "recognition"
        ],
        "summary": "Get an ASR dictionary",
        "operationId": "getDictionary",
        "responses": {
          "200": {
            "description": "The dictionary with its entries.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "dictionary"
                  ],
                  "properties": {
                    "dictionary": {
                      "$ref": "#/components/schemas/Dictionary"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "patch": {
        "tags": [
          "recognition"
        ],
        "summary": "Update an ASR dictionary",
        "operationId": "updateDictionary",
        "description": "Partial update. `entries` replaces the whole list. Jobs already started keep the terms they were started with.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "entries": {
                    "type": "array",
                    "maxItems": 2000,
                    "items": {
                      "$ref": "#/components/schemas/DictionaryEntryInput"
                    }
                  },
                  "is_default": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Dictionary updated.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "dictionary"
                  ],
                  "properties": {
                    "dictionary": {
                      "$ref": "#/components/schemas/Dictionary"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "delete": {
        "tags": [
          "recognition"
        ],
        "summary": "Delete an ASR dictionary",
        "operationId": "deleteDictionary",
        "description": "Jobs that referenced it stay readable; a later restart of such a job runs without a dictionary.",
        "responses": {
          "200": {
            "description": "Dictionary deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "tags": [
          "webhooks"
        ],
        "summary": "List webhook subscriptions",
        "operationId": "listWebhooks",
        "responses": {
          "200": {
            "description": "Active webhook subscriptions for the caller.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhooksList"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "webhooks"
        ],
        "summary": "Create a webhook subscription",
        "operationId": "createWebhook",
        "description": "Registers a webhook endpoint. The response includes the signing `secret` exactly once — store it server-side and use it to verify the `ElevenLabs-Signature` header on incoming deliveries.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookCreated"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/webhooks/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "Webhook subscription id (returned at creation as `webhook_id`)."
        }
      ],
      "delete": {
        "tags": [
          "webhooks"
        ],
        "summary": "Revoke a webhook subscription",
        "operationId": "deleteWebhook",
        "responses": {
          "200": {
            "description": "Subscription revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "webhook_id",
                    "revoked"
                  ],
                  "properties": {
                    "webhook_id": {
                      "type": "string"
                    },
                    "revoked": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/recognition/jobs/{job_id}/summary": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobId"
        }
      ],
      "get": {
        "tags": [
          "summaries"
        ],
        "summary": "List summaries for a job",
        "operationId": "listJobSummaries",
        "description": "Returns every summary generated for the job so far, oldest first. A job can carry multiple summaries — typically one per template the caller has run.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Existing summaries for the job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummariesListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      },
      "post": {
        "tags": [
          "summaries"
        ],
        "summary": "Generate a summary",
        "operationId": "generateJobSummary",
        "description": "Generates a new summary for a finished transcription job using the chosen template. If `templateId` is omitted the caller’s default template is used (see `GET /summary-templates`). The job must be in `state: \"succeeded\"`. Each call creates a fresh summary row — there is no implicit dedup, so it is the caller’s responsibility to avoid duplicate work if regenerating with the same template.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SummaryGenerateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Summary generated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SummaryResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/summary-templates": {
      "get": {
        "tags": [
          "summaries"
        ],
        "summary": "List summary templates",
        "operationId": "listSummaryTemplates",
        "description": "Returns the catalog of summary templates plus the caller’s default. Templates are catalog-defined — there is no create or delete here.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Template catalog and caller’s default.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplatesCatalogResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "summaries"
        ],
        "summary": "Set default summary template",
        "operationId": "setDefaultSummaryTemplate",
        "description": "Sets the caller’s preferred default template. Future `POST /recognition/jobs/{job_id}/summary` calls without a `templateId` will use this template.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetDefaultTemplateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated catalog with new default.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemplatesCatalogResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/summarize": {
      "post": {
        "tags": [
          "summaries"
        ],
        "summary": "Summarize a transcript",
        "operationId": "summarizeText",
        "description": "Summarizes a transcript the caller sends, with the chosen template, and returns the summary. For transcripts that are not a transcription job here — for jobs, use `POST /recognition/jobs/{job_id}/summary`, which also saves the summary.\n\n**Kept only briefly.** The text is held until its summary is written, then deleted. The summary is deleted once it has been returned, or an hour after it was written if it is never collected — with `retain: false`, within about 10 minutes.\n\n**Input.** Plain text up to 1 MiB (UTF-8), ideally one `Speaker: text` line per turn; the summary names speakers as the text does. A long text is summarized in parts and then as a whole, so none of it is dropped. `language` picks the prompt language (`et` gets the Estonian prompt; anything else, or none, the multilingual one). If `templateId` is omitted the caller’s default template is used (see `GET /summary-templates`); an id that is not in the catalog also falls back to the default, and the response’s `templateId` says which template ran.\n\n**Timing.** The request waits until the summary is written, which can take minutes for a long transcript. If it is not done within about 10 minutes, the answer is `202` with the run and a `Location` header: poll `GET /summarize/{run_id}` until it answers `200`.\n\n**Billing.** One AI summary credit per request, checked before the request is accepted (`402`) and spent once the summary is written. Every request is charged, including a repeat of the same text.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TextSummaryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Summary written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TextSummaryResponse"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/TextSummaryPending"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/summarize/{run_id}": {
      "get": {
        "tags": [
          "summaries"
        ],
        "summary": "Get a pending text summary",
        "operationId": "getTextSummary",
        "description": "Collects a summary that `POST /summarize` answered `202` for. `202` again while it is still being written; `200` with the summary once it is, after which the run is deleted and asking again answers `404`. A failed run answers `502` once. A run nobody collects is deleted an hour after it settled.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "parameters": [
          {
            "name": "run_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`run.id` from the `202` answer."
          }
        ],
        "responses": {
          "200": {
            "description": "Summary written.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TextSummaryResponse"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/TextSummaryPending"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/translate/chunk": {
      "post": {
        "tags": [
          "translate"
        ],
        "summary": "Translate a transcript chunk",
        "operationId": "translateChunk",
        "description": "Translates the `new_source` chunk from `source` to `target`, given the tail of the translation rendered so far as `previous` context. The response carries `appended` — text the caller concatenates to whatever it has already shown. Earlier translation is never rewritten; the model is instructed not to repeat or revise it. Useful for live transcripts where ASR text grows in place. Same-language requests short-circuit and echo `new_source`.\n\n**Streaming.** Send `Accept: text/event-stream` (or `?stream=true`) to receive translation as a token-by-token SSE stream instead of waiting for the full chunk. The wire format is:\n\n```\nevent: delta\ndata: {\"appended\":\"Hello\"}\n\nevent: delta\ndata: {\"appended\":\", how are you?\"}\n\nevent: done\ndata: {\"model\":\"@cf/mistralai/mistral-small-3.1-24b-instruct\",\"source\":\"et\",\"target\":\"en\"}\n```\n\nConcatenate `appended` from each `delta` frame to render translation live. `event: done` terminates the stream cleanly. On model failure or rate-limit, the server emits one `event: error\\ndata: {\"code\":\"…\",\"message\":\"…\"}` frame before closing. The default (JSON) response shape is unchanged.\n\n**Billing.** Charged like live translation: `new_source` is converted to the spoken time it represents (750 characters ≈ 1 minute) and billed as translation minutes at 1 credit per 30 seconds — i.e. 1 credit per 375 characters, rounded up per request. Credits are checked before the model runs (`402`) and spent once the translation is delivered. Same-language requests are free.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranslateChunkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Translated chunk to append. JSON by default; `text/event-stream` when negotiated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranslateChunkResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "Server-Sent Events stream of `delta` / `done` / `error` frames. Each `delta` frame carries `{ \"appended\": \"<text>\" }`; concatenate across frames. The terminal `done` frame carries `{ \"model\", \"source\", \"target\" }`.",
                  "example": "event: delta\ndata: {\"appended\":\"Hello\"}\n\nevent: delta\ndata: {\"appended\":\", world.\"}\n\nevent: done\ndata: {\"model\":\"@cf/mistralai/mistral-small-3.1-24b-instruct\",\"source\":\"et\",\"target\":\"en\"}\n\n"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          }
        }
      }
    },
    "/audio-detection": {
      "post": {
        "tags": [
          "audio-detection"
        ],
        "summary": "Check audio for the AI-generated mark",
        "operationId": "detectAiAudioMark",
        "description": "Every clip Jutusta synthesizes carries an inaudible watermark saying it is AI-generated (EU AI Act Art. 50(2)). This endpoint reads it back from any audio or video file. It is free and needs no key; callers without one are rate-limited per IP address. Nothing is stored. Send the file as the request body, or as multipart/form-data in the `audio` field. Up to 50 MB; the first 10 minutes are read.\n\n`detected: false` means only that this mark was not found — not that the speech is human. The mark survives ordinary re-encoding (MP3, AAC, Opus), resampling and telephone audio, but a speed or pitch change removes it.",
        "security": [
          {},
          {
            "XiApiKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "required": [
                  "audio"
                ],
                "properties": {
                  "audio": {
                    "type": "string",
                    "format": "binary"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Detection result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AudioDetectionResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": [
          "models"
        ],
        "summary": "List models",
        "operationId": "listModels",
        "security": [],
        "responses": {
          "200": {
            "description": "Available models.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelsList"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "XiApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "xi-api-key",
        "description": "Personal API key issued at `/app/developers`. Also accepted as `Authorization: Bearer sk_jt_…`."
      }
    },
    "parameters": {
      "VoiceId": {
        "name": "voice_id",
        "in": "path",
        "required": true,
        "description": "Voice identifier. Pick a preset id from the dropdown — or pass a voice clone id you created via `POST /voices/add` (clone ids look like `vc_xxx`). The full preset list is also available at `GET /voices`.",
        "schema": {
          "type": "string",
          "enum": [
            "anette",
            "johanna",
            "kaisa",
            "lisandra",
            "marleen",
            "mirtel",
            "karoliina",
            "kertu",
            "laura",
            "getter",
            "teele",
            "jaanika",
            "evelin",
            "kerli",
            "kristel",
            "margit",
            "merike",
            "signe",
            "terje",
            "ulle",
            "sirje",
            "aili",
            "anu",
            "malle",
            "pille",
            "reet",
            "artur",
            "mattias",
            "robin",
            "romet",
            "erko",
            "joosep",
            "kaspar",
            "oskar",
            "gregor",
            "karl",
            "sten",
            "gert",
            "raul",
            "silver",
            "meelis",
            "veiko",
            "ahto",
            "kaido",
            "lauri",
            "martin",
            "ragnar",
            "tanel",
            "heiki",
            "vello",
            "ulo",
            "juri",
            "peeter",
            "mari",
            "liina",
            "kadri",
            "tiina",
            "eve",
            "annika",
            "katrin",
            "kart",
            "piret",
            "jaan",
            "mart",
            "andres",
            "priit",
            "tarmo",
            "rein",
            "urmas",
            "tonu",
            "marko",
            "raivo",
            "kaur",
            "siim",
            "taavi",
            "ott",
            "henri",
            "margus",
            "sander",
            "toomas",
            "indrek",
            "madis",
            "kalev",
            "tuuli",
            "heli",
            "triin",
            "maarja",
            "linda",
            "karin",
            "anneli",
            "karim-ar",
            "aytac-az",
            "stoyan-bg",
            "edin-bs",
            "jordi-ca",
            "jan-cs",
            "mikkel-da",
            "maximilian-de",
            "nikos-el",
            "oliver-en",
            "mateo-es",
            "kristjan-et",
            "tapio-fi",
            "antoine-fr",
            "brais-gl",
            "yonatan-he",
            "arjun-hi",
            "ivan-hr",
            "bence-hu",
            "budi-id",
            "lorenzo-it",
            "hiroshi-ja",
            "minjun-ko",
            "justas-lt",
            "janis-lv",
            "goran-mk",
            "ahmad-ms",
            "daan-nl",
            "erik-no",
            "piotr-pl",
            "joao-pt",
            "andrei-ro",
            "aleksei-ru",
            "tomas-sk",
            "luka-sl",
            "nikola-sr",
            "lars-sv",
            "arun-ta",
            "somchai-th",
            "mehmet-tr",
            "taras-uk",
            "faisal-ur",
            "minh-vi",
            "wei-zh",
            "james-en",
            "william-en",
            "henry-en",
            "edward-en",
            "charles-en",
            "thomas-en",
            "sophie-en",
            "emily-en",
            "hannah-en",
            "layla-ar",
            "aysel-az",
            "maria-bg",
            "selma-bs",
            "nuria-ca",
            "klara-cs",
            "freja-da",
            "hanna-de",
            "maria-el",
            "lucia-es",
            "sini-fi",
            "elise-fr",
            "tamar-he",
            "ananya-hi",
            "ana-hr",
            "eszter-hu",
            "dewi-id",
            "sakura-ja",
            "soyeon-ko",
            "egle-lt",
            "elina-lv",
            "marija-mk",
            "nur-ms",
            "eva-nl",
            "ingrid-no",
            "aleksandra-pl",
            "ines-pt",
            "ioana-ro",
            "anastasia-ru",
            "eva-sk",
            "maja-sl",
            "jelena-sr",
            "linnea-sv",
            "anjali-ta",
            "suda-th",
            "aylin-tr",
            "iryna-uk",
            "aisha-ur",
            "mai-vi",
            "lin-zh",
            "mikhail-ru",
            "bohdan-uk",
            "klaus-de",
            "juhani-fi",
            "dmitri-ru",
            "andriy-uk",
            "hans-de",
            "mikko-fi",
            "olga-ru",
            "oksana-uk",
            "anna-de",
            "helmi-fi",
            "yulia-uk",
            "lena-de",
            "riikka-fi",
            "tatyana-ru",
            "daria-uk",
            "greta-de",
            "pirjo-fi",
            "sofia-it",
            "chiara-it",
            "arianna-it",
            "ilaria-it",
            "francesca-it",
            "andrea-it",
            "roberto-it",
            "marco-it",
            "simone-it",
            "paolo-it"
          ],
          "default": "kerli",
          "example": "kerli"
        },
        "example": "kerli"
      },
      "OutputFormat": {
        "name": "output_format",
        "in": "query",
        "required": false,
        "description": "Requested audio format. Only wav / pcm variants are honoured today; mp3 variants return 415.",
        "schema": {
          "type": "string",
          "enum": [
            "wav",
            "pcm_16000",
            "pcm_22050",
            "pcm_24000",
            "pcm_44100"
          ]
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Optional client-generated key that makes this call safe to retry. Replaying the same key with the same caller returns the original job instead of creating a second one, so a request that timed out or lost its connection can simply be sent again. Keys are scoped to your account and never expire. Ignored for anonymous callers. Each call keeps its own key: the one sent to `POST /recognition/uploads` and the one sent to `POST /recognition/jobs/{job_id}/start` are matched independently. A key replayed with a different request body is a 409 `idempotency_conflict`, not a replay.",
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      },
      "JobView": {
        "name": "view",
        "in": "query",
        "required": false,
        "description": "`group` (the default) answers for the whole recording: `state` turns terminal only once every part is done, `result` is the stitched transcript on one timeline, and durations and progress are summed. `part` answers for this job row alone — the first window of a split recording, with timestamps starting at 0. Identical either way for a recording that was not split.",
        "schema": {
          "type": "string",
          "enum": [
            "group",
            "part"
          ],
          "default": "group"
        }
      },
      "JobId": {
        "name": "job_id",
        "in": "path",
        "required": true,
        "description": "Recognition job id returned by `POST /recognition/uploads`.",
        "schema": {
          "type": "string"
        }
      },
      "StreamInputApiKeyQuery": {
        "name": "xi_api_key",
        "in": "query",
        "required": false,
        "description": "Fallback API-key transport for the WebSocket `stream-input` endpoint. Browsers cannot set custom headers on a `WebSocket()` upgrade, so the key may be passed on the URL. The key is stripped from the URL before the request reaches our application logs; a URL can still be recorded by proxies and client-side tooling, so server-side clients should use the `Authorization` or `xi-api-key` header instead. Either spelling (`xi_api_key` or `xi-api-key`) is accepted.",
        "schema": {
          "type": "string"
        }
      },
      "StreamInputLanguageQuery": {
        "name": "language",
        "in": "query",
        "required": false,
        "description": "Target language the synthesized speech will be in (ISO-639-1 code or English name). Defaults to Estonian when omitted. Languages the streaming engine speaks are rendered there from the voice's reference anchor; any other language is routed to the expressive engine, which re-renders the same voice in the target language at higher latency.",
        "schema": {
          "type": "string"
        }
      },
      "StreamInputLanguageHeader": {
        "name": "X-Speak-Language",
        "in": "header",
        "required": false,
        "description": "Same as the `language` query parameter, for server-side clients that prefer headers. When both are set, the query parameter wins.",
        "schema": {
          "type": "string"
        }
      },
      "StreamInputSeedQuery": {
        "name": "seed",
        "in": "query",
        "required": false,
        "description": "Sampling seed for every chunk of the session, 0–2147483647. Omitted, a fixed server-side default applies. A seed reproduces a take only for the same text sent as the same frames: chunks are cut where your frames, flushes and the buffer rules put them, so the same text framed differently renders differently. Pass a different seed for a different take. Any other value — a negative, a fraction, a larger number, a non-numeric or empty value — refuses the upgrade with `400 invalid_seed`. Best effort: see `x-compatibility`.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 2147483647
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "Out of credits for this feature (`insufficient_credits`; org members may see `organization_cap_exceeded` / `organization_unavailable`). The error carries an `upsell` object with the shortfall and the credit packs that top up an active subscription. When an organization or company pays for the caller, `upsell.billedTo` is `organization` and the error means its credits ran out: usage does not fall back to the caller's own credits unless the API key is set to bill personally.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Malformed request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Requested output format not supported by this deployment.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UpstreamError": {
        "description": "Upstream synthesis engine failed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Conflict": {
        "description": "Resource conflict (e.g. duplicate voice name).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "Request body exceeds the deployment limit.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TextSummaryPending": {
        "description": "Still being written. Poll the `Location` URL (`GET /summarize/{run_id}`); `Retry-After` suggests how long to wait.",
        "headers": {
          "Location": {
            "schema": {
              "type": "string"
            },
            "description": "Where to poll for the summary."
          },
          "Retry-After": {
            "schema": {
              "type": "integer"
            },
            "description": "Seconds to wait before polling."
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/TextSummaryRunPending"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "object",
            "required": [
              "status",
              "message"
            ],
            "properties": {
              "status": {
                "type": "string",
                "example": "unauthorized"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Voice": {
        "type": "object",
        "required": [
          "voice_id",
          "name",
          "category"
        ],
        "properties": {
          "voice_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "premade",
              "cloned"
            ],
            "description": "ElevenLabs-style category. `cloned` voices are owned by the API-key holder."
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "preview_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Public URL for `premade` voices; for `cloned` voices the URL requires the same `xi-api-key` (or session cookie) used to list voices."
          },
          "labels": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Key/value metadata. Every preset has `gender` and `language`. The Estonian catalogue voices add `age` (`young`, `adult`, `mature`), `pitch` (`low`, `medium`, `high`), `pace` (`slow`, `medium`, `fast`) and `use_cases`, a comma-separated list of `audiobooks`, `elearning`, `documentary`, `meditation`, `children`, `assistant`, `announcements`, `podcasts`, `characters`. Earlier Estonian voices that are no longer offered in the app carry `legacy: \"true\"`; they keep working with the same `voice_id`."
          }
        }
      },
      "AddVoiceRequest": {
        "type": "object",
        "required": [
          "name",
          "files"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 60,
            "description": "Display name. Must be unique among the caller’s active clones."
          },
          "files": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "binary"
            },
            "description": "Reference audio files. The first file is used; additional files are ignored. 6–45 seconds of clean speech (30–45 s gives the closest likeness), max 16 MB."
          },
          "audio": {
            "type": "string",
            "format": "binary",
            "description": "Legacy alias for the first item in `files`. Ignored if `files` is present."
          },
          "language": {
            "type": "string",
            "description": "ISO language code of the reference audio (defaults to `et`). Influences the preview generated for the clone.",
            "examples": [
              "et",
              "en"
            ]
          },
          "previewText": {
            "type": "string",
            "description": "Sentence the sidecar speaks back as the clone preview. Defaults to a language-appropriate canned sentence."
          },
          "refText": {
            "type": "string",
            "description": "Optional transcript of the reference audio. When omitted, the sidecar transcribes it."
          }
        }
      },
      "AddVoiceResponse": {
        "type": "object",
        "required": [
          "voice_id",
          "requires_verification"
        ],
        "properties": {
          "voice_id": {
            "type": "string"
          },
          "requires_verification": {
            "type": "boolean",
            "description": "Always `false` on this deployment; field retained for SDK compatibility."
          }
        }
      },
      "VoicesList": {
        "type": "object",
        "required": [
          "voices"
        ],
        "properties": {
          "voices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Voice"
            }
          }
        }
      },
      "VoiceSettings": {
        "type": "object",
        "description": "ElevenLabs voice-settings object. Accepted for SDK compatibility; no field is applied today. `speed` is validated (clamped to [0.5, 2]) but the streaming engine has no tempo control, so it does not change the output.",
        "properties": {
          "stability": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "similarity_boost": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "style": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "use_speaker_boost": {
            "type": "boolean"
          },
          "speed": {
            "type": "number",
            "minimum": 0.5,
            "maximum": 2
          }
        }
      },
      "TextToSpeechRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 8000,
            "description": "Input text to synthesize. Hard cap of 8000 characters (≈ 6 min of audio). Inputs above this return `400 text_too_long`. Splitting longer scripts into separate requests is the supported pattern."
          },
          "model_id": {
            "type": "string",
            "examples": [
              "jutusta_v1",
              "jutusta_v2"
            ],
            "description": "`jutusta_v2`: always jutusta v2 (Estonian, non-streaming endpoint only). Any other value, `jutusta_v1` included, or omitted: picked per request — `jutusta_v2` when the text has tags or `instructions` is set, `jutusta_v1` otherwise."
          },
          "language_code": {
            "type": "string",
            "description": "ISO language code (e.g. `et`, `en`). Defaults to voice language.",
            "examples": [
              "et",
              "en"
            ]
          },
          "seed": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 2147483647,
            "description": "Sampling seed, 0–2147483647. Omitted or `null`, a fixed server-side default applies, so an identical request returns the same audio; send a different seed to get a different take of the same text. Send the same seed with every request to keep a cloned voice steady across the many requests of a long dialogue. A value outside the range, a fraction or a string returns `400 invalid_seed`. Best effort: see `x-compatibility` for when the same seed can still produce different audio."
          },
          "voice_settings": {
            "$ref": "#/components/schemas/VoiceSettings"
          },
          "previous_text": {
            "type": "string"
          },
          "next_text": {
            "type": "string"
          },
          "sentence_chunking": {
            "type": "boolean",
            "default": true,
            "description": "When `true` the Worker splits `text` into sentence-sized segments, synthesizes each segment separately, and stitches the PCM into a single WAV (streamed on `/text-to-speech/{voice_id}/stream`, fully buffered on the non-stream endpoint). This lowers time-to-first-audio for long inputs and keeps long renders stable, at the cost of small extra pauses at segment boundaries. Every engine chunks, so `false` is accepted for compatibility and has no effect."
          }
        }
      },
      "TextToSpeechBufferedRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TextToSpeechRequest"
          },
          {
            "type": "object",
            "properties": {
              "instructions": {
                "type": [
                  "string",
                  "null"
                ],
                "maxLength": 300,
                "description": "Estonian text only: how to deliver it, in Estonian or English (e.g. \"Calm and warm, like a bedtime storyteller.\"). Translated to English server-side. See the endpoint description for where it is accepted.",
                "examples": [
                  "Rahulikult ja soojalt, nagu õhtujutu lugeja."
                ]
              }
            }
          }
        ]
      },
      "StreamInputClientFrame": {
        "type": "object",
        "description": "JSON text frame sent by the client over the `stream-input` WebSocket. Mirrors the ElevenLabs stream-input protocol. Frames with no `text` field are ignored unless they carry `flush`, `cancel` or `voice_settings`.",
        "properties": {
          "text": {
            "type": "string",
            "description": "Text to append to the synth buffer. Use a literal single space (`\" \"`) on the first frame; an empty string (`\"\"`) flushes and ends the session."
          },
          "try_trigger_generation": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, force-synth the current buffer instead of waiting for a sentence boundary."
          },
          "flush": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, force-synth the buffered text immediately and keep the session open (ElevenLabs semantics). May be sent with or without a `text` field. To end the session, send `{\"text\": \"\"}` instead."
          },
          "cancel": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, drop the buffered text and every chunk not yet spoken, stop the audio being generated and keep the session open (barge-in). Acknowledged with `{\"audio\":null,\"cancelDone\":true}`. Applied before the frame's own `text`, so `{\"cancel\": true, \"text\": \"…\", \"flush\": true}` replaces the pending speech. Sent after the end-of-stream frame it only shortens the ending: `isFinal` and the close still follow. Not part of the ElevenLabs protocol."
          },
          "voice_settings": {
            "$ref": "#/components/schemas/VoiceSettings"
          },
          "xi_api_key": {
            "type": "string",
            "description": "Accepted in-frame for SDK compatibility and ignored — auth is resolved on the WebSocket upgrade."
          }
        }
      },
      "StreamInputAudioFrame": {
        "type": "object",
        "description": "Server → client audio frame. `audio` carries base64-encoded RAW PCM (s16le, 24 kHz, mono). Chunk frames carry `isFinal:false`. A `flush` closes with a `{\"audio\":null,\"flushDone\":true}` marker and a `cancel` is acknowledged with `{\"audio\":null,\"cancelDone\":true}` (session stays open in both cases); the terminal frame has `isFinal:true` and `audio:null`, followed by a clean close (code 1000).",
        "properties": {
          "audio": {
            "type": [
              "string",
              "null"
            ],
            "description": "Base64-encoded RAW PCM bytes (signed 16-bit little-endian, 24 kHz, mono). `null` on the `flushDone`, `cancelDone` and terminal frames."
          },
          "isFinal": {
            "type": "boolean",
            "description": "`true` on the terminal frame, just before the connection is closed cleanly. Absent on `flushDone` and `cancelDone` markers."
          },
          "flushDone": {
            "type": "boolean",
            "description": "`true` on the marker sent after a `flush` has fully drained its audio; the session stays open for the next response."
          },
          "cancelDone": {
            "type": "boolean",
            "description": "`true` on the acknowledgement of a `cancel`. No audio of the cancelled text follows it; the session stays open."
          }
        }
      },
      "StreamInputUpgradeError": {
        "type": "object",
        "required": [
          "error"
        ],
        "description": "Body of a refused WebSocket upgrade (a plain HTTP response, before any frame).",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "invalid_seed"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "StreamInputErrorFrame": {
        "type": "object",
        "required": [
          "error"
        ],
        "description": "Server → client error frame. Sent before a 1011 close when an upstream synthesis call fails mid-session.",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "upstream_error"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "Model": {
        "type": "object",
        "required": [
          "model_id",
          "name"
        ],
        "properties": {
          "model_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "can_do_text_to_speech": {
            "type": "boolean"
          },
          "can_do_voice_conversion": {
            "type": "boolean"
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "language_id",
                "name"
              ],
              "properties": {
                "language_id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "AudioDetectionResult": {
        "type": "object",
        "required": [
          "detected",
          "watermark",
          "segments",
          "duration_seconds",
          "truncated"
        ],
        "properties": {
          "detected": {
            "type": "boolean",
            "description": "The mark was found in the clip as a whole or in at least one stretch of it."
          },
          "watermark": {
            "type": "object",
            "required": [
              "method",
              "score",
              "threshold"
            ],
            "properties": {
              "method": {
                "type": "string",
                "enum": [
                  "perth"
                ]
              },
              "score": {
                "type": "number",
                "description": "Whole-clip score, 0 to 1."
              },
              "threshold": {
                "type": "number",
                "description": "Scores above this count as detected."
              }
            }
          },
          "segments": {
            "type": "array",
            "description": "Ten-second stretches, half overlapping, each with its own score. Empty for clips under about 15 seconds.",
            "items": {
              "type": "object",
              "required": [
                "start",
                "end",
                "score",
                "detected"
              ],
              "properties": {
                "start": {
                  "type": "number"
                },
                "end": {
                  "type": "number"
                },
                "score": {
                  "type": "number"
                },
                "detected": {
                  "type": "boolean"
                }
              }
            }
          },
          "duration_seconds": {
            "type": "number"
          },
          "truncated": {
            "type": "boolean",
            "description": "The file was longer than the detector reads; only its start was checked."
          }
        }
      },
      "ModelsList": {
        "type": "object",
        "required": [
          "models"
        ],
        "properties": {
          "models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Model"
            }
          }
        }
      },
      "SpeechToTextRequest": {
        "type": "object",
        "required": [
          "model_id"
        ],
        "description": "Multipart form. Exactly one of `file` or `cloud_storage_url` is required. Fields listed under `x-compatibility` are accepted for SDK compatibility and silently ignored.",
        "properties": {
          "model_id": {
            "type": "string",
            "description": "Accepted for SDK compatibility (e.g. `scribe_v1`, `scribe_v2`). The engine is the Jutusta ASR model regardless of value."
          },
          "file": {
            "type": "string",
            "format": "binary",
            "description": "Audio/video file, max 100 MB inline."
          },
          "cloud_storage_url": {
            "type": "string",
            "format": "uri",
            "description": "https URL to an audio/video file fetched server-side. Mutually exclusive with `file`."
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "description": "Alias of `cloud_storage_url`."
          },
          "language_code": {
            "type": "string",
            "description": "ISO-639-1 language code; `auto` for detection.",
            "examples": [
              "et",
              "en",
              "auto"
            ]
          },
          "diarize": {
            "type": "boolean",
            "default": false
          },
          "speaker_recognition": {
            "type": "boolean",
            "default": false,
            "description": "Jutusta extension. With `diarize=true`, matches diarized speakers against the saved speaker library of the account and adds a top-level `matched_speakers` object to the response. `words[].speaker_id` is never rewritten."
          },
          "timestamps_granularity": {
            "type": "string",
            "enum": [
              "none",
              "word",
              "character"
            ],
            "default": "word"
          },
          "webhook": {
            "type": "boolean",
            "default": false,
            "description": "When `true`, the response is `SpeechToTextWebhookResponse` and the transcription result is POSTed to the registered webhook URL on completion."
          },
          "webhook_id": {
            "type": "string",
            "description": "Required when `webhook=true`. Must reference an active subscription owned by the caller."
          },
          "webhook_metadata": {
            "type": "string",
            "description": "Opaque caller metadata (≤ 16 KB) round-tripped on the webhook payload."
          },
          "dictionary_id": {
            "type": "string",
            "description": "Jutusta extension. Id of an ASR dictionary (`GET /recognition/dictionaries`) whose terms the transcript is corrected towards. Omit to apply the account’s default dictionary, if one is set; send `none` to run without one. An id that is not the caller’s is 404 `dictionary_not_found`."
          },
          "llm_correction": {
            "type": "boolean",
            "default": false,
            "description": "Jutusta extension. `true` asks for LLM correction after transcription: a large language model reads the transcript (and the dictionary, if one applies) and fixes clearly misrecognized words, names above all. The model only proposes small replacements and each one is checked against the audio before it is applied; nothing is rewritten, added or removed. Off by default, Estonian only, and a request that sets it never takes the low-latency path. When the model is operated by an external provider, it runs only for an account that has already agreed to that: a private account by agreeing once in the Jutusta app, a company account by switching the optional LLM correction function on. Otherwise the transcript is returned without this correction. A request that sets it is always told what happened, in the `llm_correction` object of the response (`status`, `reason`, `message`). 503 `service_unavailable` when the deployment does not offer it. Only `true` and `false` (or `1`/`0`) are accepted."
          },
          "retain": {
            "type": "boolean",
            "default": true,
            "description": "Jutusta extension. `false` keeps nothing once the transcript is handed over: the synchronous response is the only copy, and with `webhook=true` the job is deleted once the delivery succeeded (or gave up). No playback copy is made and the audio is deleted within minutes of transcription ending. Only `true` and `false` (or `1`/`0`) are accepted."
          },
          "tag_audio_events": {
            "type": "boolean",
            "default": true,
            "description": "Accepted; currently ignored."
          },
          "num_speakers": {
            "type": "integer",
            "description": "Accepted; currently ignored."
          },
          "temperature": {
            "type": "number",
            "description": "Accepted; currently ignored."
          },
          "seed": {
            "type": "integer",
            "description": "Accepted; currently ignored."
          },
          "additional_formats": {
            "type": "string",
            "description": "JSON-encoded array of export-format requests, matching the ElevenLabs `additional_formats` field. Each element is an object with a `format` discriminator. Honoured formats: `srt`, `txt`, `segmented_json`; the generated files come back in the response `additional_formats` array. Other ElevenLabs formats (`docx`, `html`, `pdf`) are accepted-and-skipped, and the numeric segmentation knobs (`max_characters_per_line`, `max_segment_chars`, `max_segment_duration_s`, `segment_on_silence_longer_than_s`) are ignored — our subtitle chunker uses its own heuristic. `include_speakers` / `include_timestamps` are honoured for `txt` and inherent to `segmented_json`; `srt` always carries timecodes and does not embed speaker labels. `segmented_json` follows Jutusta's segments schema, not ElevenLabs' internal shape."
          }
        }
      },
      "SpeechToTextResponse": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/SpeechToTextChunkResponse"
          },
          {
            "$ref": "#/components/schemas/SpeechToTextWebhookResponse"
          }
        ]
      },
      "AdditionalFormat": {
        "type": "object",
        "required": [
          "requested_format",
          "file_extension",
          "content_type",
          "is_base64_encoded",
          "content"
        ],
        "properties": {
          "requested_format": {
            "type": "string",
            "example": "srt"
          },
          "file_extension": {
            "type": "string",
            "example": "srt"
          },
          "content_type": {
            "type": "string",
            "example": "application/x-subrip"
          },
          "is_base64_encoded": {
            "type": "boolean",
            "description": "Always `false` for the supported text formats (srt/txt/segmented_json); `content` is the raw file body."
          },
          "content": {
            "type": "string"
          }
        }
      },
      "SpeechToTextChunkResponse": {
        "type": "object",
        "required": [
          "language_code",
          "language_probability",
          "text",
          "words"
        ],
        "properties": {
          "language_code": {
            "type": "string",
            "example": "et"
          },
          "language_probability": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "text": {
            "type": "string"
          },
          "words": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpeechToTextWord"
            }
          },
          "channel_index": {
            "type": [
              "integer",
              "null"
            ]
          },
          "additional_formats": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/AdditionalFormat"
            },
            "description": "Generated export files for the `additional_formats` requested on the input. `null` when none were requested; an entry is present per honoured format (`srt`, `txt`, `segmented_json`)."
          },
          "transcription_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "entities": {
            "type": [
              "array",
              "null"
            ]
          },
          "audio_duration_secs": {
            "type": [
              "number",
              "null"
            ]
          },
          "matched_speakers": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "$ref": "#/components/schemas/SpeakerMatch"
            },
            "description": "Jutusta extension, present only when the job ran with `speaker_recognition=true`. Maps diarization labels (the `words[].speaker_id` values) to saved speakers that matched confidently."
          },
          "llm_correction": {
            "$ref": "#/components/schemas/LlmCorrectionStatus"
          }
        }
      },
      "LlmCorrectionStatus": {
        "type": [
          "object",
          "null"
        ],
        "description": "Jutusta extension. What became of a request for `llm_correction`. Present whenever the request set it and absent or `null` otherwise, so a correction that did not happen is stated rather than inferred from a missing field.",
        "required": [
          "requested",
          "status",
          "reason",
          "message",
          "edits"
        ],
        "properties": {
          "requested": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "applied",
              "partial",
              "skipped",
              "failed"
            ],
            "description": "`pending` until the job finishes; `applied` when the whole transcript was corrected (possibly with no edits); `partial` when only part of it could be; `skipped` when the correction did not run; `failed` when it was attempted and gave up. For `skipped` and `failed` the transcript is the uncorrected one."
          },
          "reason": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "agreement_required",
              "company_function_off",
              "not_enabled",
              "unsupported_language",
              "unavailable",
              "error",
              null
            ],
            "description": "Why, when `status` is not `applied` or `pending`. `agreement_required`: the account has not agreed to an external model (the account owner can agree once in the Jutusta app). `company_function_off`: the account’s company has not switched LLM correction on (an optional function in the company settings). `not_enabled`: the service does not offer it. `unsupported_language`: Estonian only. `unavailable`: the model or the cluster that ran the job could not do it; resubmitting may succeed. `error`: the stage failed."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "One English sentence saying what happened and what can be done about it, suitable for showing to a person or for an assistant to relay."
          },
          "edits": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Edits applied. `null` unless the correction ran, and on the combined result of a split recording (each part’s own result has its count)."
          }
        }
      },
      "SpeakerMatch": {
        "type": "object",
        "required": [
          "name",
          "confidence",
          "profileId"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Saved speaker name."
          },
          "confidence": {
            "type": "number",
            "minimum": 0,
            "maximum": 1,
            "description": "Cosine similarity of the winning voiceprint."
          },
          "profileId": {
            "type": "string",
            "description": "Id of the matched saved speaker (see `/recognition/speakers`)."
          }
        }
      },
      "SpeakerProfile": {
        "type": "object",
        "required": [
          "id",
          "name",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "maxLength": 200
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms."
          },
          "quality": {
            "type": [
              "number",
              "null"
            ],
            "description": "How well this voiceprint separated the speaker from others in the source recording (0–1); `null` for single-speaker sources."
          },
          "speech_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds of clean speech the voiceprint was computed from."
          }
        }
      },
      "DictionaryEntryInput": {
        "description": "A bare string is shorthand for `{ \"surface\": \"…\" }`.",
        "oneOf": [
          {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          {
            "type": "object",
            "required": [
              "surface"
            ],
            "properties": {
              "surface": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "The term in its base form, as it should appear in the transcript."
              },
              "variants": {
                "type": "array",
                "maxItems": 20,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 200
                },
                "description": "Known misrecognitions of the term (what the recognizer tends to write instead). A word in the transcript that is exactly one of these, alone or with a case ending, is replaced with the term. List the base form only: `Liben` also covers `Libeni`."
              }
            }
          }
        ]
      },
      "DictionaryEntry": {
        "type": "object",
        "required": [
          "surface",
          "variants"
        ],
        "properties": {
          "surface": {
            "type": "string"
          },
          "variants": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "DictionaryInput": {
        "type": "object",
        "required": [
          "name",
          "entries"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "entries": {
            "type": "array",
            "maxItems": 2000,
            "items": {
              "$ref": "#/components/schemas/DictionaryEntryInput"
            }
          },
          "is_default": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "DictionarySummary": {
        "type": "object",
        "required": [
          "id",
          "name",
          "entry_count",
          "is_default",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "entry_count": {
            "type": "integer"
          },
          "is_default": {
            "type": "boolean"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms."
          },
          "updated_at": {
            "type": "integer",
            "description": "Unix ms."
          }
        }
      },
      "Dictionary": {
        "allOf": [
          {
            "$ref": "#/components/schemas/DictionarySummary"
          },
          {
            "type": "object",
            "required": [
              "entries"
            ],
            "properties": {
              "entries": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/DictionaryEntry"
                }
              }
            }
          }
        ]
      },
      "SpeakerVoiceprint": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SpeakerProfile"
          },
          {
            "type": "object",
            "required": [
              "model_version",
              "embedding"
            ],
            "properties": {
              "model_version": {
                "type": "string",
                "description": "Embedding model the voiceprint was computed with. Only prints from the same model are comparable."
              },
              "embedding": {
                "type": "array",
                "items": {
                  "type": "number"
                },
                "description": "The voiceprint vector."
              }
            }
          }
        ]
      },
      "SpeechToTextWord": {
        "type": "object",
        "required": [
          "text",
          "type"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "enum": [
              "word",
              "spacing",
              "audio_event"
            ]
          },
          "start": {
            "type": [
              "number",
              "null"
            ]
          },
          "end": {
            "type": [
              "number",
              "null"
            ]
          },
          "speaker_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "logprob": {
            "type": "number"
          },
          "characters": {
            "type": [
              "array",
              "null"
            ]
          }
        }
      },
      "SpeechToTextWebhookResponse": {
        "type": "object",
        "required": [
          "message",
          "request_id"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "transcription_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "llm_correction": {
            "$ref": "#/components/schemas/LlmCorrectionStatus"
          }
        }
      },
      "WebhookCreateRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 80
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "https endpoint that will receive POSTs."
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "speech_to_text.transcription_completed",
                "speech_to_text.transcription_failed"
              ]
            },
            "description": "Defaults to `[\"speech_to_text.transcription_completed\"]`."
          }
        }
      },
      "Webhook": {
        "type": "object",
        "required": [
          "webhook_id",
          "name",
          "url",
          "secret_prefix",
          "events",
          "created_at",
          "revoked"
        ],
        "properties": {
          "webhook_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "secret_prefix": {
            "type": "string",
            "description": "Prefix of the signing secret. The full secret is only returned at creation time."
          },
          "events": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms."
          },
          "revoked": {
            "type": "boolean"
          }
        }
      },
      "WebhookCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Webhook"
          },
          {
            "type": "object",
            "required": [
              "secret"
            ],
            "properties": {
              "secret": {
                "type": "string",
                "description": "Plaintext signing secret. Returned exactly once; store it server-side."
              }
            }
          }
        ]
      },
      "WebhooksList": {
        "type": "object",
        "required": [
          "webhooks"
        ],
        "properties": {
          "webhooks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Webhook"
            }
          }
        }
      },
      "JobState": {
        "type": "string",
        "enum": [
          "uploading",
          "pending",
          "running",
          "succeeded",
          "failed",
          "cancelled"
        ],
        "description": "Lifecycle state. `uploading` is the initial state after `POST /recognition/uploads` until `…/start` is called. `succeeded`/`failed`/`cancelled` are terminal."
      },
      "CreateUploadRequest": {
        "type": "object",
        "required": [
          "filename",
          "content_type",
          "size_bytes"
        ],
        "properties": {
          "filename": {
            "type": "string",
            "description": "Original filename, used for display only."
          },
          "content_type": {
            "type": "string",
            "description": "MIME type of the upload. Must be an allowed audio/video type.",
            "examples": [
              "audio/wav",
              "audio/mpeg",
              "audio/mp4",
              "video/mp4"
            ]
          },
          "size_bytes": {
            "type": "integer",
            "minimum": 1,
            "description": "Total byte length of the file. 25 MB cap for anonymous callers; deployment cap for authed callers."
          },
          "language": {
            "type": "string",
            "default": "et",
            "description": "ISO-639-1 language code, or `auto` to auto-detect. Declaring it here is recommended: it is stored on the job, so a job recovered server-side after a lost `…/start` still runs in this language. `…/start` can override it.",
            "examples": [
              "et",
              "en",
              "auto"
            ]
          },
          "denoise": {
            "type": "boolean",
            "default": false,
            "description": "Remove background noise from the audio before it is transcribed. Stored on the job like `language`, so a job recovered server-side keeps it. `…/start` can override it."
          },
          "retain": {
            "type": "boolean",
            "default": true,
            "description": "Jutusta extension. `false` keeps nothing once the result is handed over: no playback copy is made, the uploaded file is deleted within minutes of transcription ending (so a failed job cannot be restarted), and the job with its transcript is deleted 24 h after it finished — or, with a webhook, once the delivery succeeded or gave up. Delete it sooner with `DELETE /recognition/jobs/{job_id}?purge=true`. Stored on the job like `language`; `…/start` can override it."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Your own correlation id for this recording (meeting id, case number, row key). Opaque to the service: never parsed, never required to be unique, and echoed back on every later read — job status, job list and webhook delivery."
          },
          "webhook_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Registered webhook subscription the finished transcript should be delivered to. Declaring it here rather than at `…/start` is recommended: the intent is stored on the job, so delivery still happens if the `…/start` call is lost and the job is recovered server-side. `…/start` can still override it (`webhook: false` opts out). A subscription that is not yours or has been revoked is a 404 `webhook_not_found`."
          },
          "webhook_metadata": {
            "type": [
              "string",
              "null"
            ],
            "description": "Opaque JSON string echoed back on the delivery. Stored verbatim; inherited by `…/start` unless that call sends its own."
          }
        }
      },
      "CreateUploadResponse": {
        "type": "object",
        "required": [
          "job_id",
          "upload_url",
          "r2_key",
          "expires_at"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "upload_url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Presigned R2 PUT URL. Send the file body with `Content-Type` matching the value posted as `content_type`. Null only on an idempotent replay (see `idempotent_replay`) of a job whose upload already completed — the bytes are in R2 and re-signing would let a retry overwrite a running job."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Echo of the request’s `external_id`."
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "idempotent_replay": {
            "type": "boolean",
            "description": "True when the `Idempotency-Key` matched a job you already created and THIS request created nothing. The response then describes that existing job (and the status code is 200 rather than 201), so a retried request after a network error cannot produce a second paid job."
          },
          "r2_key": {
            "type": "string",
            "description": "Object key inside R2 (informational)."
          },
          "expires_at": {
            "type": "integer",
            "description": "Unix-second expiry of the presigned URL (30 minutes from issuance)."
          }
        }
      },
      "StartJobRequest": {
        "type": "object",
        "description": "All fields optional; omit the body or send `{}` to accept defaults.",
        "properties": {
          "language": {
            "type": "string",
            "description": "ISO-639-1 language code, or `auto` to auto-detect. Defaults to the `language` declared at `/recognition/uploads` (`et` when none was).",
            "examples": [
              "et",
              "en",
              "auto"
            ]
          },
          "diarization": {
            "type": "boolean",
            "default": true
          },
          "denoise": {
            "type": "boolean",
            "description": "Remove background noise (DeepFilterNet) from the audio before it is transcribed. Helps with recordings made in noisy rooms, outdoors or over a loud background; on clean audio it adds processing time without improving the text. Defaults to the `denoise` declared at `/recognition/uploads` — or, when restarting a failed job, the value it last ran with — and `false` when neither was set. Every part of a split recording uses the same setting."
          },
          "retain": {
            "type": "boolean",
            "description": "Jutusta extension; see `retain` on `/recognition/uploads`. Defaults to the value declared there, or, when restarting a failed job, the value it last ran with; `true` when neither was set. Every part of a split recording uses the same setting."
          },
          "forced_alignment": {
            "type": "boolean",
            "default": true,
            "description": "When `true` (the default), the result carries per-word `start`/`end` timings (`segments[].words[]`). Set `false` to skip alignment and return segment-level timings only."
          },
          "fa_method": {
            "type": "string",
            "enum": [
              "xlsr",
              "kaldi",
              "none"
            ],
            "default": "xlsr",
            "description": "Forced-alignment backend when `forced_alignment=true`."
          },
          "asr_backend": {
            "type": "string",
            "enum": [
              "whisper",
              "moss"
            ],
            "description": "Recognition engine. Omit to use the service default for the job language. `whisper` is the finetuned Estonian Whisper pipeline; `moss` is the MOSS-Transcribe-Diarize engine. An unknown value is rejected with 400."
          },
          "duration_hint_seconds": {
            "type": "number",
            "minimum": 0,
            "description": "Length of the recording in seconds, if you know it. Two effects: it sharpens the ETA, and it decides the job topology — a recording longer than the split threshold is transcribed as several windowed part jobs (see `group_id` / `part_count` on the response). Without a hint the split decision is made from the duration the backend probes after the job starts, which is equally correct but only known later. Sending a hint shorter than the real file does NOT truncate anything: the last window always runs to end-of-file."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 256,
            "description": "Your own correlation id, echoed on every later read. Omit it to keep the value given at `POST /recognition/uploads`; send a string to replace it, or `null` / an empty string to clear it."
          },
          "webhook": {
            "type": "boolean",
            "default": false,
            "description": "Deliver the finished transcript to a registered webhook instead of requiring you to poll. Requires `webhook_id`. For a split recording exactly one delivery is made, for the whole recording, once every part has finished. Requires authentication. Omit the field entirely to inherit whatever was declared at `POST /recognition/uploads`; send `false` to opt out of an inherited subscription."
          },
          "dictionary_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "ASR dictionary (`GET /recognition/dictionaries`) whose terms the transcript is corrected towards. Omit to apply the account’s default dictionary — or, when restarting a failed job, the dictionary it was started with; send `null` or `none` to run without one. An id that is not the caller’s is 404 `dictionary_not_found`. Every part of a split recording uses the same dictionary."
          },
          "llm_correction": {
            "type": "boolean",
            "default": false,
            "description": "`true` asks for LLM correction after transcription: a large language model reads the transcript (and the dictionary, if one applies) and fixes clearly misrecognized words, names above all. The model only proposes small replacements and each one is checked against the audio before it is applied; nothing is rewritten, added or removed. Off by default, Estonian only, and a request that sets it never takes the low-latency path. When the model is operated by an external provider, it runs only for an account that has already agreed to that: a private account by agreeing once in the Jutusta app, a company account by switching the optional LLM correction function on. Otherwise the transcript is returned without this correction. A request that sets it is always told what happened, in the `llm_correction` object of the response (`status`, `reason`, `message`). 503 `service_unavailable` when the deployment does not offer it. Requires authentication. Omit it when restarting a job to keep what the job was last started with; send `false` to restart without correction. Every part of a split recording is corrected."
          },
          "webhook_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Id of a subscription created with `POST /webhooks`. Must belong to the caller and not be revoked; otherwise 404 `webhook_not_found`."
          },
          "webhook_metadata": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 16384,
            "description": "Opaque string echoed back in the delivery’s `metadata` field. JSON is parsed and echoed as an object; anything else is echoed verbatim."
          }
        }
      },
      "StartJobResponse": {
        "type": "object",
        "required": [
          "job_id",
          "state",
          "part_count",
          "part_job_ids"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "eta_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "audio_duration_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds of audio THIS job decodes. For the primary part of a split recording that is the first window only — `original_duration_seconds` is the whole recording."
          },
          "original_duration_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Length of the whole recording as understood at submit time."
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Set when the recording was split into several part jobs; equals `job_id` (the primary part). Null for an ordinary single-part job."
          },
          "part_count": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of part jobs the recording was split into. 1 when it was not split."
          },
          "part_job_ids": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Every part id in order, primary first — a one-element array when there was no split. You do not have to use these: `GET /recognition/jobs/{job_id}` on the primary answers for the whole recording."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "webhook_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Subscription the finished recording will be delivered to, when one was requested."
          },
          "llm_correction": {
            "$ref": "#/components/schemas/LlmCorrectionStatus"
          }
        }
      },
      "RecognitionWord": {
        "type": "object",
        "description": "One aligned word. `start`/`end` (seconds from the start of the recording) are present when the job ran with `forced_alignment=true`.",
        "properties": {
          "word_with_punctuation": {
            "type": "string",
            "description": "Surface form including trailing punctuation, e.g. `Tere,`."
          },
          "word": {
            "type": "string",
            "description": "Bare word without punctuation."
          },
          "punctuation": {
            "type": [
              "string",
              "null"
            ]
          },
          "start": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds from recording start."
          },
          "end": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds from recording start."
          },
          "confidence": {
            "type": [
              "number",
              "null"
            ]
          },
          "logprob": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "RecognitionSegment": {
        "type": "object",
        "required": [
          "start",
          "end",
          "text"
        ],
        "properties": {
          "start": {
            "type": "number",
            "description": "Segment start, seconds from recording start."
          },
          "end": {
            "type": "number",
            "description": "Segment end, seconds from recording start."
          },
          "text": {
            "type": "string"
          },
          "speaker": {
            "type": [
              "string",
              "null"
            ],
            "description": "Diarization label (`SPEAKER_00`…) when the job ran with `diarization=true`."
          },
          "text_pre_llm": {
            "type": "string",
            "description": "The segment’s text before LLM correction; present only on segments that correction changed."
          },
          "words": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/RecognitionWord"
            },
            "description": "Per-word timings; present when the job ran with `forced_alignment=true`."
          }
        }
      },
      "RecognitionResult": {
        "type": "object",
        "required": [
          "segments"
        ],
        "description": "Raw recognition result. Segment-grained, with per-word timings nested under `segments[].words[]`.",
        "properties": {
          "segments": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RecognitionSegment"
            }
          },
          "language_detected": {
            "type": [
              "string",
              "null"
            ]
          },
          "dict_correction": {
            "type": [
              "object",
              "null"
            ],
            "description": "Present when the job ran with a dictionary: how many terms were loaded (`entries`), how many edits were applied (`edits`) and the list of `applied` corrections. Absent when no dictionary applied and on combined split-recording results. A `warnings[]` entry with `stage: \"dict_correct\"` means the correction stage failed and the text is uncorrected.",
            "properties": {
              "entries": {
                "type": "integer"
              },
              "candidates": {
                "type": "integer"
              },
              "edits": {
                "type": "integer"
              },
              "applied": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          },
          "llm_correction": {
            "type": [
              "object",
              "null"
            ],
            "description": "The backend’s own report, present when the job was sent with `llm_correction`: `status` (`applied`, `partial`, `skipped`, `failed`), and when the stage ran, how many replacements the model proposed (`proposed`), how many passed the checks and were applied (`edits`), and the `applied` list (segment, `before`, `after`, time span). An edited segment keeps its earlier text in `text_pre_llm`. Absent when correction was not requested or not allowed, and on combined split-recording results. For whether a requested correction happened, read the job’s top-level `llm_correction` instead: it is always present for a job that asked.",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "applied",
                  "partial",
                  "skipped",
                  "failed"
                ]
              },
              "reason": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "detail": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "chunks": {
                "type": "integer"
              },
              "failed_chunks": {
                "type": "integer"
              },
              "proposed": {
                "type": "integer"
              },
              "edits": {
                "type": "integer"
              },
              "acoustics": {
                "type": "boolean"
              },
              "applied": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              }
            }
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "description": "Full transcript as plain text, when the backend provides it. Otherwise join `segments[].text`."
          }
        }
      },
      "RecognitionJobSummary": {
        "type": "object",
        "required": [
          "job_id",
          "state",
          "source",
          "language",
          "original_filename",
          "size_bytes",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "source": {
            "type": "string",
            "enum": [
              "file",
              "live",
              "meet",
              "teams"
            ],
            "description": "Which surface produced the job: an upload, a browser-mic session, or a Google Meet / Microsoft Teams integration."
          },
          "language": {
            "type": "string"
          },
          "original_filename": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "duration_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "progress": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1,
            "description": "Fractional progress (0–1) while running."
          },
          "created_at": {
            "type": "integer",
            "description": "Unix ms."
          },
          "updated_at": {
            "type": "integer",
            "description": "Unix ms."
          },
          "upload_landed": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the uploaded file actually reached storage, reported where that is the open question. `true`: an `uploading` job older than 30 minutes whose file is complete — it was never started; call `POST /recognition/jobs/{job_id}/start`. Also `true` on a job cancelled before its upload finished whose upload then completed anyway (its `error_code` turns back into `cancelled`). `false`: the upload never finished (a stuck `uploading` job past its upload window, a `failed` job with `upload_incomplete`, or a job cancelled before its upload finished, `upload_cancelled`) — it cannot be restarted; upload the file again. `null`: not checked, or not applicable."
          },
          "media_deleted_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "When the job’s audio was deleted (unix ms) — by you with `DELETE /recognition/jobs/{job_id}/media`, or by the retention rules. The transcript is kept. `null` while the audio is stored."
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Set only on the primary row of an auto-split recording (and then equal to `job_id`). For such a row `state`, `progress` and `duration_seconds` above are already aggregated across all parts."
          },
          "part_count": {
            "type": [
              "integer",
              "null"
            ]
          },
          "part_job_ids": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Every part id in order. Null for an unsplit job."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "DeletedRecognitionJob": {
        "type": "object",
        "required": [
          "job_id",
          "deleted_at"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RecognitionJobStatus": {
        "type": "object",
        "required": [
          "job_id",
          "state",
          "language",
          "original_filename",
          "size_bytes",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "job_id": {
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/JobState"
          },
          "progress": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1
          },
          "eta_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Estimated seconds until done. Under `view=group` it covers the whole recording: the backend’s estimate for the window just polled, extrapolated over every unfinished window at the same rate, taking the slowest — a floor rather than a promise, since queued windows have not been scheduled yet. `null` when nothing can be estimated."
          },
          "audio_duration_seconds": {
            "type": [
              "number",
              "null"
            ]
          },
          "language": {
            "type": "string"
          },
          "language_detected": {
            "type": [
              "string",
              "null"
            ]
          },
          "original_filename": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "result": {
            "description": "Populated when `state` is `succeeded`. Shape matches `RecognitionResult` (segment-grained, with per-word timings under `segments[].words[]` when the job ran with `forced_alignment=true`). Note: this differs from the flattened `SpeechToTextChunkResponse` returned by `POST /speech-to-text`.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/RecognitionResult"
              },
              {
                "type": "null"
              }
            ]
          },
          "matched_speakers": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": {
              "$ref": "#/components/schemas/SpeakerMatch"
            },
            "description": "Saved speakers recognised in this job, keyed by diarization label. `null` unless the job ran with diarization + speaker recognition and the account has saved speakers. When `result_is_combined` is true the keys are the labels the combined `result.segments` carry — the first part’s own labels, plus those later parts’ speakers were given on the shared roster."
          },
          "llm_correction": {
            "$ref": "#/components/schemas/LlmCorrectionStatus"
          },
          "error": {
            "description": "Populated when `state` is `failed`.",
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "code"
                ],
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "detail": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "integer"
          },
          "updated_at": {
            "type": "integer"
          },
          "part_index": {
            "type": [
              "integer",
              "null"
            ],
            "description": "0-based position of this part in the recording. Null for an unsplit job."
          },
          "part_start_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Offset of this part’s first sample within the whole recording. A part’s own `result` timestamps are LOCAL (they start at 0), so add this to get absolute times — or read the group view, where they are already absolute."
          },
          "group_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Set on every part of an auto-split recording; equals the primary part’s job id. Null when this job is the whole recording."
          },
          "part_count": {
            "type": "integer",
            "minimum": 1,
            "description": "Number of parts the recording was split into; 1 when it was not."
          },
          "part_job_ids": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "part_state": {
            "allOf": [
              {
                "$ref": "#/components/schemas/JobState"
              }
            ],
            "description": "This row’s own state, never aggregated. Under `view=part` it equals `state`."
          },
          "group_state": {
            "allOf": [
              {
                "$ref": "#/components/schemas/JobState"
              }
            ],
            "description": "State of the whole recording: `succeeded` only once every part succeeded, `failed` if any part failed, otherwise the least-advanced part’s state."
          },
          "is_complete": {
            "type": "boolean",
            "description": "True only when EVERY part of the recording succeeded. This is the flag to gate on before treating `result` as the complete recording."
          },
          "original_duration_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Length of the whole recording — from the duration hint given at start, or summed from the finished parts."
          },
          "processed_duration_seconds": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds of audio actually decoded so far across all parts. Equal to `original_duration_seconds` (within probe tolerance) once `is_complete` is true; compare the two to verify nothing was left out."
          },
          "external_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Echo of the correlation id you supplied."
          },
          "media_deleted_at": {
            "type": [
              "integer",
              "null"
            ],
            "description": "When the job’s audio was deleted (unix ms) — by you with `DELETE /recognition/jobs/{job_id}/media`, or by the retention rules. The transcript is kept. `null` while the audio is stored."
          },
          "result_is_combined": {
            "type": "boolean",
            "description": "True when `result` spans the whole recording — all parts stitched onto one timeline with a unified speaker roster. A combined `result` is the first part’s result with the stitched fields laid over it and nothing removed, so every field a single job’s `result` has is still there (`speaker_embeddings`, when present, are the first part’s; its labels are unchanged on the shared roster). It also carries `speaker_count`, `speakers_unified`, `part_count` and `speaker_names` (label → the name you saved for that speaker, in the app or via the transcript editor; empty when nobody is named). False means `result` covers this part only (because `view=part` was requested, the recording is not finished, or it is too large to combine in one response — then use `GET /recognition/jobs/{job_id}/transcript`)."
          }
        }
      },
      "Summary": {
        "type": "object",
        "required": [
          "id",
          "jobId",
          "templateId",
          "text",
          "model",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "jobId": {
            "type": "string"
          },
          "templateId": {
            "type": "string",
            "description": "Catalog id of the template used. Listed by `GET /summary-templates`."
          },
          "text": {
            "type": "string",
            "description": "Generated summary text."
          },
          "model": {
            "type": "string",
            "description": "Identifier of the LLM that produced the summary (e.g. `@cf/mistralai/mistral-small-3.1-24b-instruct`)."
          },
          "createdAt": {
            "type": "integer",
            "description": "Unix ms."
          },
          "updatedAt": {
            "type": "integer",
            "description": "Unix ms."
          }
        }
      },
      "SummariesListResponse": {
        "type": "object",
        "required": [
          "summaries"
        ],
        "properties": {
          "summaries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Summary"
            }
          }
        }
      },
      "SummaryResponse": {
        "type": "object",
        "required": [
          "summary"
        ],
        "properties": {
          "summary": {
            "$ref": "#/components/schemas/Summary"
          }
        }
      },
      "SummaryGenerateRequest": {
        "type": "object",
        "properties": {
          "templateId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Template to apply. Omit (or pass `null`) to use the caller’s default template."
          }
        }
      },
      "TextSummaryRequest": {
        "type": "object",
        "required": [
          "text"
        ],
        "properties": {
          "text": {
            "type": "string",
            "description": "The transcript to summarize, up to 1 MiB as UTF-8 — ideally one `Speaker: text` line per turn."
          },
          "language": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "et"
            ],
            "description": "Language tag of the text (`et`, `en-US`). `et` gets the Estonian prompt; omit when unknown."
          },
          "templateId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Template to apply. Omit (or pass `null`) to use the caller’s default template."
          },
          "retain": {
            "type": "boolean",
            "default": true,
            "description": "Jutusta extension. `false` keeps the summary only for the hand-over: the response to this request is meant to be the only copy, and a summary that is not collected (by this request, or by `GET /summarize/{run_id}` after a `202`) is deleted within about 10 minutes of being written instead of an hour. The text is deleted once the summary is written either way. Only `true` and `false` are accepted."
          }
        }
      },
      "TextSummaryResponse": {
        "type": "object",
        "required": [
          "summary"
        ],
        "properties": {
          "summary": {
            "type": "object",
            "required": [
              "templateId",
              "text",
              "model"
            ],
            "properties": {
              "templateId": {
                "type": "string",
                "description": "Template that was applied — the caller’s default when none was named."
              },
              "text": {
                "type": "string",
                "description": "The summary, as Markdown."
              },
              "model": {
                "type": "string",
                "description": "Identifier of the LLM that wrote it."
              }
            }
          }
        }
      },
      "TextSummaryRunPending": {
        "type": "object",
        "required": [
          "run"
        ],
        "properties": {
          "run": {
            "type": "object",
            "required": [
              "id",
              "status",
              "templateId"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "Run id to poll."
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending",
                  "running"
                ]
              },
              "templateId": {
                "type": "string",
                "description": "Template being applied."
              }
            }
          }
        }
      },
      "SummaryTemplate": {
        "type": "object",
        "required": [
          "id",
          "label",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "TemplatesCatalogResponse": {
        "type": "object",
        "required": [
          "templates",
          "default_template_id"
        ],
        "properties": {
          "templates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SummaryTemplate"
            }
          },
          "default_template_id": {
            "type": "string",
            "description": "Caller’s current default template id. Falls back to the catalog default until `PUT /summary-templates` is called."
          }
        }
      },
      "SetDefaultTemplateRequest": {
        "type": "object",
        "required": [
          "templateId"
        ],
        "properties": {
          "templateId": {
            "type": "string",
            "description": "Catalog id of the template to set as default."
          }
        }
      },
      "TranslateChunkRequest": {
        "type": "object",
        "required": [
          "source",
          "target",
          "new_source"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "BCP-47 / Whisper-style language code of `new_source`. `auto` is rejected — resolve before calling.",
            "examples": [
              "et",
              "en"
            ]
          },
          "target": {
            "type": "string",
            "description": "Target language code.",
            "examples": [
              "en",
              "et"
            ]
          },
          "new_source": {
            "type": "string",
            "minLength": 1,
            "description": "New transcript chunk to translate. Capped at ~8000 characters per call."
          },
          "previous": {
            "type": [
              "string",
              "null"
            ],
            "description": "Tail of the translation rendered so far. Used as context — the model is instructed not to repeat or revise it. Truncated to the last ~2000 characters server-side."
          }
        }
      },
      "TranslateChunkResponse": {
        "type": "object",
        "required": [
          "appended",
          "model",
          "source",
          "target"
        ],
        "properties": {
          "appended": {
            "type": "string",
            "description": "Text to append to the already-rendered translation. Concatenate verbatim."
          },
          "model": {
            "type": "string",
            "description": "Identifier of the LLM that produced the chunk (e.g. `@cf/mistralai/mistral-small-3.1-24b-instruct`). Same-language requests echo `identity`."
          },
          "source": {
            "type": "string"
          },
          "target": {
            "type": "string"
          }
        }
      }
    }
  }
}