{"openapi":"3.1.0","info":{"title":"Kolimina Narration API","version":"1.0.0","description":"Hebrew narration through the same pipeline as kolimina.com. Work is asynchronous: creation and corrections answer 202 with a job; poll it (every 2–5 s, honouring Retry-After) and then fetch the revision it produced. There is no model to choose: every narration uses the same voice engine. Per-sentence styles are not supported in v1: set the narration's `style_id`. Inline expressions - the website's Hebrew markers, e.g. (לחישה), and the audio tags listed by a voice's capabilities, e.g. [whispers] - need input_format `kolimina_markup_v1`; any other square bracket is refused (422 unsupported_expression or invalid_expression_syntax), never read aloud or dropped. Expressions are not billed: credits count the spoken characters. A job whose expressions can't be voiced fails with expressions_unavailable (nothing charged, the previous revision stays); they are never replaced or removed."},"servers":[{"url":"https://kolimina.com/api/public/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"An API key from the dashboard (מפתחים / API). Server-side only - never in browser code."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":"string"},"request_id":{"type":["string","null"]}}}}},"WebhookEvent":{"type":"object","required":["event_id","type","created_at","data"],"properties":{"event_id":{"type":"string","pattern":"^evt_[0-9a-f]{32}$"},"type":{"enum":["narration.created","narration.updated","narration.failed","narration.canceled"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"narration_id":{"type":"string"},"job_id":{"type":"string"},"revision":{"type":["integer","null"]},"revision_path":{"type":["string","null"],"description":"GET this path (relative to the API base) for the revision manifest."},"client_reference":{"type":["string","null"]},"error_code":{"type":"string","description":"failed / canceled only."}}}}},"SentenceInput":{"type":"object","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","maxLength":2000,"description":"One editable unit (at most 300 spoken characters)."},"client_sentence_id":{"type":"string","maxLength":100}}},"CreateNarration":{"type":"object","additionalProperties":false,"description":"`voice_id` and exactly one of `text` or `sentences` - or only `preview_id` (plus max_credits, client_reference, metadata, webhook_endpoint_id) to create from a preview. `sentences` keeps your editing boundaries; it is priced like the same text typed one sentence per line.","properties":{"text":{"type":"string","maxLength":8000},"sentences":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/SentenceInput"}},"voice_id":{"type":"string"},"style_id":{"type":"string","description":"From the voice's capabilities. Default: natural_friendly."},"language":{"const":"he"},"input_format":{"enum":["plain","kolimina_markup_v1"],"default":"plain","description":"plain is text only (expressions refused). kolimina_markup_v1 adds expressions: Hebrew markers and the audio tags in expression_tags; any other square bracket is refused in both."},"output_format":{"const":"mp3"},"speed":{"enum":[0.85,1,1.1,1.15],"default":1},"text_gender":{"enum":["masculine","feminine"],"default":"masculine"},"max_credits":{"type":"integer","minimum":1,"description":"Refused (422 max_credits_exceeded) if the narration would cost more."},"client_reference":{"type":"string","maxLength":200},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"maxProperties":20},"webhook_endpoint_id":{"type":"string","description":"Send this narration's events to this endpoint only (default: every enabled endpoint of the account). Unknown or another account's: 422 invalid_webhook_endpoint."},"preview_id":{"type":"string","description":"Create exactly the snapshot of a ready preview."}}},"Accepted":{"type":"object","properties":{"narration_id":{"type":"string"},"sentence_id":{"type":"string"},"job_id":{"type":"string"},"status":{"const":"queued"},"base_revision":{"type":["integer","null"]},"current_revision":{"type":["integer","null"]},"poll_path":{"type":"string"}}},"Job":{"type":"object","properties":{"job_id":{"type":"string"},"kind":{"enum":["create","correction","regeneration"]},"status":{"enum":["queued","processing","succeeded","failed","canceled"]},"stage":{"type":["string","null"]},"narration_id":{"type":"string"},"sentence_id":{"type":["string","null"]},"base_revision":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"result":{"type":["object","null"],"properties":{"narration_id":{"type":"string"},"revision":{"type":"integer"},"revision_path":{"type":"string"}}},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Audio":{"type":"object","properties":{"asset_id":{"type":"string"},"content_type":{"const":"audio/mpeg"},"duration_ms":{"type":"integer"},"download_path":{"type":"string"}}},"Revision":{"type":"object","description":"Immutable. start_ms/end_ms are unit boundaries in the master (not word timestamps); gap_after_ms is the silence after a unit (not in the sentence file).","properties":{"narration_id":{"type":"string"},"revision":{"type":"integer"},"voice_id":{"type":["string","null"]},"speed":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"superseded_at":{"type":["string","null"],"format":"date-time"},"retained_until":{"type":["string","null"],"format":"date-time","description":"A superseded revision stays available until then."},"audio":{"$ref":"#/components/schemas/Audio"},"sentences":{"type":"array","items":{"type":"object","properties":{"sentence_id":{"type":"string"},"sentence_revision":{"type":"integer"},"index":{"type":"integer"},"client_sentence_id":{"type":["string","null"]},"source_text":{"type":["string","null"]},"display_text":{"type":["string","null"]},"start_ms":{"type":"integer"},"end_ms":{"type":"integer"},"gap_after_ms":{"type":"integer"},"audio":{"$ref":"#/components/schemas/Audio"}}}}}},"Narration":{"type":"object","properties":{"narration_id":{"type":"string"},"status":{"enum":["processing","ready","failed","preparing"]},"source":{"enum":["web","api","editor"]},"client_reference":{"type":["string","null"]},"metadata":{"type":["object","null"]},"voice_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"current_revision":{"type":["integer","null"]},"revision_path":{"type":["string","null"]},"active_job":{"type":["object","null"],"properties":{"job_id":{"type":"string"},"status":{"type":"string"}}}}},"CorrectSentence":{"type":"object","additionalProperties":false,"required":["base_revision","text"],"properties":{"base_revision":{"type":["integer","null"],"description":"The revision you corrected. A newer one → 409 revision_conflict."},"text":{"type":"string","maxLength":2000},"input_format":{"enum":["plain","kolimina_markup_v1"]},"config_resolution":{"const":"current_voice_style","description":"Only for a narration whose original style was never stored (409 legacy_config_unavailable)."}}},"Regenerate":{"type":"object","additionalProperties":false,"required":["base_revision"],"properties":{"base_revision":{"type":["integer","null"]},"config_resolution":{"const":"current_voice_style"}}}}},"paths":{"/me":{"get":{"summary":"Account, eligibility, credits, budgets and limits","responses":{"200":{"description":"The account"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/voices":{"get":{"summary":"The voices this account may use","responses":{"200":{"description":"Voices with their styles"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/voices/{voice_id}/capabilities":{"get":{"summary":"Formats, styles, expressions (markers and audio tags) and speeds of a voice","parameters":[{"name":"voice_id","in":"path","required":true,"schema":{"type":"string","pattern":"^voice_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"Capabilities"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such voice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations":{"post":{"summary":"Create a narration","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Your own stable id of this operation (1–255 printable characters). Reuse it, with the same body, for every retry: you get the original operation back, even if the first response was lost or its job later failed. The same key with another body is 409 idempotency_conflict. Records are kept at least 7 days and never before the operation's job has ended.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNarration"}}}},"responses":{"202":{"description":"Accepted (not yet synthesized). Location points to the job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"400":{"description":"invalid_request (malformed, unknown field, missing Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits, key_credit_limit_exceeded or account_budget_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict, or idempotency_in_progress (retry the same request after Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unsupported_expression, invalid_expression_syntax, markup_requires_markup_format, invalid_voice, invalid_style, unsupported_speed, text_limit_exceeded, max_credits_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List narrations (newest first)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of narrations and next_cursor"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations/{narration_id}":{"get":{"summary":"A narration and its published revision","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"The narration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Narration"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such narration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a narration (hidden at once, files purged later)","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such narration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations/{narration_id}/revisions/{revision}":{"get":{"summary":"An immutable revision's manifest","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}},{"name":"revision","in":"path","required":true,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"The manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Revision"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such revision.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"revision_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations/{narration_id}/revisions/{revision}/audio":{"get":{"summary":"The revision's master MP3 (Range supported)","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}},{"name":"revision","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"audio/mpeg","content":{"audio/mpeg":{}}},"206":{"description":"A byte range"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such audio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"asset_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations/{narration_id}/revisions/{revision}/sentences/{sentence_id}/audio":{"get":{"summary":"One sentence's MP3 in that revision","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}},{"name":"revision","in":"path","required":true,"schema":{"type":"integer"}},{"name":"sentence_id","in":"path","required":true,"schema":{"type":"string","pattern":"^sent_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"audio/mpeg","content":{"audio/mpeg":{}}},"206":{"description":"A byte range"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such audio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"asset_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations/{narration_id}/sentences/{sentence_id}":{"patch":{"summary":"Correct one sentence (only it is re-voiced and charged; the master is rebuilt)","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}},{"name":"sentence_id","in":"path","required":true,"schema":{"type":"string","pattern":"^sent_[0-9a-f]{32}$"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Your own stable id of this operation (1–255 printable characters). Reuse it, with the same body, for every retry: you get the original operation back, even if the first response was lost or its job later failed. The same key with another body is 409 idempotency_conflict. Records are kept at least 7 days and never before the operation's job has ended.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrectSentence"}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"revision_conflict, narration_busy, idempotency_conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Refused text: unsupported_expression, invalid_expression_syntax, markup_requires_markup_format, text_limit_exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narrations/{narration_id}/sentences/{sentence_id}/regenerations":{"post":{"summary":"Re-voice one sentence with unchanged text (a new paid generation)","parameters":[{"name":"narration_id","in":"path","required":true,"schema":{"type":"string","pattern":"^nar_[0-9a-f]{32}$"}},{"name":"sentence_id","in":"path","required":true,"schema":{"type":"string","pattern":"^sent_[0-9a-f]{32}$"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Your own stable id of this operation (1–255 printable characters). Reuse it, with the same body, for every retry: you get the original operation back, even if the first response was lost or its job later failed. The same key with another body is 409 idempotency_conflict. Records are kept at least 7 days and never before the operation's job has ended.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Regenerate"}}}},"responses":{"202":{"description":"Accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"revision_conflict, narration_busy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"unsupported_expression or invalid_expression_syntax: the stored sentence has an expression that is no longer valid; correct it with PATCH.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}":{"get":{"summary":"A job's status, result or error","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","pattern":"^job_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"The job (a failed job is still HTTP 200)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/jobs/{job_id}/cancel":{"post":{"summary":"Request cancellation (a provider call already sent may still finish)","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","pattern":"^job_[0-9a-f]{32}$"}}],"responses":{"202":{"description":"Cancellation requested; wait for the terminal status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"job_already_finished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narration-previews":{"post":{"summary":"Preview: the text through the preparation stages, its units and price - no audio, no credits","description":"Takes the same text and settings as a creation. Answers 202; poll GET /narration-previews/{preview_id}. Create from it with POST /narrations {\"preview_id\": …}: exactly this snapshot is synthesized; a preview that expired, was used, or whose voice, style or pricing changed is 409 preview_expired_or_stale. Previews are rate-limited per minute and per day.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNarration"}}}},"responses":{"202":{"description":"Accepted"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Refused text or voice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/narration-previews/{preview_id}":{"get":{"summary":"A preview's status, processed sentences and estimated credits","parameters":[{"name":"preview_id","in":"path","required":true,"schema":{"type":"string","pattern":"^prev_[0-9a-f]{32}$"}}],"responses":{"200":{"description":"The preview"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such preview.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/assets/{asset_id}/download-links":{"post":{"summary":"A temporary link to an audio asset (for playback or delivery without an API key)","description":"The link itself grants access until url_expires_at (default 15 minutes; ask for a new one any time). It stops working at once if the narration is deleted or the asset expires. Revoking an API key does not revoke a link issued earlier.","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","pattern":"^asset_[0-9a-f]{32}$"}}],"responses":{"201":{"description":"{asset_id, url, url_expires_at}"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such asset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"asset_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/asset-links/{token}":{"get":{"summary":"Download through a temporary link (no API key)","security":[],"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"audio/mpeg","content":{"audio/mpeg":{}}},"401":{"description":"link_invalid_or_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No longer available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"asset_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"summary":"Credits charged and reserved by API work","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Totals, by key, by narration, and operations"},"401":{"description":"Missing, invalid, expired or revoked API key (invalid_api_key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"api_not_enabled or scope_denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limit_exceeded or queue_full; honour Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"narration.created":{"post":{"summary":"A new narration finished: its first revision is ready","description":"At least once: deduplicate on event_id. Verify Kolimina-Signature before trusting the body: v1 = hex HMAC-SHA256(secret, event_id + \".\" + Kolimina-Timestamp + \".\" + raw_body); refuse timestamps more than 5 minutes old. After a secret rotation two v1 values are sent for 24 h: accept either. Retries at 1 m, 5 m, 30 m, 2 h, 8 h and 24 h after the event; redirects are not followed. The body carries ids only: fetch the revision with your API key.","parameters":[{"name":"Kolimina-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"The same for every attempt and every replay of this event."},{"name":"Kolimina-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of this attempt."},{"name":"Kolimina-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"v1=<hex>[, v1=<hex>]"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried."}}}},"narration.updated":{"post":{"summary":"A correction, regeneration or speed change published a new revision","description":"At least once: deduplicate on event_id. Verify Kolimina-Signature before trusting the body: v1 = hex HMAC-SHA256(secret, event_id + \".\" + Kolimina-Timestamp + \".\" + raw_body); refuse timestamps more than 5 minutes old. After a secret rotation two v1 values are sent for 24 h: accept either. Retries at 1 m, 5 m, 30 m, 2 h, 8 h and 24 h after the event; redirects are not followed. The body carries ids only: fetch the revision with your API key.","parameters":[{"name":"Kolimina-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"The same for every attempt and every replay of this event."},{"name":"Kolimina-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of this attempt."},{"name":"Kolimina-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"v1=<hex>[, v1=<hex>]"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried."}}}},"narration.failed":{"post":{"summary":"A job failed (no charge); the previous revision, if any, stays current","description":"At least once: deduplicate on event_id. Verify Kolimina-Signature before trusting the body: v1 = hex HMAC-SHA256(secret, event_id + \".\" + Kolimina-Timestamp + \".\" + raw_body); refuse timestamps more than 5 minutes old. After a secret rotation two v1 values are sent for 24 h: accept either. Retries at 1 m, 5 m, 30 m, 2 h, 8 h and 24 h after the event; redirects are not followed. The body carries ids only: fetch the revision with your API key.","parameters":[{"name":"Kolimina-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"The same for every attempt and every replay of this event."},{"name":"Kolimina-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of this attempt."},{"name":"Kolimina-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"v1=<hex>[, v1=<hex>]"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried."}}}},"narration.canceled":{"post":{"summary":"A job was canceled (no charge)","description":"At least once: deduplicate on event_id. Verify Kolimina-Signature before trusting the body: v1 = hex HMAC-SHA256(secret, event_id + \".\" + Kolimina-Timestamp + \".\" + raw_body); refuse timestamps more than 5 minutes old. After a secret rotation two v1 values are sent for 24 h: accept either. Retries at 1 m, 5 m, 30 m, 2 h, 8 h and 24 h after the event; redirects are not followed. The body carries ids only: fetch the revision with your API key.","parameters":[{"name":"Kolimina-Event-Id","in":"header","required":true,"schema":{"type":"string"},"description":"The same for every attempt and every replay of this event."},{"name":"Kolimina-Timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Unix seconds of this attempt."},{"name":"Kolimina-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"v1=<hex>[, v1=<hex>]"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"200":{"description":"Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried."}}}}}}