> Section "Writing text for speech" of the AthanLab Developer API documentation (API version 1.0.0). On the web: https://athanlab.com/docs#writing-text. Whole documentation as Markdown: https://athanlab.com/docs.md

# Writing text for speech

The API reads exactly the text you send. These rules make it sound natural and keep a request from being rejected.

## Sentences and punctuation

End every sentence with `။`, `!` or `?`, and keep sentences short. Text is spoken sentence by sentence, in pieces. A dry run's `dispatches` field counts the pieces your text becomes (see [Quote first with dry_run](https://athanlab.com/docs#dry-run)).

A sentence too long for one piece is cut at a `၊`, then at a space, and mid-word only as a last resort. So a long stretch without punctuation breaks in odd places. If a piece still cannot be made short enough, the request is rejected before any charge with [422 text_too_long](https://athanlab.com/docs#errors-text_too_long): “Part of the text is too long to speak in one piece. Add sentence punctuation and retry.”

## Burmese and English

Burmese, English, and Burmese with English words mixed in all work. Made-up names and brand names (for example `AthanLab`) can come out wrong. Spell them the way they sound in Burmese (`အသံလက်ဘ်`) and listen to a sample first.

## Marks the voice skips

Quotation marks, brackets and `…` are not spoken well. Remove them, or put a `၊` where you want a short pause. Text that is only emoji, punctuation or whitespace has nothing to read. It is rejected before any charge with [422 unspeakable_text](https://athanlab.com/docs#errors-unspeakable_text).

## Numbers

`number_mode` sets how digits are read. Here is each mode reading `ကျပ် ၁၂၃၄`:

| Mode | What it reads | ကျပ် ၁၂၃၄ is spoken as |
| --- | --- | --- |
| `smart` | The default. Burmese digits as Burmese words — digit by digit after a leading zero and for runs of 9 or more digits, with ဒဿမ for a decimal point. Latin digits (1234) are left as written. | ကျပ် တစ်ထောင့်နှစ်ရာ့သုံးဆယ့်လေး |
| `place` | Every number, in Burmese or Latin digits, as Burmese place words (up to 8 digits; longer runs digit by digit). | ကျပ် တစ်ထောင့်နှစ်ရာ့သုံးဆယ့်လေး |
| `digits` | Burmese, one digit at a time: phone numbers, codes, IDs. | ကျပ် တစ် နှစ် သုံး လေး |
| `english` | English number words. | ကျပ် one thousand two hundred thirty four |
| `english_digits` | English, one digit at a time. | ကျပ် one two three four |

Numbers written out as words cost nothing extra, but the expanded text must stay within 10,000 characters, or the request returns [422 text_too_long](https://athanlab.com/docs#errors-text_too_long).

## Scripts and dialogue

Split long scripts into sentence-sized lines and create one job per line, each with its speaker's `voice_id`. Every line then has its own audio file to place on a timeline, retime or replace. Fixing one line regenerates, and charges, only that line.

Your account runs a limited number of jobs at once (see [Rate limits and quotas](https://athanlab.com/docs#limits)), so queue the lines and submit the next as earlier ones finish. For AI agents, `athanlab_speak_script` creates one job per line, each in its speaker's voice, and saves the files on one timeline (see [AI agents (MCP)](https://athanlab.com/docs#agents)).