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–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.

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 your speech payment mode. The API uses the same key; send billing_source:"payg" on each request. Telegram's preference does not change 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.

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.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]
"""

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 documented by the provider 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. Tags we do not know (<b>, 5 < 10 > 3) stay plain text. 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 a provider beta documented for 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.app/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.app/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.app/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.app/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 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 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 Flow 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.app/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.app/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.app/v1/videos/VIDEO_ID -H "X-API-Key: $SONA_API_KEY"
curl https://api.sonapro.app/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).

GET /v1/me → video: allowed, models, aspect_ratios, duration_s, max_references 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 Google 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.

HTTP codes