API reference
Kolimina Narration API v1.0.0 · https://kolimina.com/api/public/v1 · openapi.json
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.
Every call except a temporary download link and openapi.json needs Authorization: Bearer kol_live_…. Errors are {"error": {"code", "message", "field", "request_id"}}.
Endpoints
/meAccount, eligibility, credits, budgets and limits
200The account401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.429rate_limit_exceeded or queue_full; honour Retry-After.
/voicesThe voices this account may use
200Voices with their styles401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.429rate_limit_exceeded or queue_full; honour Retry-After.
/voices/{voice_id}/capabilitiesFormats, styles, expressions (markers and audio tags) and speeds of a voice
voice_id(path, required)
200Capabilities401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such voice.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrationsCreate a narration
Idempotency-Key(header, required) - 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.
Body: CreateNarration
202Accepted (not yet synthesized). Location points to the job.400invalid_request (malformed, unknown field, missing Idempotency-Key).401Missing, invalid, expired or revoked API key (invalid_api_key).402insufficient_credits, key_credit_limit_exceeded or account_budget_exceeded.403api_not_enabled or scope_denied.409idempotency_conflict, or idempotency_in_progress (retry the same request after Retry-After).413payload_too_large.422unsupported_expression, invalid_expression_syntax, markup_requires_markup_format, invalid_voice, invalid_style, unsupported_speed, text_limit_exceeded, max_credits_exceeded.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrationsList narrations (newest first)
limit(query)cursor(query)
200A page of narrations and next_cursor401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}A narration and its published revision
narration_id(path, required)
200The narration401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such narration.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}Delete a narration (hidden at once, files purged later)
narration_id(path, required)
204Deleted401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such narration.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}/revisions/{revision}An immutable revision's manifest
narration_id(path, required)revision(path, required)
200The manifest401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such revision.410revision_expired.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}/revisions/{revision}/audioThe revision's master MP3 (Range supported)
narration_id(path, required)revision(path, required)
200audio/mpeg206A byte range401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such audio.410asset_expired.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}/revisions/{revision}/sentences/{sentence_id}/audioOne sentence's MP3 in that revision
narration_id(path, required)revision(path, required)sentence_id(path, required)
200audio/mpeg206A byte range401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such audio.410asset_expired.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}/sentences/{sentence_id}Correct one sentence (only it is re-voiced and charged; the master is rebuilt)
narration_id(path, required)sentence_id(path, required)Idempotency-Key(header, required) - 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.
Body: CorrectSentence
202Accepted401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.409revision_conflict, narration_busy, idempotency_conflict.422Refused text: unsupported_expression, invalid_expression_syntax, markup_requires_markup_format, text_limit_exceeded.429rate_limit_exceeded or queue_full; honour Retry-After.
/narrations/{narration_id}/sentences/{sentence_id}/regenerationsRe-voice one sentence with unchanged text (a new paid generation)
narration_id(path, required)sentence_id(path, required)Idempotency-Key(header, required) - 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.
Body: Regenerate
202Accepted401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.409revision_conflict, narration_busy.422unsupported_expression or invalid_expression_syntax: the stored sentence has an expression that is no longer valid; correct it with PATCH.429rate_limit_exceeded or queue_full; honour Retry-After.
/jobs/{job_id}A job's status, result or error
job_id(path, required)
200The job (a failed job is still HTTP 200)401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such job.429rate_limit_exceeded or queue_full; honour Retry-After.
/jobs/{job_id}/cancelRequest cancellation (a provider call already sent may still finish)
job_id(path, required)
202Cancellation requested; wait for the terminal status401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.409job_already_finished.429rate_limit_exceeded or queue_full; honour Retry-After.
/narration-previewsPreview: the text through the preparation stages, its units and price - no audio, no credits
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.
Body: CreateNarration
202Accepted401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.422Refused text or voice.429rate_limit_exceeded or queue_full; honour Retry-After.
/narration-previews/{preview_id}A preview's status, processed sentences and estimated credits
preview_id(path, required)
200The preview401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such preview.429rate_limit_exceeded or queue_full; honour Retry-After.
/assets/{asset_id}/download-linksA temporary link to an audio asset (for playback or delivery without an API key)
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.
asset_id(path, required)
201{asset_id, url, url_expires_at}401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.404No such asset.410asset_expired.429rate_limit_exceeded or queue_full; honour Retry-After.
/asset-links/{token}no API keyDownload through a temporary link (no API key)
token(path, required)
200audio/mpeg401link_invalid_or_expired.404No longer available.410asset_expired.
/usageCredits charged and reserved by API work
from(query)to(query)
200Totals, by key, by narration, and operations401Missing, invalid, expired or revoked API key (invalid_api_key).403api_not_enabled or scope_denied.429rate_limit_exceeded or queue_full; honour Retry-After.
Webhook events
narration.createdA new narration finished: its first revision is ready
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.
Kolimina-Event-Id(header, required) - The same for every attempt and every replay of this event.Kolimina-Timestamp(header, required) - Unix seconds of this attempt.Kolimina-Signature(header, required) - v1=<hex>[, v1=<hex>]
Body: WebhookEvent
200Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
narration.updatedA correction, regeneration or speed change published a new revision
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.
Kolimina-Event-Id(header, required) - The same for every attempt and every replay of this event.Kolimina-Timestamp(header, required) - Unix seconds of this attempt.Kolimina-Signature(header, required) - v1=<hex>[, v1=<hex>]
Body: WebhookEvent
200Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
narration.failedA job failed (no charge); the previous revision, if any, stays current
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.
Kolimina-Event-Id(header, required) - The same for every attempt and every replay of this event.Kolimina-Timestamp(header, required) - Unix seconds of this attempt.Kolimina-Signature(header, required) - v1=<hex>[, v1=<hex>]
Body: WebhookEvent
200Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
narration.canceledA job was canceled (no charge)
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.
Kolimina-Event-Id(header, required) - The same for every attempt and every replay of this event.Kolimina-Timestamp(header, required) - Unix seconds of this attempt.Kolimina-Signature(header, required) - v1=<hex>[, v1=<hex>]
Body: WebhookEvent
200Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
Schemas
Error
| error* | object |
WebhookEvent
| event_id* | string | |
| type* | "narration.created" | "narration.updated" | "narration.failed" | "narration.canceled" | |
| created_at* | string | |
| data* | object |
SentenceInput
| text* | string | One editable unit (at most 300 spoken characters). Max 2000 characters. |
| client_sentence_id | string | Max 100 characters. |
CreateNarration
`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.
| text | string | Max 8000 characters. |
| sentences | SentenceInput[] | Max 200 items. |
| voice_id | string | |
| style_id | string | From the voice's capabilities. Default: natural_friendly. |
| language | "he" | |
| input_format | "plain" | "kolimina_markup_v1" | 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. Default: "plain". |
| output_format | "mp3" | |
| speed | 0.85 | 1 | 1.1 | 1.15 | Default: 1. |
| text_gender | "masculine" | "feminine" | Default: "masculine". |
| max_credits | integer | Refused (422 max_credits_exceeded) if the narration would cost more. |
| client_reference | string | Max 200 characters. |
| metadata | object | |
| webhook_endpoint_id | string | 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 | string | Create exactly the snapshot of a ready preview. |
Accepted
| narration_id | string | |
| sentence_id | string | |
| job_id | string | |
| status | "queued" | |
| base_revision | integer | null | |
| current_revision | integer | null | |
| poll_path | string |
Job
| job_id | string | |
| kind | "create" | "correction" | "regeneration" | |
| status | "queued" | "processing" | "succeeded" | "failed" | "canceled" | |
| stage | string | null | |
| narration_id | string | |
| sentence_id | string | null | |
| base_revision | integer | null | |
| created_at | string | |
| finished_at | string | null | |
| result | object | null | |
| error | object | null |
Audio
| asset_id | string | |
| content_type | "audio/mpeg" | |
| duration_ms | integer | |
| download_path | string |
Revision
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).
| narration_id | string | |
| revision | integer | |
| voice_id | string | null | |
| speed | number | |
| created_at | string | |
| superseded_at | string | null | |
| retained_until | string | null | A superseded revision stays available until then. |
| audio | Audio | |
| sentences | object[] |
Narration
| narration_id | string | |
| status | "processing" | "ready" | "failed" | "preparing" | |
| source | "web" | "api" | "editor" | |
| client_reference | string | null | |
| metadata | object | null | |
| voice_id | string | null | |
| created_at | string | |
| current_revision | integer | null | |
| revision_path | string | null | |
| active_job | object | null |
CorrectSentence
| base_revision* | integer | null | The revision you corrected. A newer one → 409 revision_conflict. |
| text* | string | Max 2000 characters. |
| input_format | "plain" | "kolimina_markup_v1" | |
| config_resolution | "current_voice_style" | Only for a narration whose original style was never stored (409 legacy_config_unavailable). |
Regenerate
| base_revision* | integer | null | |
| config_resolution | "current_voice_style" |
