Expressions and niqqud
Inline expressions - the website's Hebrew markers and audio tags such as [whispers] - what is refused, and how your niqqud is kept.
Send "input_format": "kolimina_markup_v1" to use expressions inside the text. Two kinds work together: the website's Hebrew markers, a label in parentheses such as (לחישה) or (נרגש), and audio tags in square brackets such as [whispers], [laughs] or [excited]. GET /voices/{voice_id}/capabilities lists both (expressions and expression_tags). A tag may combine up to three qualities, separated by commas: [whispering, playful]. Case and spacing don't matter.
Place an expression right before the words it should change; it stays with its sentence when the text is split. Expressions are never read aloud, never corrected or vocalized as words, and never counted: credits are the spoken characters only.
Anything else in square brackets is refused before anything is charged: an unknown instruction such as [pirate voice] with 422 unsupported_expression, broken syntax (a missing "]", "[]", nested brackets, a line break inside) with 422 invalid_expression_syntax. Square brackets are never read as text, so write a literal aside in round parentheses. In "plain" (the default) any expression is refused with 422 markup_requires_markup_format.
Words you vocalize yourself (niqqud) are locked before any automatic correction: the pipeline never rewrites them, next to an expression or not. The pronunciation order is your dictionary → Kolimina's store → the gender layer → the language model.
curl -s -X POST "https://kolimina.com/api/public/v1/narrations" \
-H "Authorization: Bearer $KOLIMINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: expressions-1" \
-d '{"voice_id": "voice_…", "input_format": "kolimina_markup_v1", "sentences": [{"client_sentence_id": "opening", "text": "[excited] איזה יופי שהצטרפתם אלינו!"}, {"client_sentence_id": "aside", "text": "[whispers] ועכשיו נגלה לכם סוד קטן. (צוחק)"}]}'Correcting a sentence that has an expression
A correction sends the sentence's full new text, expressions included, with the same input_format. Only that sentence is voiced again, with the narration's voice and style; the master is rebuilt from the other sentences' unchanged files. A changed expression is a changed sentence: it is always generated again, never taken from an earlier take.
curl -s -X PATCH "https://kolimina.com/api/public/v1/narrations/nar_…/sentences/sent_…" \
-H "Authorization: Bearer $KOLIMINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: fix-aside-1" \
-d '{"base_revision": 1, "input_format": "kolimina_markup_v1", "text": "[whispering, playful] ועכשיו נגלה לכם סוד גדול."}'Unsupported tags and failures
A refused tag is named in the error, and nothing is created or charged.
Expressions are never dropped, replaced or voiced in another way. If they can't be voiced at the moment, the job fails with expressions_unavailable: nothing is charged and, for a correction, the previous revision stays current. Retry later, or send the sentence without the expression.
curl -s -X POST "https://kolimina.com/api/public/v1/narrations" \
-H "Authorization: Bearer $KOLIMINA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: expressions-2" \
-d '{"voice_id": "voice_…", "input_format": "kolimina_markup_v1", "text": "[pirate voice] אהוי, חברים!"}'{"error": {"code": "unsupported_expression", "message": "\"[pirate voice]\" is not a supported expression. …", "field": "text", "request_id": "req_…"}}{"job_id": "job_…", "status": "failed", "error": {"code": "expressions_unavailable", "message": "A sentence's expressions could not be voiced right now; …"}}