Settings

Balance and expiry — GET /v1/me

The answer covers only the account the key belongs to. The bot's Profile shows the same figures. Dates are ISO 8601 in UTC.

Nano and Veo plans are in product_billing.products.nano.plan and product_billing.products.video.plan; null without a plan.

product_billing.legacy_image_credits — previously purchased credits that can pay for Nano. They are already part of credits_remaining, so do not add them twice. payg — the pay-as-you-go wallet: balance_usd available, reserved_usd held for running jobs; the money does not expire. payg is absent when PAYG is off for the account.

Response, shortened:

{
  "credits_remaining": 400000,
  "credits_expiring": 400000,
  "credits_expires_at": "2026-10-27T11:37:49+00:00",
  "tariff": "pro",
  "tariff_expires_at": "2026-10-27T11:37:49+00:00",
  "jobs_limit": 4,
  "product_billing": {"products": {"nano": {"plan": {
    "daily_limit": 600, "used_today": 2, "remaining_today": 598,
    "resets_at": "2026-09-28T11:37:49+00:00",
    "expires_at": "2026-10-27T11:37:49+00:00",
    "active_until": "2026-11-26T11:37:49+00:00"}}}},
  "payg": {"balance_usd": "5.000000", "reserved_usd": "0.000000"}
}

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.

Pull the voice catalog

One request returns the whole catalog for a language — handy for building your own table of id + name + description.

curl "$API/v1/voices?language=en" \
  -H "X-API-Key: $KEY"

# response (trimmed)
{
  "count": 393,
  "voices": [
    {
      "id": "vc_88664ca3a4",
      "name": "Emma",
      "language": "en",
      "gender": "feminine",
      "tags": ["Conversational"],
      "description": "Approachable American female ideal for customer care and support.",
      "is_pro": false,
      "has_preview": true,
      "collection": "library"
    }
  ]
}

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–60 seconds of clean speech without music, up to 16 MB; on Sona 3.6 a longer sample, 30–60 seconds, keeps the accent better.

Voice one fragment again

A finished voice-over is made of fragments of about 700 characters. One fragment can be voiced again — as it was or with corrected text (a stress mark, say). The result is a new job with a new whole file in which that fragment is replaced; the original stays as it was. It costs twice as much as an ordinary voice-over of the fragment's characters.

GET /v1/tts/{job_id}/fragments — the number (index, from 1), text, start and end of each fragment. POST …/fragments/{n}/quote — the price, with the same fields as POST /v1/tts/quote. POST …/fragments/{n} with optional text (up to 3000 characters), max_credits / max_microusd, billing_source and client_request_id returns a job_id; from there it is an ordinary job, with subtitles when the original had them. A finished voice-over's status shows fragments — how many it has. Available while the result is stored (24 h); a dub's fragment is not voiced again — fix the original and dub it again.

Template vs request emotion

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

Pay per use (PAYG)

Top up from $5 and pay as you use speech. Sona costs $8 per million billable characters; clones and PRO voices cost $12 (×1.5). 10 concurrent tasks; funds do not expire. For example, $16 covers 2,000,000 ordinary characters.

Open /payg in Telegram to view your balance, top up and choose how the bot pays for speech. The web cabinet (api.sonapro.ai/cabinet) has its own «Оплата» (payment) switch in the speech settings; the bot's choice does not carry over to it. The API uses the same key; send billing_source:"payg" on each request. Neither the bot's choice nor the cabinet's switch changes the API default. Images and video have their own plans and the same PAYG balance: $0.015 per image, $0.02 per clip; see the Image and Video generation tabs.

GET /v1/billing/payg returns available/reserved USD and history. Create a top-up with POST /v1/billing/checkout: {"product":"payg","amount_usd":"16.25","method":"mono"} (or crypto). Payment is credited after provider verification. An empty wallet returns 402; failed/canceled speech refunds the same wallet. The TTS billing receipt reports the amount and settlement.

How it works

The text of a finished voice-over is translated and voiced in other languages. Every language is its own job and its own file. You choose how the translation is laid: «Match the video» — each sentence starts where it is said in the original, so the track can be laid over the same video; «Natural» — like an ordinary voice-over in that language (see «Modes» below). Dubbing is open to every account, uses the same X-API-Key header and is paid in credits or from the PAYG balance (pay per use).

Modes: match the video or natural

A translation is rarely as long as the original: English or Spanish often run 20–25 % shorter than Ukrainian. So choose what matters more — matching the picture or sounding natural. The field is mode in POST …/dub (dub_mode in POST /v1/tts with dub_languages); it works for ordinary voice-overs and for dialogues alike. The price is the same.

Without the field — video. Any other value — 422. GET …/dub and POST /v1/tts/dub-options return modes (id, name, description) and default_mode, the POST …/dub answer has mode, and a dub job's status has dub_mode. In «Natural» nothing is re-voiced, so only the base price is charged and the rest of the hold comes back.

Dub a finished result

Ask for the offer first, then start the languages you need. max_credits (max_amount_microusd for PAYG) is the most you agree to pay. Below the base price the request is refused with 409 and nothing is charged; between the base price and the maximum it caps how much re-voicing can be charged; without it the full maximum is held.

# 1. What is available and what it costs
curl https://api.sonapro.ai/v1/tts/JOB_ID/dub \
  -H "X-API-Key: $SONA_API_KEY"

# 2. Start: one job per language
curl -X POST https://api.sonapro.ai/v1/tts/JOB_ID/dub \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"languages":["en","ja"],"voices":{"ja":"native"},"mode":"video","max_credits":4500}'
# → {"job_id":"JOB_ID","mode":"video","billing_source":"credits","chars":4500,"chars_base":3000,"jobs":[
#     {"job_id":"DUB_ID","language":"en","status":"queued","voice":"same","chars":2250}, …]}

# 3. Every language is an ordinary speech job
curl https://api.sonapro.ai/v1/tts/DUB_ID -H "X-API-Key: $SONA_API_KEY"
curl https://api.sonapro.ai/v1/tts/DUB_ID/audio -H "X-API-Key: $SONA_API_KEY" -o dub_en.mp3

In the POST …/dub response chars is the credits held now, chars_base the base price, and each job's chars in jobs its own hold. When a language is done, the base plus the re-voiced characters is charged and the rest goes back at once; a finished dub job's status shows the credits actually charged in chars.

GET …/dub response for a 1,000-character original in a catalog voice, shortened:

{
  "job_id": "JOB_ID",
  "source_language": "uk",
  "languages": ["ar", "bg", "cs", "de", "en", "…"],
  "voices": {
    "en": {"auto": "native",
           "native": {"id": "vc_…", "name": "…", "gender": "feminine"},
           "choices": [{"id": "vc_…", "name": "…", "gender": "feminine"}, "…"],
           "pro": [{"id": "sona_…", "name": "…", "pro": true, "gender": "feminine"}]}
  },
  "cost_per_language": 1500,
  "cost_catalog_voice": 1500,
  "cost_clone_voice": 2000,
  "cost_per_language_max": 2250,
  "cost_catalog_voice_max": 2250,
  "cost_clone_voice_max": 3000,
  "multiplier_catalog_voice": 1.5,
  "multiplier_clone_voice": 2.0,
  "billing_source": "credits",
  "charge_per_language": 1500,
  "charge_per_language_max": 2250,
  "max_languages": 10,
  "modes": [{"id": "video", "name": "Під відео", "description": "…"},
            {"id": "natural", "name": "Природно", "description": "…"}],
  "default_mode": "video",
  "free_slots": 4,
  "balance": 400000,
  "payg": {
    "cost_per_language_microusd": 12000,
    "cost_catalog_voice_microusd": 12000,
    "cost_clone_voice_microusd": 16000,
    "cost_per_language_max_microusd": 18000,
    "cost_catalog_voice_max_microusd": 18000,
    "cost_clone_voice_max_microusd": 24000,
    "balance_microusd": 5000000
  }
}

cost_per_language is the base price of one language in the original voice; cost_catalog_voice and cost_clone_voice apply when a language gets a catalog voice, or a clone or Sona PRO voice. The _max fields are what is held at launch: the base plus 50 % for re-voicing. multiplier_catalog_voice and multiplier_clone_voice are the price per original character. billing_source is what auto would pay with; charge_per_language and charge_per_language_max are what would be held from credits (0 for an unlimited account). payg is present only for accounts with PAYG: the same prices in micro-USD and balance_microusd. Per language, voices holds auto — what auto will pick (same or native), native — the main native-speaker voice, choices — up to 6 native voices, and pro — Sona PRO voices of that language. A dub job's status carries dub_of, the original's job_id. A finished result that can be dubbed shows dub_available: true.

Subtitles: subtitles on POST …/dub (true or false) turns them on for every language of the request; without it a dub follows the original — the GET …/dub offer shows that as subtitles, and dubs ordered through POST /v1/tts follow that voice-over's own subtitles. A finished language with subtitles shows has_subtitles: true and serves SRT, VTT, ASS or JSON from GET /v1/tts/{job_id}/subtitles, like an ordinary voice-over. No extra charge.

Pay per use (PAYG)

Dubbing can be paid from the PAYG balance: $12 per million original characters per language in a catalog voice and $16 in a clone or Sona PRO voice (the ordinary $8 PAYG rate × 1.5 and × 2), plus re-voicing at the same rate. billing_source on POST …/dub picks how to pay: auto (the default) uses PAYG when the original was paid with PAYG and PAYG is enabled for the account, credits otherwise; credits or payg choose explicitly. The price cap is max_amount_microusd, with the same rules as max_credits.

curl -X POST https://api.sonapro.ai/v1/tts/JOB_ID/dub \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"languages":["en","de"],"billing_source":"payg","max_amount_microusd":36000}'
# → {"job_id":"JOB_ID","billing_source":"payg","amount_microusd":36000,"amount_usd":"0.036000",
#    "base_microusd":24000,"base_usd":"0.024000",
#    "jobs":[{"job_id":"DUB_ID","language":"en",…,"amount_microusd":18000}, …]}

amount_microusd and amount_usd are held now, base_microusd and base_usd are the base price, and amount_microusd on each job in jobs is its own hold. The final charge is in the billing receipt of the finished dub job's status (charged_usd). With PAYG, free_slots in the offer counts PAYG slots.

Dub while creating

Add dub_languages and, if needed, dub_voices and dub_mode (video or natural, see «Modes») to POST /v1/tts. The dub price is added to the voice-over price and held with it: POST /v1/tts/quote with the same body shows the dubs' base price in dub_credits, the hold including re-voicing in dub_credits_max, and charge_credits already includes the hold. max_credits covers the whole request: below the voice-over price plus the dubs' base price it is 409; above that it caps the re-voicing charge.

curl -X POST https://api.sonapro.ai/v1/tts \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, world!","voice":"vc_xxxxxxxxxx","language":"en","dub_languages":["de","uk"],"dub_voices":{"de":"same"},"dub_mode":"natural"}'
# → {"job_id":"JOB_ID","status":"queued","chars":13,"language":"en",
#    "dub_credits":40,"dub_credits_max":60,"dub_languages":["de","uk"],"dub_mode":"natural"}

# dub progress lives in the original's status
curl https://api.sonapro.ai/v1/tts/JOB_ID -H "X-API-Key: $SONA_API_KEY"
# → … "dub_jobs":[{"language":"de","state":"started","job_id":"DUB_ID"},
#                 {"language":"uk","state":"waiting"}]

Once the original is done, the service creates the dub jobs itself and each gets its own job_id. If the original fails or is canceled, everything held for the dubs is given back and the state becomes refunded.

With billing_source:"payg" the job also pays for its dub_languages from the PAYG balance: the dubs are held from the wallet together with the job and given back if the job fails or is canceled. The price cap for the whole request is then max_microusd. The quote shows dub_amount_microusd and dub_amount_max_microusd (in dollars, dub_amount_usd and dub_amount_max_usd), and amount_microusd includes the dub hold.

Voice per language

voices (or dub_voices on POST /v1/tts) maps a language to a voice. A language without an entry gets auto.

To offer the choice before a voice-over exists, send the voice, language and model to POST /v1/tts/dub-options. It returns languages, voices in the same shape and max_languages. There is no price here because it depends on the text: POST /v1/tts/quote gives it.

curl -X POST https://api.sonapro.ai/v1/tts/dub-options \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice":"vc_xxxxxxxxxx","language":"en","model":"sona-3.6"}'

Price and limits

• Price — per character of the original, per language: 1.5 credits in a catalog voice (what a clone or Sona PRO voice-over costs), 2 credits in a clone or a Sona PRO voice. With PAYG, $12 and $16 per million original characters. Translation is included.
• Re-voicing — charged as it happens: fragments that had to be voiced again to fit the time are charged on top at the same rate (the characters of each extra take × the multiplier). At launch the base price plus 50 % of it is held (the *_max fields); when the dub is done, the base plus the re-voiced characters is charged and the rest of the hold goes back at once. Never more than the hold is charged — re-voicing beyond it is free. If a language's dub fails, everything held for it comes back.
• Example — a 1,000-character original, one language: in a catalog voice 1,500 credits (up to 2,250 with re-voicing) or $0.012 (up to $0.018); in a clone or Sona PRO voice 2,000 (up to 3,000) or $0.016 (up to $0.024).
• Languages depend on the original's model: the 42 languages of sona-3.5, and sona-3.6 adds Odia (or) and Urdu (ur). The original's own language is not in the list.
• Up to 10 languages per request. Every language is its own job and takes one of the tariff's concurrent job slots (jobs_limit), or one of the 10 PAYG slots with PAYG. The set is admitted whole or not at all: without a free slot for every language the answer is 429. free_slots shows how many are free now.
• 24 hours — how long a result is stored and can be dubbed; after that 410. A dub cannot be dubbed again — dub the original.

Errors

Nothing is charged on a refusal.

Dub your own recording

Your own audio recording or voice message can be dubbed into other languages too — in the bot or through the API. A step-by-step guide, the price and the limits are on the «Audio dubbing» tab.

How it works

• What to send — an audio file (mp3, m4a, ogg, wav, flac…) or a voice message: one voice in the recording, up to 2 h. Videos are not accepted — sound only.
• What the service does — recognises the language, the text and the time of every word, free of charge, and tells the speaker's gender. You can correct the text before dubbing: names, terms, misheard words.
• What you get — an mp3 in every chosen language. «🎬 Match the video» keeps every phrase where it was and the original's length: the track can go over the same video. «🎙 Natural» sounds like an ordinary voice-over in that language. Background music and noise are not carried over: only the new voice is heard in the result.

In the bot, step by step

1. Open @sonapro_bot and send an audio file or a voice message — up to 20 MB (Telegram gives bots nothing larger).
2. The bot shows the recording's card with its length and price — press «🌐 Dub this audio».
3. Wait for the recognition — about a minute for every 10 minutes of recording. The bot sends the recognised text.
4. If needed — «✏️ Correct the text»: copy the text, fix it and send it as the next message (up to 3,500 characters in the bot; a longer text is corrected through the API).
5. «🌐 Choose languages» — tick the languages and press «Next › voices». For every language — «Auto» (a native speaker of the speaker's gender), another native voice (🔊 — listen), a Sona PRO voice 💎 or your own saved voice ⭐.
6. Choose «🎬 Match the video» or «🎙 Natural», «Subtitles» if needed, and press «▶️ Start» — the button already shows the price. The finished file in every language arrives in the chat.

Via the API, price and limits

• Through the API — send the file, wait for status: done, correct the text if needed and start the dub with the usual POST …/dub.

# 1. Send the recording (recognition is free)
curl -X POST https://api.sonapro.ai/v1/audio/dub-source \
  -H "X-API-Key: $SONA_API_KEY" \
  -F file=@talk.mp3 -F language=en
# → 202 {"job_id":"JOB_ID","status":"queued","duration":512.4}

# 2. Wait for "status": "done"
curl https://api.sonapro.ai/v1/tts/JOB_ID -H "X-API-Key: $SONA_API_KEY"

# 3. The text with its sentences' times — and a correction if needed
curl https://api.sonapro.ai/v1/tts/JOB_ID/transcript -H "X-API-Key: $SONA_API_KEY"
curl -X PUT https://api.sonapro.ai/v1/tts/JOB_ID/transcript \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello everyone. Today we talk about the weather."}'

# 4. The dub — as for any voice-over
curl -X POST https://api.sonapro.ai/v1/tts/JOB_ID/dub \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"languages":["uk","de"],"mode":"video"}'

• Price — recognising and correcting the text are free. A recording's dub costs per character of the recognised text, per language, twice a voice-over: a catalog voice 2 credits, a clone or Sona PRO voice 3. With PAYG, $16 and $24 per million characters. Re-voicing is charged as it happens at the same rate; the base plus 50 % is held at launch, as for any dub.
• Example — a recording with 1 000 characters of text, one language: a catalog voice 2 000 credits (up to 3 000) or $0.016 (up to $0.024); a clone or Sona PRO voice 3 000 (up to 4 500) or $0.024 (up to $0.036).
• Limits — files up to 95 MB, recordings up to 2 h, up to 6 h of recordings a day per account, one recording recognised at a time. «Match the video» gives a file as long as the recording. The file itself is deleted once it is recognised; the text and the mp3 are kept for 24 hours.

How it works

A dialogue is roles and lines in the order they are spoken. Every line is voiced in its role's voice, and all of them are put together into one file. We trim the silence at the start and end of every line, so a pause between lines sounds exactly as long as you set it. The roles' loudness is levelled: a quiet role is not drowned out by a loud one, and a whisper stays a whisper. Lines can overlap, sound at the same time or interrupt the previous one — an interrupted line fades out where it was cut, and an overlap does not overload the sound. Subtitles name the speaker, and every role can be downloaded as its own track.

Dialogues are enabled per account: GET /v1/me returns "dialogue": true when they can be used. Until then, dialogue requests answer 403.

In the bot

1. Send a script as text or as a .txt / .docx file — every line on a new row: Name: text. The bot recognises the dialogue and opens the roles screen «🎭 Dialogue: N roles · M lines».
2. The roles screen has a button per role «Name — Voice». The first role gets your current voice, the others get suggested voices so the roles do not sound alike. Tap a role to choose its voice: saved voices, clones, recent voices, search by name, an ID or the catalog.
3. Next › appears once every role has a voice: the card shows the roles, voices, characters and the price, and Voice it starts the dialogue. Voice it in one voice goes back to an ordinary voice-over of the same text, How to write a dialogue shows the format and the commands.

• 🎭 Split into roles — a button under an ordinary text without names: the story is split into the narrator and the characters, and the words of every line are taken from your text verbatim.
• 🎭 Dialogue templates — saved casts of heroes with their voices. A template whose heroes match the script's names is applied by itself: a role is marked «from the template» or «as last time»; 🎭 Template… picks another template or none.
• When a script has a mistake, the bot shows the reason with its row number («Рядок N: …») and never reads the names or the commands aloud.

Under a finished dialogue:

Script format

A script is written the same way in the bot and for POST /v1/tts/dialogue/parse.

• A line starts on a new row: Name: text or [Name]: text. A row without a name continues the previous line.
• A remark in parentheses after the name is not voiced: Andriy (whispering): … is the role «Andriy».
• Text before the first name is read by the role «Narrator».
• Commands go in curly braces anywhere in a line; they are not voiced and not charged. A pause belongs to the end of its line, the others to its start, counted from the previous line. Numbers are seconds (a decimal comma works too); with ms or мс — milliseconds.

Author: A forest clearing. Evening mist creeps over the lake.
Vasyl: Andriy, do you hear that? Someone is singing over the water. {pause: 1}
Andriy (whispering): I hear it. They say it is Mavka, and she lures fishermen into the deep.
Mavka: {interrupt after words: "lures fishermen"} Not true!
I just love to sing when the moon rises.
Vasyl: {overlap: 0.4} Oh... She heard us.
Author: The boys looked at each other and silently headed home.

Four roles, seven rows — six lines: a second of silence after Vasyl's question, Mavka interrupts Andriy on the words «lures fishermen», the row without a name continues her line, and Vasyl starts before she has finished.

API: voice a dialogue

The same POST /v1/tts, but with roles (speakers) and lines (segments) instead of text and voice. The other fields — model, language, format, subtitles, billing_source, max_credits, name — work as for an ordinary voice-over; the request's speed, volume and emotion apply to roles without their own. From there it is an ordinary job: status, /audio, subtitles.

curl -X POST https://api.sonapro.ai/v1/tts \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"sona-3.6","subtitles":true,"dialogue_pause_seconds":0.35,
  "speakers":[
    {"id":"author","name":"Author","voice":"vc_xxxxxxxxxx"},
    {"id":"vasyl","name":"Vasyl","voice":"tmpl:3","speed":1.05},
    {"id":"mavka","name":"Mavka","voice":"sona_xxxxxxxxxxxx","volume":0.9,"emotion":"calm"}],
  "segments":[
    {"speaker_id":"author","text":"Mist creeps over the lake.","pause_after_seconds":1},
    {"speaker_id":"vasyl","text":"Listen. Someone is singing over the water. It must be Mavka."},
    {"speaker_id":"mavka","text":"Yes, it is me!","start_mode":"after_words",
     "start_after_words":"over the water","interrupt_previous":true},
    {"speaker_id":"vasyl","text":"She heard us.","start_mode":"overlap","start_offset_seconds":0.3}]}'
# → {"job_id":"JOB_ID","status":"queued","chars":226,"language":"en",
#    "dialogue":{"speakers":3,"segments":4}}

# with the template dlg:3: the heroes' voices come from it by name, no speakers needed
curl -X POST https://api.sonapro.ai/v1/tts \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"dlg:3","segments":[{"speaker_id":"Vasyl","text":"Do you hear that?"},{"speaker_id":"Mavka","text":"I do."}]}'

Precedence: the role's field → the request's field → the preset of a saved voice tmpl:N. Stress marks, pronunciation rules and inline tags work in every line exactly as in an ordinary voice-over.

A start rule counts from the previous line and replaces the pause before it. The first line is always after, and a role never overlaps itself. The POST /v1/tts response adds dialogue — how many roles and lines; the quote adds dialogue with the roles (id, name, voice, chars), the number of lines and credit_multiplier.

API: the result

A dialogue's status carries dialogue — the roles (id, name) and the number of lines. A finished one adds dialogue_url, stems_url and fragments — the number of lines that can be voiced again.

# 1. Status
curl https://api.sonapro.ai/v1/tts/JOB_ID -H "X-API-Key: $SONA_API_KEY"
# → … "dialogue":{"speakers":[{"id":"author","name":"Author"}, …],"segments":4},
#     "dialogue_url":"/v1/tts/JOB_ID/dialogue","stems_url":"/v1/tts/JOB_ID/stems","fragments":4

# 2. Who says what, and when
curl https://api.sonapro.ai/v1/tts/JOB_ID/dialogue -H "X-API-Key: $SONA_API_KEY"

# 3. Role tracks: the ZIP or a public link to it
curl https://api.sonapro.ai/v1/tts/JOB_ID/stems -H "X-API-Key: $SONA_API_KEY" -o stems.zip
curl https://api.sonapro.ai/v1/tts/JOB_ID/stems/link -H "X-API-Key: $SONA_API_KEY"
# → {"url":"https://api.sonapro.ai/ds/…","expires":1791460800}

# 4. Voice the third line again, with corrected text
curl -X POST https://api.sonapro.ai/v1/tts/JOB_ID/fragments/3 \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Yes, it is me! And I hear everything."}'

GET …/dialogue response, shortened:

{
  "job_id": "JOB_ID",
  "duration": 7.41,
  "speakers": [{"id": "author", "name": "Author", "voice": "vc_xxxxxxxxxx"}, "…"],
  "segments": [
    {"index": 2, "speaker_id": "vasyl", "speaker_name": "Vasyl",
     "text": "Listen. Someone is singing over the water. It must be Mavka.",
     "start": 3.12, "end": 5.06, "interrupted": true},
    {"index": 3, "speaker_id": "mavka", "speaker_name": "Mavka",
     "text": "Yes, it is me!", "start": 5.01, "end": 6.2, "interrupted": false},
    "…"
  ]
}

• Role tracks — GET …/stems returns a ZIP: a separate track per role, as long as the whole dialogue, plus timeline.json. GET …/stems/link is a public link that needs no key (url and expires), handy for big files.
• Subtitles (subtitles:true) name the speaker: SRT — «Name: …», simultaneous speech — one block «- A: … / - B: …», VTT — <v Name>, ASS — the Name field.
• Lines as fragments — GET /v1/tts/{job_id}/fragments returns the lines with speaker_id and speaker_name. POST …/fragments/{n} with an optional corrected text creates a new job — the whole dialogue with that line voiced again; the original does not change. POST …/fragments/{n}/quote shows the price first.

API: parsing a script

POST /v1/tts/dialogue/parse turns a text into roles and lines in the POST /v1/tts format and suggests a voice for every role. Free: up to 30 requests a minute. An ordinary text without names answers {"is_dialogue": false}; with "auto": true it is split into the narrator and the characters — up to 20,000 characters, up to 6 requests a minute; the words of every line are taken from the original verbatim.

# a script; voice is your current voice, the first role gets it
curl -X POST https://api.sonapro.ai/v1/tts/dialogue/parse \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Vasyl: Do you hear that? {pause: 1}\nMavka: I do!","voice":"vc_xxxxxxxxxx"}'

# ordinary prose → the narrator and the characters, no template
curl -X POST https://api.sonapro.ai/v1/tts/dialogue/parse \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Vasyl looked round and called out: “Who is there?” From the mist, Mavka answered quietly: “Me.”","auto":true,"template":"none"}'

The answer to the first request, shortened:

{
  "is_dialogue": true,
  "auto": false,
  "speakers": [
    {"id": "Vasyl", "name": "Vasyl", "lines": 1, "chars": 17,
     "suggested_voice": {"id": "vc_xxxxxxxxxx", "name": "…", "gender": "masculine"},
     "voice_source": "current", "template_voice": null, "remembered_voice": null},
    {"id": "Mavka", "name": "Mavka", "lines": 1, "chars": 5,
     "suggested_voice": {"id": "vc_…", "name": "…", "gender": "feminine"},
     "voice_source": "suggested", "template_voice": null, "remembered_voice": null}
  ],
  "segments": [
    {"speaker_id": "Vasyl", "text": "Do you hear that?", "pause_after": 1.0, "start_mode": "after", "…": "…"},
    {"speaker_id": "Mavka", "text": "I do!", "pause_after": null, "start_mode": "after", "…": "…"}
  ],
  "characters": 22,
  "credit_multiplier": 2.0,
  "language": "en",
  "template": null
}

• Request fields: text (required), auto, voice — your current voice (vc_…, sona_…, tmpl:N; an unknown one is simply ignored), template, language, model.
• suggested_voice — the voice a role starts with, in this order: the template's hero → the voice this hero had in your last dialogue → the request's voice (the first role only) → a catalog voice no other role has. voice_source says where it came from: template, memory, current, suggested or null. A template or memory voice comes with its speed and emotion; those voices themselves are in template_voice and remembered_voice.
• template: "dlg:N" — that template, "none" — no template; without the field, your template whose heroes cover the most roles of the script (at least two, or all of them) is applied. The response then has template — id, name, matched and missing (roles the template gave no voice), otherwise null.
• segments can go straight into POST /v1/tts once every role has a voice. Their fields use the short names — pause_after, start_offset, interrupt, interrupt_overlap; POST /v1/tts accepts both spellings.
• A script that could not be voiced (a broken command, too many roles or lines, too long) gets 422 with the reason «Рядок N: …» (line N) right here.

Dialogue templates

A template is your saved cast: the heroes as they are named in your scripts and the voice of each (vc_…, sona_… or tmpl:N), optionally with speed, volume, emotion and language. Its reference is dlg:N: a number within the account, never reused after a delete. Up to 50 templates, 1–20 heroes in each, a name of up to 60 characters.

# create from a list of heroes: one hero per line
curl -X POST https://api.sonapro.ai/v1/dialogue/templates \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Forest Song","text":"Author vc_xxxxxxxxxx\nVasyl tmpl:3 1.1\nAndriy: vc_yyyyyyyyyy calm\nMavka = sona_xxxxxxxxxxxx 0.9 sad"}'
# → 201 {"id":"dlg:3","num":3,"name":"Forest Song","roles":[
#     {"name":"Author","voice":"vc_xxxxxxxxxx","voice_name":"…","speed":null,…}, …],…}

# or from the heroes of a finished dialogue
curl -X POST https://api.sonapro.ai/v1/dialogue/templates/from-job/JOB_ID \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Forest Song"}'

# rename
curl -X PATCH https://api.sonapro.ai/v1/dialogue/templates/dlg:3 \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mavka and the fishermen"}'

• Hero lines — Name ID [speed] [emotion]: a space, :, -, — or = between the name and the voice; speed is 0.6–1.5 or 60–150 %. A line that cannot be read gets 422 «Рядок N: …» (line N).
• Matching by name ignores case and extra spaces, «ё» = «е», and every apostrophe is the same. POST /v1/tts with "template": "dlg:3" gives every role the voice of the hero with the same name, while subtitles keep the script's spelling; speakers with the same id override a hero or add a new one. A role found in neither gets 422 naming it. Parsing a script applies the matching template by itself.
• Remembered heroes — even without a template the service remembers the last voice of every hero by name (up to 500 per account): every accepted dialogue records it, and the next parse suggests it again (voice_source: "memory").
• When a saved voice tmpl:N is deleted, the heroes that used it are left without a voice ("voice": null): the parse lists them in missing, and they need a new one.

Dubbing a dialogue

A finished dialogue is dubbed like an ordinary voice-over — GET and POST /v1/tts/{job_id}/dub — but the voice is set for every role. Every line is translated with the previous lines and who says them in mind, voiced in its role's voice and placed where it sounded in the original; an interrupted line is cut at the same moment. Every language's file is as long as the original and is a dialogue too: lines, role tracks, subtitles, voicing a line again. A dub cannot be dubbed again.

# 1. Languages, role voices and the price
curl https://api.sonapro.ai/v1/tts/JOB_ID/dub -H "X-API-Key: $SONA_API_KEY"
# → … "dialogue":true,"roles":[{"id":"vasyl","name":"Vasyl","voice":"tmpl:3"}, …],
#     "role_voices":{"uk":{"vasyl":{"auto":{"id":"tmpl:3","name":"…"},"choices":[…]}, …}, …}

# 2. Start: a voice is set only for Mavka in Ukrainian, the rest are auto
curl -X POST https://api.sonapro.ai/v1/tts/JOB_ID/dub \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"languages":["uk","pl"],"role_voices":{"uk":{"mavka":"vc_xxxxxxxxxx","author":"native"}}}'

• role_voices — «language → role → voice»: auto, same, native, vc_…, sona_… or tmpl:N; a role without an entry gets auto. voices does not apply to a dialogue — 422.
• auto: a clone and a Sona PRO voice stay themselves, and so does a voice that speaks the language; otherwise the role gets a native-speaker voice of the same gender, and two roles never get one voice.
• The offer GET …/dub of a dialogue adds dialogue: true, roles and role_voices — for every language and role, what auto picks and up to 6 native voices in choices.
• mode — as on the Dubbing tab: video (default) — every line starts where it did in the original (up to half a second earlier to even out the pauses), the file is as long, for the same video; natural — the lines follow one another with natural pauses (overlaps and interruptions are kept), the length may differ.
• The price does not depend on the voices (below, «Price and limits»); languages, up to 10 languages per request, slots, holds and max_credits work as in the «Dubbing» tab. A dub cannot be ordered while the dialogue is created (dub_languages) — only from the finished result.

Price and limits

• A dialogue — 2 credits per character of the lines, whatever voices speak them; names, commands, settings and pauses are free. With PAYG (billing_source:"payg") — $16 per million characters of the lines. For example, 1,000 characters of lines cost 2,000 credits or $0.016.
• One line again — ×2 its characters: 2 credits per character, $16 per million with PAYG.
• Dubbing a dialogue — 2 credits per character of the original's lines per language, $16 per million per language with PAYG. Lines that had to be voiced again to fit the time are charged on top at the same rate: the base plus up to 50 % is held at launch, and what is not used goes back at once.
• Roles — from 2 to 20; an id and a name of up to 80 characters. Lines — up to 2,000, up to 200,000 characters together.
• Pauses — up to 30 s, offsets (start_offset_seconds and the numbers in commands) — up to 60 s. The whole dialogue including pauses — up to 5 hours; a longer one gets 422 before anything is charged.
• One job — a dialogue takes one concurrent job slot, however many roles it has.
• 24 hours — how long the file, the role tracks and the lines are kept for voicing again and dubbing; after that 410. A template can still be saved from a finished dialogue later.

Errors

Nothing is charged on a refusal.

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.

Case-sensitive exceptions: the default is case_sensitive: false, preserving existing rules. With case_sensitive: true, US does not match us, and LaTeX does not match latex. Lowercase keys also accept initial capitalization: cat → cat / Cat, but not CAT. Supported by Sona 3.5 and 3.6. Example for POST /v1/pronunciation: {"term":"US","replacement":"United States","case_sensitive":true}. Overlapping spellings return 422; edit or delete the existing rule first. Use the exact term returned by the list endpoint to update or delete a particular variant.

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.ai/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.ai/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.ai/v1/pronunciation \
  -H "X-API-Key: $SONA_API_KEY"

# delete a rule; percent-encode Cyrillic in the URL
curl -X DELETE https://api.sonapro.ai/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.ai/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]
"""

Tags in text

The speed, volume and emotion fields set one style for the whole request. The same three controls can be placed inside the text instead — plus a pause, letter-by-letter spelling and a laugh. Tags work on sona-3.5 and sona-3.6; [laughter] is made for sona-3.6, the default model; do not rely on it with "model":"sona-3.5".

<volume ratio="0.6"/><speed ratio="0.8"/>This part is softer and slower.<break time="1s"/>
<volume ratio="1"/><speed ratio="1"/>And this part is back to normal.
<emotion value="excited"/> You will not believe what I learned! [laughter]
<emotion value="sad"/> But then everything went wrong…

Uppercase, a comma decimal and a missing slash are repaired for you (<SPEED RATIO="0,8"> → <speed ratio="0.8"/>); broken markup returns 422 with an explanation instead of silently doing nothing. Text in angle brackets that is not a tag is voiced as a quotation: <<Stop!>> becomes «Stop!», 5 < 10 > 3 becomes 5 ‹ 10 › 3 (otherwise the engine silently skipped everything in brackets). HTML tags such as <b> are not spoken. Long text is split into parts and any active speed/volume/emotion is re-opened in each of them, so the effect does not stop mid-way.

emotion is in beta and works best in English — on other languages the difference may not be audible; speed and volume are guidance, not exact multipliers. <break> splits the generation at that point, so several in a row sound unnatural. Tag characters count towards chars but never reach subtitles: those contain only what is actually spoken.

Example

# Nano plan or previously purchased credits: billing_source may be omitted (auto)
curl -X POST https://api.sonapro.ai/v1/images \
  -H "X-API-Key: $SONA_API_KEY" -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"prompt":"A cinematic Crimean coast at sunrise","model":"nano-banana-2","size":"1024x1024"}'

# PAYG balance ($0.015): billing_source:"payg" is required; without it auto answers 402
curl -X POST https://api.sonapro.ai/v1/images \
  -H "X-API-Key: $SONA_API_KEY" -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"prompt":"A cinematic Crimean coast at sunrise","model":"nano-banana-2","size":"1024x1024","billing_source":"payg","max_amount_microusd":15000}'

# edit with repeated references (repeat -F images=@... up to the model limit; for PAYG add -F billing_source=payg)
curl -X POST https://api.sonapro.ai/v1/images/edit \
  -H "X-API-Key: $SONA_API_KEY" -H "Prefer: respond-async" \
  -F 'prompt=Preserve the people and combine the composition' \
  -F 'model=nano-banana-pro' \
  -F 'images=@reference-1.jpg' -F 'images=@reference-2.png'

# GPT Image 2.5 through PAYG ($0.03); with previously purchased credits billing_source may be omitted
curl -X POST https://api.sonapro.ai/v1/images \
  -H "X-API-Key: $SONA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -d '{"prompt":"Cinematic portrait in soft blue light","model":"gpt-image-2.5","size":"2048x1152","billing_source":"payg","max_amount_microusd":30000}'

# poll GET /v1/images/IMAGE_ID until status=done, then download download_url

Sizes (size)

The default is 1024x1024; any other value returns 422. Nano Banana returns a file of exactly the requested size. For GPT Image 2.5, size only picks the aspect ratio: the file arrives at the model's own resolution (~1.5 MP), never upscaled. POST /v1/images/edit takes the same size.

Models

Do not hardcode the list: GET /v1/me returns in image.model_options only the models this account may use, with their price (billing_options). model is required; there is no default.

How an image is paid for

• Nano plan, 30 days: Start $27 — 600 images a day, 5 at once; Pro $45 — 1,200 a day, 7 at once; Ultra $90 — 3,500 a day, 14 at once. Nano Banana 2.1 and Pro count towards one daily allowance; unused allowance does not roll over.
• PAYG — $0.015 per generation from the money balance, only when asked for explicitly: send billing_source:"payg" (a billing_source=payg field in multipart). Add max_amount_microusd to cap the price.
• Previously purchased credits — 1,000 per Nano Banana 2.1 or Pro image.
• GPT Image 2.5 — PAYG, $0.03 per image (billing_source:"payg"), or credits purchased before the switch to plans, at the purchase tariff (Start 2,500 · Pro 3,333 · Business 6,000 · Ultra 9,000); auto spends those first. Plans and credits bought after the switch do not pay for it: without old credits auto returns 402. size only picks the aspect ratio — the file arrives at the model's own resolution (~1.5 MP, e.g. 1672×941 for 16:9). The legacy ids gpt-image-2 and sona-image are accepted.

The default billing_source:"auto" uses the plan, and without one the previously purchased credits. It never spends PAYG money: with neither a plan nor credits the answer is 402. A failed generation refunds automatically. Images ship as the 1080 original exactly as the model generates them, no upscale. quality=2k was retired and returns 422.

Parameters

Always asynchronous: a clip takes one to several minutes to render, so POST answers 202 at once and you fetch the file from the status's download_url. A clip from text is 8 s. The render service picks the length of a clip from images: currently 6 s from a first frame (1–2 images) and 8 s from three references. So its duration_s is null until it is done. A finished clip's duration_s is the real length of the file.

Example

# 1. A clip from text
curl -X POST https://api.sonapro.ai/v1/videos \
  -H "X-API-Key: $SONA_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt":"A paper boat drifting across a calm pond at sunrise","aspect_ratio":"16:9"}'
# → 202 {"video_id":"...","status":"queued","model":"veo-3.1","status_url":"/v1/videos/..."}

# 2. A clip that starts from your picture
curl -X POST https://api.sonapro.ai/v1/videos \
  -H "X-API-Key: $SONA_API_KEY" \
  -F 'prompt=The camera slowly pushes in, wind moves the leaves' \
  -F 'aspect_ratio=9:16' \
  -F 'images=@first-frame.jpg'

# 3. Poll until done, then download the MP4
curl https://api.sonapro.ai/v1/videos/VIDEO_ID -H "X-API-Key: $SONA_API_KEY"
curl https://api.sonapro.ai/v1/videos/VIDEO_ID/file -H "X-API-Key: $SONA_API_KEY" -o clip.mp4

Access and billing

• Video is available to every account. If a manager has switched Veo off for an account, POST /v1/videos returns 403 and GET /v1/me shows video.allowed:false.
• Veo plan, 30 days, unlimited clips: Start $45 — 2 clips at once; Pro $95 — 6; Ultra $140 — 10. A manager enables the plan.
• PAYG — $0.02 per clip from the money balance, only when asked for explicitly: send billing_source:"payg". To lock the price, add max_amount_microusd (20000). A 1080p clip (resolution:"1080p") is $0.03 (30000), PAYG only.

GET /v1/me → video: allowed, models, aspect_ratios, duration_s, max_references, resolutions (available now) and billing_options, this account's price. If a render fails, the status says error with the reason in detail, and the payment is returned automatically. error_code is content_refused when the model refused the request itself under its policies (refusal_reason: real_person, intellectual_property, minor, audio, sexual, violence, unsafe, prohibited, prompt or policy; retryable:false — change the prompt or the image), otherwise generation_failed (retryable:true). The same request (prompt + images) refused twice (three times when the reason is the audio) is not accepted for 24 h: POST answers 422 at once and nothing is charged.

Job lifecycle

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

Job history — GET /v1/activity

The latest jobs of the account that owns the key: voice-overs, images and video together. Unfinished ones (queued, processing) come first, then newest first. It shows which requests have finished and which have not, even if a job_id was lost.

Response, shortened:

{
  "jobs": [
    {"id": "3f9c2a…", "kind": "voice", "name": "chapter_2", "status": "processing",
     "created_at": "2026-10-09T10:27:03+00:00", "finished_at": null},
    {"id": "8a41d0…", "kind": "voice", "name": "chapter_1", "status": "done",
     "created_at": "2026-10-09T10:12:40+00:00", "finished_at": "2026-10-09T10:13:05+00:00"}
  ],
  "payments": []
}

id is the voice-over's job_id, the image's image_id or the clip's video_id: fetch status and files with the usual requests (/v1/tts/{job_id}/audio, /v1/images/{image_id}/file, /v1/videos/{video_id}/file). Files are kept for a limited time; the history entry stays. An unknown kind or status value returns 422. payments lists the account's latest payments.

HTTP codes