{"openapi":"3.1.0","info":{"title":"Hakim API","version":"1.0.0","summary":"Arabic-first Text-to-Speech and Speech-to-Text","description":"Public HTTP API for Hakim. Every endpoint lives under `/v1/*`; versioning is path-based. All requests are authenticated via an API key passed as `Authorization: Bearer hk_live_…`. Errors follow a uniform `ApiError` shape and include a `request_id` for support.","contact":{"name":"Hakim API Support","email":"support@tryhakim.ai"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.tryhakim.ai","description":"Production"}],"tags":[{"name":"Audio — Text-to-Speech","description":"Generate speech audio from text."},{"name":"Audio — Speech-to-Text","description":"Transcribe audio to text."},{"name":"Audio — Voices","description":"List, inspect, clone, and manage voices."},{"name":"Jobs","description":"Inspect asynchronous jobs (batch STT, voice clone, bulk TTS) and download their outputs."},{"name":"Webhooks","description":"Manage webhook subscriptions and inspect recent delivery attempts."},{"name":"Settings","description":"Read and update the caller's profile and organization settings."},{"name":"Notifications","description":"Read and update transactional email preferences for the API-key creator."},{"name":"Usage","description":"Inspect billing usage and raw events."}],"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/audio/speech":{"post":{"tags":["Audio — Text-to-Speech"],"summary":"Synthesize speech from text","description":"Generates audio from the provided text using the requested voice and model. Returns the audio body directly (not JSON). Set `stream: true` to receive the output as a chunked HTTP response starting as soon as the first frame is ready.","operationId":"audio_speech_create","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeechRequest"}}}},"responses":{"200":{"description":"Synthesized audio. `Content-Type` varies by `response_format` (`audio/mpeg`, `audio/wav`, `audio/pcm;rate=…`, or `audio/ogg`). Streaming responses use `Transfer-Encoding: chunked`.","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}},"audio/pcm":{"schema":{"type":"string","format":"binary"}}},"headers":{"X-Usage-Characters":{"description":"Unicode code-point count billed against the TTS quota.","schema":{"type":"integer","minimum":0}},"X-Duration-Ms":{"description":"Emitted audio duration in milliseconds. Non-streaming only.","schema":{"type":"integer","minimum":0}},"X-Upstream-Host":{"description":"Inference host that served the request. Useful for support tickets.","schema":{"type":"string"}},"X-Upstream-Voice":{"description":"Upstream voice reference resolved from the caller-supplied slug or id.","schema":{"type":"string"}},"X-Request-Id":{"description":"Echoed request id. Pass back to support for every ticket.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Quota exceeded for the billing period or hard cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict — same key used with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded. See `Retry-After` and `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Upstream inference unavailable or breaker open.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/audio/transcriptions":{"post":{"tags":["Audio — Speech-to-Text"],"summary":"Transcribe an audio file","description":"Transcribes an audio file to text. Multipart upload. Files larger than 25 MiB or longer than 10 minutes are accepted as 202 and queued; poll the returned `poll_url` for the result.\n\n**Need lower latency?** For interactive use cases (live captions, dictation, call-center agents) prefer the realtime streaming surface at `WSS /v1/audio/transcriptions/stream` — it returns interim `transcription.delta` frames as the audio arrives instead of waiting for the full file. See the `audio_transcriptions_stream` operation below for the wire contract.","operationId":"audio_transcriptions_create","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","model"],"properties":{"file":{"type":"string","format":"binary"},"model":{"type":"string","enum":["hakim-arab-v2","hakim-voxtral-v1"],"default":"hakim-arab-v2","description":"STT model id. `hakim-arab-v2` is the current canonical id; `hakim-voxtral-v1` is the legacy id from the v1.0.0 launch — still accepted for backwards-compat and normalised server-side."},"language":{"type":"string","default":"auto"},"response_format":{"type":"string","enum":["json","text","srt","vtt","verbose_json"],"default":"json"},"timestamps":{"type":"string","enum":["word","segment","none"],"default":"segment"},"diarize":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"Synchronous transcription. Body type depends on `response_format`: JSON for `json` / `verbose_json`, plain text for `text`, SRT/VTT subtitles for `srt`/`vtt`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionJsonResponse"}},"text/plain":{"schema":{"type":"string"}},"application/x-subrip":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}}},"headers":{"X-Audio-Duration-Ms":{"description":"Measured duration of the uploaded audio in milliseconds.","schema":{"type":"integer","minimum":0}},"X-Audio-Size-Bytes":{"description":"Uploaded audio size in bytes.","schema":{"type":"integer","minimum":0}},"X-Audio-Format":{"description":"Detected container format.","schema":{"type":"string"}},"X-Usage-Seconds":{"description":"Seconds billed against the STT quota (ceiled).","schema":{"type":"integer","minimum":0}}}},"202":{"description":"Asynchronous acceptance — file exceeds the synchronous limit. Poll `poll_url` for the result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranscriptionAsyncAccepted"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Quota exceeded for the billing period or hard cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded. See `Retry-After` and `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Upstream inference unavailable or breaker open.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/audio/transcriptions/stream":{"get":{"tags":["Audio — Speech-to-Text"],"summary":"Realtime streaming transcription (WebSocket)","x-websocket":true,"description":"Opens a long-lived WebSocket session for realtime transcription. The proxy is wire-compatible with the OpenAI Realtime API: clients send JSON text frames (`session.update`, `input_audio_buffer.append`, `input_audio_buffer.commit`, `session.close`) and receive `session.created`, `transcription.delta`, `transcription.done`, and `error` frames as the upstream processes the audio.\n\n**Connection**\n\n* Upgrade target: `wss://api.tryhakim.ai/v1/audio/transcriptions/stream`.\n* Authentication: `Authorization: Bearer hk_live_…` on the HTTP upgrade   request (the proxy runs the same `apiKeyAuth + requireScope(\"stt:write\") +   rateLimit + quota` middleware chain as the batch endpoint).\n* Subprotocol: none — frames are JSON text; binary frames are rejected with   `binary_frames_not_supported`.\n* Audio payload: base64-encoded inside `input_audio_buffer.append.audio`.   Supported codecs: `pcm16`, `opus`, `mulaw`. Recommended chunk size: 50–250 ms.\n\n**Lifecycle**\n\n1. Server sends `session.created` immediately after the upgrade succeeds; the    `limits` block echoes the constants defined in `RealtimeSttLimits`.\n2. Client may send `session.update` at any time to change `model`, `language`,    `timestamps`, `diarize`, `partials`, `input_audio_format`, or    `input_sample_rate`. Subsequent `session.update` frames merge into the    existing config.\n3. Client streams `input_audio_buffer.append` frames; the proxy forwards them to    the upstream and accumulates `audio_ms` for billing (`stt_realtime` usage    kind, billed in seconds, ceiled).\n4. Either side may end the session: client sends `session.close`, or the proxy    closes when limits are reached or the upstream disconnects.\n\n**WebSocket close codes**\n\n| Code | Meaning |\n|------|---------|\n| `1000` | Clean close (`session.close` from either side). |\n| `1008` | Policy violation — see preceding `error` frame for the stable `code`   (`upstream_unavailable`, `frame_too_large`, `invalid_json`, `invalid_frame`,   `binary_frames_not_supported`, `upstream_closed`, `upstream_timeout`,   `session_too_long`). |\n| `1011` | Internal error — see `error.code` (`upstream_not_ready`,   `upstream_write_failed`, `auth_missing`). |\n\nSee `RealtimeClientFrame` / `RealtimeServerFrame` for the full message catalog and `RealtimeSttSession` for the per-session configuration object.","operationId":"audio_transcriptions_stream","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"},{"name":"Connection","in":"header","required":true,"description":"Standard WebSocket upgrade header. Must be `Upgrade`.","schema":{"type":"string","enum":["Upgrade"]}},{"name":"Upgrade","in":"header","required":true,"description":"Standard WebSocket upgrade header. Must be `websocket`.","schema":{"type":"string","enum":["websocket"]}},{"name":"Sec-WebSocket-Version","in":"header","required":true,"description":"WebSocket protocol version. Must be `13`.","schema":{"type":"string","enum":["13"]}},{"name":"Sec-WebSocket-Key","in":"header","required":true,"description":"Client-generated nonce per RFC 6455.","schema":{"type":"string"}}],"x-messages":{"send":{"description":"Frames the client may send.","payload":{"$ref":"#/components/schemas/RealtimeClientFrame"}},"receive":{"description":"Frames the server emits.","payload":{"$ref":"#/components/schemas/RealtimeServerFrame"}},"limits":{"description":"Per-session limits echoed in `session.created`.","payload":{"$ref":"#/components/schemas/RealtimeSttLimits"}}},"responses":{"101":{"description":"WebSocket upgrade accepted. Subsequent frames follow the JSON wire contract documented above and in the `RealtimeClientFrame` / `RealtimeServerFrame` schemas.","headers":{"Upgrade":{"description":"Always `websocket` on success.","schema":{"type":"string","enum":["websocket"]}},"Connection":{"description":"Always `Upgrade` on success.","schema":{"type":"string","enum":["Upgrade"]}},"Sec-WebSocket-Accept":{"description":"RFC 6455 handshake response.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Quota exceeded for the billing period or hard cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded. See `Retry-After` and `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Upstream inference unavailable or breaker open.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/audio/voices":{"post":{"tags":["Audio — Voices"],"summary":"Clone a new voice","description":"Creates a cloned voice for the caller organization. Accepts a single audio sample (multipart `file` part) plus metadata. The voice is created in `status: \"processing\"` and a background job generates the preview. Poll `GET /v1/audio/voices/{id}` until `status` transitions to `ready` or `failed`.\n\nRequires the `voices:write` scope. Supports `Idempotency-Key` to safely retry uploads.","operationId":"audio_voices_clone_create","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","name","language","consent_confirmed"],"properties":{"file":{"type":"string","format":"binary","description":"Voice sample (wav/mp3/ogg/webm/m4a/mp4/flac). Max size is set by the platform — on overflow the server returns a 413 with detail. The sample is used only for clone training and is not played back publicly."},"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":500},"language":{"type":"string","description":"Base language or Arabic dialect of the sample (matches `Voice.language`)."},"voice_type":{"type":"string","enum":["conversational","narrative","news","social_media","advertising","elearning","character","customer_service"],"default":"conversational"},"gender":{"type":"string","enum":["male","female","neutral"]},"consent_confirmed":{"type":"boolean","enum":[true],"description":"Must be `true`. The caller attests that they have the speaker’s consent to clone the voice per PRD §9."}}}}}},"responses":{"202":{"description":"Clone job enqueued. Returned `Voice` has `status: \"processing\"`. Poll `GET /v1/audio/voices/{id}` for completion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"Quota exceeded for the billing period or hard cap.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict — same key used with a different body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded. See `Retry-After` and `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Audio — Voices"],"summary":"List available voices","description":"Returns presets and the caller organization's cloned voices. Filter by language, Arabic dialect, gender, voice type, or kind.","operationId":"audio_voices_list","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"language","in":"query","required":false,"schema":{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da","ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE","multi"]}},{"name":"gender","in":"query","required":false,"schema":{"type":"string","enum":["male","female","neutral"]}},{"name":"voice_type","in":"query","required":false,"schema":{"type":"string","enum":["conversational","narrative","news","social_media","advertising","elearning","character","customer_service"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["preset","cloned"]}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"List of voices.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoicesListResponse"}}},"headers":{"Cache-Control":{"description":"`private, max-age=30, stale-while-revalidate=60`.","schema":{"type":"string"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/audio/voices/{id}":{"get":{"tags":["Audio — Voices"],"summary":"Retrieve a voice","description":"Returns a single voice. Callers see every preset and any non-deleted voice their organization owns (including moderation-blocked clones, with `preview_url: null`). Cloned voices are returned with a freshly-minted 7-day signed preview URL.","operationId":"audio_voices_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","maxLength":128}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"The requested voice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Voice"}}},"headers":{"Cache-Control":{"description":"`private, max-age=10, stale-while-revalidate=30`.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"tags":["Audio — Voices"],"summary":"Delete a cloned voice","description":"Soft-deletes an organization-owned cloned voice. Preset voices are managed by Hakim and cannot be deleted. Voices owned by other organizations return 404.","operationId":"audio_voices_delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","maxLength":128}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Voice soft-deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoiceDeletedResponse"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/audio/voices/{id}/preview.mp3":{"get":{"tags":["Audio — Voices"],"summary":"Download a voice preview (signed URL)","description":"Public endpoint — authorization is carried by the HMAC signature in the query string. Signed URLs are minted by `GET /v1/audio/voices/{id}` with a 7-day TTL. Returns `audio/mpeg` bytes on success. Expired URLs return 410.","operationId":"audio_voices_preview_download","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+$","maxLength":128}},{"name":"expires","in":"query","required":true,"schema":{"type":"string","description":"Signed expiry (unix-ms) from the minted URL."}},{"name":"sig","in":"query","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature from the minted URL."}}],"responses":{"200":{"description":"Preview audio bytes.","content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Preview is not available or the object was already cleaned up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Signed URL has expired — fetch a fresh one via GET /v1/audio/voices/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/jobs":{"get":{"tags":["Jobs"],"summary":"List jobs","description":"Paginated list of the caller organization's jobs, ordered by `created_at` descending. Filter by `status` and/or `type`. Pagination is cursor-based: pass the previous response's `next_cursor` as `cursor` to fetch the next page.","operationId":"jobs_list","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]}},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["batch_stt","voice_clone","bulk_tts"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"A page of jobs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobsListResponse"}}},"headers":{"Cache-Control":{"description":"`private, no-store`.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/jobs/{id}":{"get":{"tags":["Jobs"],"summary":"Retrieve a job","description":"Returns a single job owned by the caller organization. Succeeded `batch_stt` jobs carry a freshly-minted `result_url` (signed, short-lived) on every fetch. Cloned voices are tracked under `/v1/audio/voices/{id}` rather than here.","operationId":"jobs_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"The requested job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}},"headers":{"Cache-Control":{"description":"`private, no-store`.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/jobs/{id}/result":{"get":{"tags":["Jobs"],"summary":"Download a job result (signed URL)","description":"Public endpoint — authorization is carried by the HMAC signature in the query string. Currently only `batch_stt` jobs expose a downloadable result. The response `Content-Type` matches the original `response_format` (JSON, text, SRT, or VTT). Expired URLs return 410. Jobs that have not succeeded return 409.","operationId":"jobs_result_download","security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":128}},{"name":"expires","in":"query","required":true,"schema":{"type":"string"}},{"name":"sig","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job output bytes.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/plain":{"schema":{"type":"string"}},"application/x-subrip":{"schema":{"type":"string"}},"text/vtt":{"schema":{"type":"string"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid signature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Job not found or no downloadable result for this job type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Job has not succeeded yet — result is not available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Signed URL has expired — fetch a fresh one via GET /v1/jobs/{id}.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks":{"post":{"tags":["Webhooks"],"summary":"Create a webhook subscription","description":"Creates a webhook subscription for one or more event types. The signing `secret` is returned exactly once in this response — persist it immediately. Subsequent reads never return the secret; use the rotate flow in the dashboard to mint a new one.\n\nRequires the `webhooks:write` scope.","operationId":"webhooks_create","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreateRequest"}}}},"responses":{"201":{"description":"Webhook created. Includes the one-time signing secret.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCreated"}}},"headers":{"Cache-Control":{"description":"`private, no-store`.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"Rate limit exceeded. See `Retry-After` and `X-RateLimit-*` headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Webhooks"],"summary":"List webhook subscriptions","description":"Lists the caller organization's webhook subscriptions. Secrets are never included; use the dashboard to rotate and reveal a fresh secret.","operationId":"webhooks_list","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Webhook subscriptions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhooksListResponse"}}},"headers":{"Cache-Control":{"description":"`private, no-store`.","schema":{"type":"string"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks/{id}":{"get":{"tags":["Webhooks"],"summary":"Retrieve a webhook subscription","operationId":"webhooks_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"The requested webhook subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook subscription","description":"Partial update — supply any subset of `url`, `events`, and `active`. At least one field must be provided. Requires the `webhooks:write` scope.","operationId":"webhooks_update","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/XRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdateRequest"}}}},"responses":{"200":{"description":"Updated webhook subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook subscription","description":"Hard-deletes a webhook subscription. Any in-flight delivery attempts are cancelled. Requires the `webhooks:write` scope.","operationId":"webhooks_delete","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"204":{"description":"Webhook deleted."},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"List delivery attempts for a webhook","description":"Paginated list of delivery attempts for the given webhook. Filter by delivery `status` (`pending`, `succeeded`, `failed`). Payload bodies are deliberately excluded — inspect payloads in the dashboard.","operationId":"webhooks_deliveries_list","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","succeeded","failed"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"A page of delivery attempts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveriesListResponse"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/settings/profile":{"get":{"tags":["Settings"],"summary":"Retrieve the API-key creator's profile","description":"Returns the profile of the user who created the API key. All responses are `Cache-Control: private, no-store` — never cache these payloads. Requires the `settings:read` scope.","operationId":"settings_profile_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Settings"],"summary":"Update the API-key creator's profile","description":"Partial update — any subset of `name`, `locale`, `timezone`, and `marketing_opt_in`. At least one field must be present. Email changes are out of scope here (they require re-verification). Requires the `settings:write` scope.","operationId":"settings_profile_update","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdateRequest"}}}},"responses":{"200":{"description":"Updated profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/settings/organization":{"get":{"tags":["Settings"],"summary":"Retrieve organization settings","description":"Returns the caller's organization settings (name, slug, billing email, default locale, logo URL). Requires the `settings:read` scope.","operationId":"settings_organization_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Organization settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSettings"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Settings"],"summary":"Update organization settings","description":"Partial update. Reserved to API keys whose *creator* is an `owner` or `admin` of the organization — demoting the creator takes effect immediately. Logo uploads use a separate signed-upload flow and are not patched through this endpoint. Requires the `settings:write` scope.","operationId":"settings_organization_update","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSettingsUpdateRequest"}}}},"responses":{"200":{"description":"Updated organization settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrganizationSettings"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/notifications":{"get":{"tags":["Notifications"],"summary":"Retrieve notification preferences","description":"Returns the transactional-email preferences for the API-key creator. Missing categories fall back to defaults. Requires the `settings:read` scope.","operationId":"notifications_get","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Notification preferences.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"patch":{"tags":["Notifications"],"summary":"Update notification preferences","description":"Partial update — any subset of toggles may be sent. Missing keys mean \"unchanged\" (not \"reset to default\"). Requires the `settings:write` scope.","operationId":"notifications_update","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferencesUpdateRequest"}}}},"responses":{"200":{"description":"Updated notification preferences.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotificationPreferences"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/usage":{"get":{"tags":["Usage"],"summary":"Summarize usage for the current billing period","description":"Aggregates TTS characters + STT seconds for the caller organization, combining authoritative daily rollups with a 60-minute live delta so the dashboard is accurate to within seconds of activity.","operationId":"usage_summary","security":[{"ApiKeyAuth":[]}],"parameters":[{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Current-period usage summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageSummary"}}},"headers":{"Cache-Control":{"description":"`private, max-age=5, stale-while-revalidate=25`.","schema":{"type":"string"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/usage/events":{"get":{"tags":["Usage"],"summary":"List raw usage events with cursor pagination","description":"Paginated raw usage events. Use the opaque `next_cursor` to fetch the next page. Events are ordered by `created_at` descending.","operationId":"usage_events_list","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["tts","stt_batch","stt_realtime","voice_clone"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/XRequestId"}],"responses":{"200":{"description":"Usage events page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageEventsList"}}},"headers":{"Cache-Control":{"description":"`private, no-store`.","schema":{"type":"string"}}}},"400":{"description":"Invalid request — validation failed or bad parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication error — missing, malformed, or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Permission error — API key is missing the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"hk_live_…","description":"API key passed as `Authorization: Bearer hk_live_<secret>`. Test keys (`hk_test_…`) bypass quota enforcement."}},"schemas":{"ApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found","rate_limit_error","quota_exceeded","api_error","service_unavailable","idempotency_conflict"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"},"retry_after_seconds":{"type":"integer","minimum":0},"upgrade_url":{"type":"string","format":"uri"},"docs_url":{"type":"string","format":"uri"}},"required":["type","code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"SpeechRequest":{"type":"object","properties":{"model":{"type":"string","enum":["hakim-fast-v1","hakim-v2","hakim-v3","hakim-flash-v1"]},"input":{"type":"string","minLength":1,"maxLength":5000},"voice":{"type":"string","minLength":1,"description":"Voice to synthesize with. Pass the `id` returned by `GET /v1/audio/voices` (recommended — ids are unique and stable). The `slug` field (e.g. `priya-hi`) is also accepted for readability, but a slug is not guaranteed unique across orgs and may shift if a voice is renamed; prefer the id for production traffic."},"response_format":{"type":"string","enum":["mp3","wav","pcm","opus"],"default":"mp3"},"sample_rate":{"anyOf":[{"type":"number","enum":[8000]},{"type":"number","enum":[16000]},{"type":"number","enum":[22050]},{"type":"number","enum":[24000]},{"type":"number","enum":[44100]},{"type":"number","enum":[48000]}],"default":24000},"speed":{"type":"number","minimum":0.5,"maximum":2,"default":1},"stream":{"type":"boolean","default":false},"cfg":{"type":"number","minimum":0,"maximum":10,"default":2},"voice_prompt":{"type":"string","minLength":1,"maxLength":500,"description":"Optional free-form description of a voice. Honoured by tiers that advertise the `voice_prompt` capability (today: `hakim-v3` only). On tiers that do not advertise it, the field is dropped and the response carries a `voice_prompt_dropped_by_model_capability` entry in the `x-hakim-warnings` header. Use the `/v1/audio/voices/design` endpoint when the prompt IS the request — that endpoint returns 422 instead of stripping."}},"required":["model","input","voice"],"additionalProperties":false},"TranscriptionRequest":{"type":"object","properties":{"model":{"type":"string","enum":["hakim-arab-v2","hakim-voxtral-v1"]},"language":{"anyOf":[{"type":"string","enum":["auto"]},{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["ar-LV"]}],"default":"auto"},"response_format":{"type":"string","enum":["json","text","srt","vtt","verbose_json"],"default":"json"},"timestamps":{"type":"string","enum":["word","segment","none"],"default":"segment"},"diarize":{"type":"boolean","default":false}},"required":["model"],"additionalProperties":false},"Voice":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["preset","cloned"]},"language":{"anyOf":[{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["multi"]}]},"gender":{"type":"string","enum":["male","female","neutral"]},"voice_type":{"type":"string","enum":["conversational","narrative","news","social_media","advertising","elearning","character","customer_service"]},"description":{"type":"string","nullable":true},"preview_url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["processing","ready","failed"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","slug","name","kind","language","gender","voice_type","description","preview_url","status"],"additionalProperties":false},"VoicesListQuery":{"type":"object","properties":{"language":{"anyOf":[{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["multi"]}]},"gender":{"type":"string","enum":["male","female","neutral"]},"voice_type":{"type":"string","enum":["conversational","narrative","news","social_media","advertising","elearning","character","customer_service"]},"kind":{"type":"string","enum":["preset","cloned"]}},"additionalProperties":false},"VoicesListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["preset","cloned"]},"language":{"anyOf":[{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["multi"]}]},"gender":{"type":"string","enum":["male","female","neutral"]},"voice_type":{"type":"string","enum":["conversational","narrative","news","social_media","advertising","elearning","character","customer_service"]},"description":{"type":"string","nullable":true},"preview_url":{"type":"string","format":"uri","nullable":true},"status":{"type":"string","enum":["processing","ready","failed"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","slug","name","kind","language","gender","voice_type","description","preview_url","status"],"additionalProperties":false}}},"required":["object","data"],"additionalProperties":false},"UsageSummary":{"type":"object","properties":{"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"],"additionalProperties":false},"tts":{"type":"object","properties":{"characters":{"type":"integer","minimum":0},"included":{"type":"integer","minimum":0},"overage_chars":{"type":"integer","minimum":0}},"required":["characters","included","overage_chars"],"additionalProperties":false},"stt":{"type":"object","properties":{"seconds":{"type":"integer","minimum":0},"included":{"type":"integer","minimum":0},"overage_seconds":{"type":"integer","minimum":0}},"required":["seconds","included","overage_seconds"],"additionalProperties":false},"estimated_overage_usd":{"type":"number","minimum":0}},"required":["period","tts","stt","estimated_overage_usd"],"additionalProperties":false},"UsageEvent":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["tts","stt_batch","stt_realtime","voice_clone"]},"units":{"type":"integer","minimum":0},"api_key_id":{"type":"string","nullable":true},"request_id":{"type":"string","nullable":true},"status_code":{"type":"integer","nullable":true},"latency_ms":{"type":"integer","minimum":0,"nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","kind","units","api_key_id","request_id","status_code","latency_ms","created_at"],"additionalProperties":false},"UsageEventsList":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["tts","stt_batch","stt_realtime","voice_clone"]},"units":{"type":"integer","minimum":0},"api_key_id":{"type":"string","nullable":true},"request_id":{"type":"string","nullable":true},"status_code":{"type":"integer","nullable":true},"latency_ms":{"type":"integer","minimum":0,"nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","kind","units","api_key_id","request_id","status_code","latency_ms","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["data","has_more","next_cursor"],"additionalProperties":false},"UsageQuery":{"type":"object","properties":{"kind":{"type":"string","enum":["tts","stt_batch","stt_realtime","voice_clone"]},"limit":{"type":"integer","minimum":1,"maximum":100,"default":50},"cursor":{"type":"string"}},"additionalProperties":false},"VoiceCloneRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":64},"description":{"type":"string","maxLength":500},"language":{"anyOf":[{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["multi"]}]},"voice_type":{"type":"string","enum":["conversational","narrative","news","social_media","advertising","elearning","character","customer_service"],"default":"conversational"},"dialect":{"type":"string","minLength":1,"maxLength":64},"accent":{"type":"string","minLength":1,"maxLength":64},"age_band":{"type":"string","enum":["young","adult","mature"]},"tags":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"consent_confirmed":{"type":"boolean","enum":[true]}},"required":["name","language","consent_confirmed"],"additionalProperties":false},"VoiceDeletedResponse":{"type":"object","properties":{"object":{"type":"string","enum":["voice"]},"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["object","id","deleted"],"additionalProperties":false},"Job":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["batch_stt","voice_clone","bulk_tts"]},"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"progress_pct":{"type":"number","minimum":0,"maximum":100},"result_url":{"type":"string","format":"uri","nullable":true},"error_message":{"type":"string","nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","type","status","progress_pct","result_url","error_message","created_at","finished_at"],"additionalProperties":false},"JobsListQuery":{"type":"object","properties":{"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"type":{"type":"string","enum":["batch_stt","voice_clone","bulk_tts"]},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"cursor":{"type":"string"}},"additionalProperties":false},"JobsListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["batch_stt","voice_clone","bulk_tts"]},"status":{"type":"string","enum":["queued","processing","succeeded","failed","canceled"]},"progress_pct":{"type":"number","minimum":0,"maximum":100},"result_url":{"type":"string","format":"uri","nullable":true},"error_message":{"type":"string","nullable":true},"error_code":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true}},"required":["id","type","status","progress_pct","result_url","error_message","created_at","finished_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"minItems":1},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","url","events","active","created_at"],"additionalProperties":false},"WebhookCreated":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"minItems":1},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"secret":{"type":"string","minLength":32}},"required":["id","url","events","active","created_at","secret"],"additionalProperties":false},"WebhookCreateRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"minItems":1,"maxItems":6},"active":{"type":"boolean"}},"required":["url","events"],"additionalProperties":false},"WebhookUpdateRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"minItems":1,"maxItems":6},"active":{"type":"boolean"}},"additionalProperties":false},"WebhooksListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"minItems":1},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","url","events","active","created_at"],"additionalProperties":false}}},"required":["object","data"],"additionalProperties":false},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"webhook_id":{"type":"string"},"event":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"status":{"type":"string","enum":["pending","succeeded","failed"]},"status_code":{"type":"integer","nullable":true},"attempts":{"type":"integer","minimum":0},"next_retry_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","webhook_id","event","status","status_code","attempts","next_retry_at","delivered_at","created_at"],"additionalProperties":false},"WebhookDeliveriesListQuery":{"type":"object","properties":{"webhook_id":{"type":"string"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20},"cursor":{"type":"string"}},"additionalProperties":false},"WebhookDeliveriesListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"webhook_id":{"type":"string"},"event":{"type":"string","enum":["job.completed","voice.ready","voice.failed","usage.threshold.reached","invoice.paid","invoice.payment_failed"]},"status":{"type":"string","enum":["pending","succeeded","failed"]},"status_code":{"type":"integer","nullable":true},"attempts":{"type":"integer","minimum":0},"next_retry_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"}},"required":["id","webhook_id","event","status","status_code","attempts","next_retry_at","delivered_at","created_at"],"additionalProperties":false}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}},"required":["object","data","has_more","next_cursor"],"additionalProperties":false},"Profile":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"email_verified":{"type":"boolean"},"name":{"type":"string","nullable":true},"locale":{"type":"string","enum":["ar","en"]},"timezone":{"type":"string"},"avatar_url":{"type":"string","format":"uri","nullable":true},"marketing_opt_in":{"type":"boolean"}},"required":["id","email","email_verified","name","locale","timezone","avatar_url","marketing_opt_in"],"additionalProperties":false},"ProfileUpdateRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":120,"nullable":true},"locale":{"type":"string","enum":["ar","en"]},"timezone":{"type":"string","minLength":3,"maxLength":64,"pattern":"^(?:UTC|[A-Z][A-Za-z]+(?:[_-][A-Za-z]+)*(?:\\/[A-Z][A-Za-z0-9]+(?:[_-][A-Za-z0-9]+)*){1,2})$"},"marketing_opt_in":{"type":"boolean"}},"additionalProperties":false},"OrganizationSettings":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"billing_email":{"type":"string","format":"email","nullable":true},"default_locale":{"type":"string","enum":["ar","en"]},"logo_url":{"type":"string","format":"uri","nullable":true}},"required":["id","name","slug","billing_email","default_locale","logo_url"],"additionalProperties":false},"OrganizationSettingsUpdateRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"slug":{"type":"string","minLength":3,"maxLength":48,"pattern":"^[a-z0-9]+(?:-[a-z0-9]+)*$"},"billing_email":{"type":"string","format":"email","maxLength":320,"nullable":true},"default_locale":{"type":"string","enum":["ar","en"]}},"additionalProperties":false},"NotificationPreferences":{"type":"object","properties":{"job_completions":{"type":"boolean"},"voice_ready":{"type":"boolean"},"billing_alerts":{"type":"boolean"},"product_updates":{"type":"boolean"}},"required":["job_completions","voice_ready","billing_alerts","product_updates"],"additionalProperties":false},"NotificationPreferencesUpdateRequest":{"type":"object","properties":{"job_completions":{"type":"boolean"},"voice_ready":{"type":"boolean"},"billing_alerts":{"type":"boolean"},"product_updates":{"type":"boolean"}},"additionalProperties":false},"TranscriptionJsonResponse":{"type":"object","required":["text"],"properties":{"text":{"type":"string"},"language":{"type":"string"},"duration":{"type":"number"}},"additionalProperties":true},"TranscriptionAsyncAccepted":{"type":"object","required":["id","status","type","reason","poll_url"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued"]},"type":{"type":"string","enum":["stt_batch"]},"reason":{"type":"string","enum":["size_gt_25mb","duration_gt_10min"]},"limits":{"type":"object","properties":{"max_sync_size_bytes":{"type":"integer"},"max_sync_duration_seconds":{"type":"integer"}}},"poll_url":{"type":"string"}}},"RealtimeSttSession":{"type":"object","properties":{"model":{"type":"string","enum":["hakim-arab-v2","hakim-voxtral-v1"],"default":"hakim-arab-v2"},"language":{"anyOf":[{"type":"string","enum":["auto"]},{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["ar-LV"]}],"default":"auto"},"timestamps":{"type":"string","enum":["word","segment","none"],"default":"none"},"diarize":{"type":"boolean","default":false},"partials":{"type":"boolean","default":true},"input_audio_format":{"type":"string","enum":["pcm16","opus","mulaw"],"default":"pcm16"},"input_sample_rate":{"anyOf":[{"type":"number","enum":[8000]},{"type":"number","enum":[16000]},{"type":"number","enum":[22050]},{"type":"number","enum":[24000]},{"type":"number","enum":[44100]},{"type":"number","enum":[48000]}],"default":16000}},"additionalProperties":false},"RealtimeClientFrame":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["session.update"]},"session":{"type":"object","properties":{"model":{"type":"string","enum":["hakim-arab-v2","hakim-voxtral-v1"],"default":"hakim-arab-v2"},"language":{"anyOf":[{"type":"string","enum":["auto"]},{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["ar-LV"]}],"default":"auto"},"timestamps":{"type":"string","enum":["word","segment","none"],"default":"none"},"diarize":{"type":"boolean","default":false},"partials":{"type":"boolean","default":true},"input_audio_format":{"type":"string","enum":["pcm16","opus","mulaw"],"default":"pcm16"},"input_sample_rate":{"anyOf":[{"type":"number","enum":[8000]},{"type":"number","enum":[16000]},{"type":"number","enum":[22050]},{"type":"number","enum":[24000]},{"type":"number","enum":[44100]},{"type":"number","enum":[48000]}],"default":16000}},"additionalProperties":false}},"required":["type","session"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_audio_buffer.append"]},"audio":{"type":"string","minLength":1},"audio_ms":{"type":"integer","minimum":0}},"required":["type","audio"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_audio_buffer.commit"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["session.close"]}},"required":["type"],"additionalProperties":false}]},"RealtimeServerFrame":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["session.created"]},"event_id":{"type":"integer","minimum":0},"session_id":{"type":"string","minLength":1},"session":{"type":"object","properties":{"model":{"type":"string","enum":["hakim-arab-v2","hakim-voxtral-v1"],"default":"hakim-arab-v2"},"language":{"anyOf":[{"type":"string","enum":["auto"]},{"type":"string","enum":["ar","en","fr","es","de","it","pt","tr","ur","hi","fa","he","nl","ru","pl","uk","ja","ko","zh","th","vi","id","ms","sw","am","bn","ta","el","ps","ku","cs","ro","hu","fi","sv","no","da"]},{"type":"string","enum":["ar-SA","ar-AE","ar-EG","ar-SY","ar-LB","ar-JO","ar-PS","ar-MA","ar-DZ","ar-IQ","ar-SD","ar-YE"]},{"type":"string","enum":["ar-LV"]}],"default":"auto"},"timestamps":{"type":"string","enum":["word","segment","none"],"default":"none"},"diarize":{"type":"boolean","default":false},"partials":{"type":"boolean","default":true},"input_audio_format":{"type":"string","enum":["pcm16","opus","mulaw"],"default":"pcm16"},"input_sample_rate":{"anyOf":[{"type":"number","enum":[8000]},{"type":"number","enum":[16000]},{"type":"number","enum":[22050]},{"type":"number","enum":[24000]},{"type":"number","enum":[44100]},{"type":"number","enum":[48000]}],"default":16000}},"additionalProperties":false},"limits":{"type":"object","properties":{"max_session_duration_seconds":{"type":"integer","exclusiveMinimum":true,"minimum":0},"max_frame_bytes":{"type":"integer","exclusiveMinimum":true,"minimum":0},"heartbeat_interval_seconds":{"type":"integer","exclusiveMinimum":true,"minimum":0}},"required":["max_session_duration_seconds","max_frame_bytes","heartbeat_interval_seconds"],"additionalProperties":false}},"required":["type","event_id","session_id","session","limits"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["transcription.delta"]},"event_id":{"type":"integer","minimum":0},"text":{"type":"string"},"is_final":{"type":"boolean"},"start_ms":{"type":"number","minimum":0},"end_ms":{"type":"number","minimum":0},"words":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string"},"start_ms":{"type":"number","minimum":0},"end_ms":{"type":"number","minimum":0}},"required":["word","start_ms","end_ms"],"additionalProperties":false}},"speaker":{"type":"string"}},"required":["type","event_id","text","is_final"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["transcription.done"]},"event_id":{"type":"integer","minimum":0},"text":{"type":"string"},"audio_ms":{"type":"integer","minimum":0},"language":{"type":"string"}},"required":["type","event_id","text","audio_ms"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["error"]},"event_id":{"type":"integer","minimum":0},"code":{"type":"string","minLength":1},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["type","event_id","code","message","retryable"],"additionalProperties":false}]},"RealtimeSttLimits":{"type":"object","description":"Static per-session limits enforced by the realtime STT proxy. The values here are echoed back to clients in the `session.created` frame so SDKs can surface them at the UI layer.","required":["max_session_duration_seconds","max_frame_bytes","heartbeat_interval_seconds","upstream_idle_timeout_seconds"],"properties":{"max_session_duration_seconds":{"type":"integer","description":"Hard ceiling on a single session before the proxy emits `session_too_long` and closes the socket. Aligns with the 15-minute realtime privacy target.","const":900},"max_frame_bytes":{"type":"integer","description":"Per-frame byte cap. Bigger frames are rejected with `frame_too_large`.","const":131072},"heartbeat_interval_seconds":{"type":"integer","description":"Cadence of the proxy→client WebSocket ping. Clients should treat the absence of a frame for ≥ 2× this interval as a stall.","const":15},"upstream_idle_timeout_seconds":{"type":"integer","description":"Maximum upstream silence before the proxy closes with `upstream_timeout` (retryable).","const":60}}}},"parameters":{"XRequestId":{"name":"X-Request-Id","in":"header","description":"Optional client-generated idempotent request identifier. Must match `^[A-Za-z0-9_-]{8,128}$`, otherwise it is ignored and the server generates a UUIDv4. Returned on every response.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"},"required":false},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","description":"Idempotency token for mutating calls (`POST /v1/audio/speech`). Stripe-like semantics: same key + same body ⇒ cached 2xx replay; same key + different body ⇒ 409 `idempotency_conflict`. 24-hour TTL.","schema":{"type":"string","minLength":1,"maxLength":255},"required":false}}}}