דלג לתוכן הראשי
Kolimina - עברית שנשמעת נכון

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

get/me

Account, eligibility, credits, budgets and limits

  • 200 The account
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/voices

The voices this account may use

  • 200 Voices with their styles
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/voices/{voice_id}/capabilities

Formats, styles, expressions (markers and audio tags) and speeds of a voice

  • voice_id (path, required)
  • 200 Capabilities
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such voice.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
post/narrations

Create 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

  • 202 Accepted (not yet synthesized). Location points to the job.
  • 400 invalid_request (malformed, unknown field, missing Idempotency-Key).
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 402 insufficient_credits, key_credit_limit_exceeded or account_budget_exceeded.
  • 403 api_not_enabled or scope_denied.
  • 409 idempotency_conflict, or idempotency_in_progress (retry the same request after Retry-After).
  • 413 payload_too_large.
  • 422 unsupported_expression, invalid_expression_syntax, markup_requires_markup_format, invalid_voice, invalid_style, unsupported_speed, text_limit_exceeded, max_credits_exceeded.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/narrations

List narrations (newest first)

  • limit (query)
  • cursor (query)
  • 200 A page of narrations and next_cursor
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/narrations/{narration_id}

A narration and its published revision

  • narration_id (path, required)
  • 200 The narration
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such narration.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
delete/narrations/{narration_id}

Delete a narration (hidden at once, files purged later)

  • narration_id (path, required)
  • 204 Deleted
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such narration.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/narrations/{narration_id}/revisions/{revision}

An immutable revision's manifest

  • narration_id (path, required)
  • revision (path, required)
  • 200 The manifest
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such revision.
  • 410 revision_expired.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/narrations/{narration_id}/revisions/{revision}/audio

The revision's master MP3 (Range supported)

  • narration_id (path, required)
  • revision (path, required)
  • 200 audio/mpeg
  • 206 A byte range
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such audio.
  • 410 asset_expired.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/narrations/{narration_id}/revisions/{revision}/sentences/{sentence_id}/audio

One sentence's MP3 in that revision

  • narration_id (path, required)
  • revision (path, required)
  • sentence_id (path, required)
  • 200 audio/mpeg
  • 206 A byte range
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such audio.
  • 410 asset_expired.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
patch/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

  • 202 Accepted
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 409 revision_conflict, narration_busy, idempotency_conflict.
  • 422 Refused text: unsupported_expression, invalid_expression_syntax, markup_requires_markup_format, text_limit_exceeded.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
post/narrations/{narration_id}/sentences/{sentence_id}/regenerations

Re-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

  • 202 Accepted
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 409 revision_conflict, narration_busy.
  • 422 unsupported_expression or invalid_expression_syntax: the stored sentence has an expression that is no longer valid; correct it with PATCH.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/jobs/{job_id}

A job's status, result or error

  • job_id (path, required)
  • 200 The job (a failed job is still HTTP 200)
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such job.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
post/jobs/{job_id}/cancel

Request cancellation (a provider call already sent may still finish)

  • job_id (path, required)
  • 202 Cancellation requested; wait for the terminal status
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 409 job_already_finished.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
post/narration-previews

Preview: 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

  • 202 Accepted
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 422 Refused text or voice.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/narration-previews/{preview_id}

A preview's status, processed sentences and estimated credits

  • preview_id (path, required)
  • 200 The preview
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such preview.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
post/assets/{asset_id}/download-links

A 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}
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 404 No such asset.
  • 410 asset_expired.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.
get/asset-links/{token}no API key

Download through a temporary link (no API key)

  • token (path, required)
  • 200 audio/mpeg
  • 401 link_invalid_or_expired.
  • 404 No longer available.
  • 410 asset_expired.
get/usage

Credits charged and reserved by API work

  • from (query)
  • to (query)
  • 200 Totals, by key, by narration, and operations
  • 401 Missing, invalid, expired or revoked API key (invalid_api_key).
  • 403 api_not_enabled or scope_denied.
  • 429 rate_limit_exceeded or queue_full; honour Retry-After.

Webhook events

eventnarration.created

A 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

  • 200 Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
eventnarration.updated

A 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

  • 200 Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
eventnarration.failed

A 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

  • 200 Any 2xx acknowledges the event. Anything else (or no answer within 10 s) is retried.
eventnarration.canceled

A 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

  • 200 Any 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*stringOne editable unit (at most 300 spoken characters). Max 2000 characters.
client_sentence_idstring 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.

textstring Max 8000 characters.
sentencesSentenceInput[] Max 200 items.
voice_idstring
style_idstringFrom 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"
speed0.85 | 1 | 1.1 | 1.15 Default: 1.
text_gender"masculine" | "feminine" Default: "masculine".
max_creditsintegerRefused (422 max_credits_exceeded) if the narration would cost more.
client_referencestring Max 200 characters.
metadataobject
webhook_endpoint_idstringSend 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_idstringCreate exactly the snapshot of a ready preview.

Accepted

narration_idstring
sentence_idstring
job_idstring
status"queued"
base_revisioninteger | null
current_revisioninteger | null
poll_pathstring

Job

job_idstring
kind"create" | "correction" | "regeneration"
status"queued" | "processing" | "succeeded" | "failed" | "canceled"
stagestring | null
narration_idstring
sentence_idstring | null
base_revisioninteger | null
created_atstring
finished_atstring | null
resultobject | null
errorobject | null

Audio

asset_idstring
content_type"audio/mpeg"
duration_msinteger
download_pathstring

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_idstring
revisioninteger
voice_idstring | null
speednumber
created_atstring
superseded_atstring | null
retained_untilstring | nullA superseded revision stays available until then.
audioAudio
sentencesobject[]

Narration

narration_idstring
status"processing" | "ready" | "failed" | "preparing"
source"web" | "api" | "editor"
client_referencestring | null
metadataobject | null
voice_idstring | null
created_atstring
current_revisioninteger | null
revision_pathstring | null
active_jobobject | null

CorrectSentence

base_revision*integer | nullThe 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"