Voiceover text: markup, normalization, billing

The text of a TTS order does not go to the generator as is: markup is stripped first, then the text is normalized, and only then is it split into chunks. Each step changes both what you hear and what you pay for; none of them is visible in the POST /orders response.

Three text channels, one set of rules

Text is accepted by three equivalent fields — input_text at the root of the request, a .txt inside input_files[] (up to 20 MB per file), and task_data.text for template-less services; all three go through the same checks. For TTS, put the text in the top-level input_text, not in task_data.

What is stripped from the voiceover

Three kinds of markup are recognized; none of them is read aloud verbatim, but only one is free:

The difference is not cosmetic: {{…}} is our format — the worker builds the silence from it, and the string never reaches the provider. Brackets and <break/> are the provider's own syntax: the provider receives them in full and counts them toward its length limit, so they take up space in the chunk: a 999-character chunk with [confident] inside holds 988 spoken characters.

Any square brackets are markup, not just a list of keywords

Any […] span with no nested brackets and no line break inside counts as a direction (regex /\[[^\[\]\n]+\]/u). A footnote [1], a [sic] note, a timecode [00:12] will not be spoken — the model will read them as directions about the reading style.

Parentheses, angle-bracket tags, and asterisks, by contrast, are voiced and billed: the narrator will read (пауза) and *шёпотом* aloud.

Pause caps

They are checked before the order is created; exceeding them returns 422, and no money is reserved. No more than 500 pauses per text, no single pause longer than 10 seconds, and no more than 3600 seconds of silence in total. Only {{pause}} and <break/> count; the legacy form [pause=2s] does not.

A separate rejection applies to text with nothing pronounceable left after markup is stripped: only tags → text_empty; only punctuation or only bracketed remarks → text_not_voiceable (named paragraph_not_voiceable in the OpenAPI spec). Both are 422.

Normalization before chunking

Chunk offsets (start/end) are counted from the modified text, not from the text you sent:

The last rule (a space after ./!/? before a letter or digit) leaves decimals, abbreviations, acronyms, URLs with a scheme, emails, and tag contents untouched. The trade-off: a bare domain without a scheme (example.com mid-sentence) is indistinguishable from Привет.Мир and will get a space — write such addresses with a scheme.

Paragraph mode (generation_mode)

By default, the text is cut sequentially by the technical chunk size, and paragraph boundaries play no role. Paragraph mode first splits the text on blank lines, and then each paragraph is chunked on its own. The key lives not inside tts_settings but at the root of config_override (or at the root of the template's config — then the mode is permanent):

{ "template_id": "<UUID>", "input_text": "Первый абзац.\n\nВторой абзац.",
  "config_override": { "generation_mode": "paragraph" } }

The values are paragraph and default. Supported by elevenlabs and heygen; other services silently ignore the key — there is no rejection, the mode simply does not turn on. It is not listed in GET /templates/config-options: that endpoint lists service settings, while the mode is set per order. At most 10 single-chunk paragraphs plus 5 multi-chunk paragraphs run concurrently per order.

The response gains paragraphs[] (for each paragraph: paragraph_index, chunks_count, completed_chunks, status, progress_percent) and a paragraph_index on chunks. Pitfalls:

• paragraphs[].status has its own vocabulary of four values (pending, in_progress, failed, completed); a chunk blocked by policy collapses into failed;
• only the original chunks (item_type = chunk) are counted: a successful retry of a failed chunk does not change the paragraph status. retry and regeneration records have paragraph_index set to null — get the paragraph from the parent via parent_item_id.

Calculate all of this in advance, for free

POST /orders/chunks/preview is a dry run of the same pipeline without creating an order: it costs no money and does not spend the key's token quota. summary returns voiced_length (what will actually be voiced), total_effective_length, total_price_units, min_billable_chars, and three diagnostic flags: voiced_empty (a future text_empty), caps_ok with caps_exceeded (count/single/total), and has_blocked_content with blocked_chunks[] — the last one shows blocklisted chunks before the order is even created (see retries). Unlike POST /orders, the preview does not fail on caps.