Settings

ID formats and pricing

Build a separate first-party picker with GET /v1/voices?collection=sona_v1. Every item in the combined catalog includes collection as sona_v1 or library. Filters compose, for example ?collection=sona_v1&language=uk.

One voice, multiple templates

A template stores its own speed, volume and emotion. The same voice can therefore have Neutral, Angry and Calm presets. The bot asks for them when creating a template and lets you edit them from its template card.

POST /v1/voices/templates
{"engine":"sona","voice":"sona_xxxxxxxxxxxx","name":"Taras · angry",
 "speed":1.05,"volume":1.0,"emotion":"angry"}

PATCH /v1/voices/templates/7
{"emotion":"neutral","speed":1.0}

A parameter sent explicitly with a synthesis request overrides the template preset for that request only.

Cloning

POST /v1/voices/clone accepts multipart fields clip, name, language, plus optional speed, volume and emotion. Use 3–10 seconds of clean speech without music.

Template vs request emotion

Using tmpl:N without emotion applies the stored template emotion. Sending emotion:"angry" overrides it for this one request.

Three levels of stress control

U+0301 and a capital vowel are not independent fallbacks. The latter is merely converted to the former, so a model may ignore both.

Personal SONA dictionary: Cyrillic behavior

This is not a complete pronunciation lexicon or an automatic stress detector. It is an account's list of explicit exceptions: before synthesis SONA finds term in the transcript and literally substitutes replacement. You do not pass a dictionary ID to POST /v1/tts; saved rules are applied automatically.

Keep a dictionary term in its ordinary spelling inside the script. Do not also add U+0301 or a capital-vowel stress mark: the dictionary runs after stress normalization, so that altered spelling no longer equals the saved term. The substituted text is what synthesis, subtitles and character accounting receive.

# add or update one rule
curl -X POST https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"Тарас","replacement":"та-РАС"}'

# save inflected forms as separate rules
curl -X POST https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"term":"Тараса","replacement":"та-РА-са"}'

# list every account rule
curl https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY"

# delete a rule; percent-encode Cyrillic in the URL
curl -X DELETE https://api.sonapro.app/v1/pronunciation/%D0%A2%D0%B0%D1%80%D0%B0%D1%81 \
  -H "X-API-Key: $SONA_API_KEY"

Use it for names, brands, abbreviations and terms that are consistently mispronounced. If U+0301 solves a stress-only issue, a dictionary rule is unnecessary. Sounds-like spelling guides rather than guarantees pronunciation, so test a short take in the intended language first.

Verified rule: Тарас

For the Ukrainian Taras voice, the model said ТАрас and ignored the stress mark. The listen-tested та-РАС replacement produced the intended ТарАс.

curl -X POST https://api.sonapro.app/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"term":"Тарас","replacement":"та-РАС"}'

The rule matches a whole word, case-insensitively, for every synthesis on this API account. Never syllabify an entire script or invent IPA; listen-test each exception first.

Prompt for Claude / ChatGPT

Put this prompt before a script. The AI will inspect the whole text—not only the word “Тарас”—and return SONA-ready text.

You edit text for SONA speech synthesis.

Analyze the complete text in context and prepare it for natural machine narration.

Rules:
1. Preserve meaning, style, facts and language.
2. Keep natural punctuation and paragraphs; they control pauses.
3. Find words that a TTS engine may pronounce incorrectly. Pay special attention to:
   - given names and surnames;
   - place names;
   - brands, products and company names;
   - abbreviations;
   - foreign words and loanwords;
   - rare terms and homographs.
4. If only the stress is ambiguous, place U+0301 after the stressed vowel:
   за́мок / замо́к, му́ка / мука́.
5. If a stress mark may be insufficient and you know the correct pronunciation with
   high confidence, rewrite ONLY the problematic word phonetically:
   - split it into readable parts with hyphens;
   - write the stressed syllable in UPPERCASE;
   - preserve the grammatical ending of the word form used in the text.
6. Do not limit the analysis to “Тарас”. Detect other risky words from context, but
   do not invent a pronunciation when uncertain.
7. Format examples:
   - Тарас → та-РАС
   - OpenAI → оупен-ей-АЙ
   - ChatGPT → чат-джі-пі-ТІ
   - Renault → ре-НО
8. Do not syllabify ordinary words, insert IPA, or rewrite the entire script
   phonetically. Preserve existing <emotion value="..."/> tags unchanged.
9. Return only the narration-ready text, without explanations, lists or comments.

My text:
"""
[PASTE TEXT]
"""

Emotions in text

emotion selects one style for the whole request. Inline tags are a beta way to change it inside text.

<emotion value="excited"/> You will not believe what I learned!
<emotion value="sad"/> But then everything went wrong…
<emotion value="determined"/> We still will not give up.

Example

curl -X POST https://api.sonapro.app/v1/images \
  -H "X-API-Key: $SONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"A cinematic Crimean coast at sunrise","model":"sona-image","size":"1536x1024","quality":"high"}'

Job lifecycle

Poll every 1–2 seconds. Download audio, subtitles or images only after done.

HTTP codes