Text to speech

Primary agent path

Use the Universal Skill with the MCP tool beatra.speech.synthesize. The tool is billable and returns an asynchronous task.

Pick a voice first: beatra.voices.list returns preset and cloned voices with voice_id and preview URLs.
If a model, language, format, or price matters, call beatra.models.list with capability: "text_to_speech". Otherwise use model: "auto" or omit model.
Create one opaque client_request_id and submit the final arguments once.
Poll the returned task with beatra.tasks.get until it is terminal.

AI guide

MCP integration guide for AI

For custom API integrations, copy this guide into Claude, Codex, or another coding assistant.

Markdown

Tool arguments

{
  "voice": "voice_01JX...",
  "input": "Welcome to Beatra — make your first call in three minutes.",
  "language": "en-US",
  "format": "mp3",
  "speed": 1.0,
  "client_request_id": "tts-opaque-1"
}

voice accepts any voice_id from voices; preset and cloned voices behave the same. Streaming and real-time conversation are not part of this capability.

Common controls are input (required, ≤50,000 characters), voice (required), language, format (default mp3; also wav/flac/opus/pcm), speed (0.5–2.0), volume (>0–10), pitch (−1–1, normalized: 0 keeps the voice's original pitch, −1 the lowest, 1 the highest the selected model supports; use decimals like 0.25 for subtle tuning), emotion, and sample_rate. Use each only according to the selected model's metadata.

beatra.models.list is the current source for selectable models, supported languages, formats, sample rates, and customer prices. Do not copy a model catalog or price table into an agent prompt.

Speech is prepaid from the request estimate and billed linearly by weighted characters (quoted per 1,000): each Han ideograph counts as 2 and every other character counts as 1.

Controlling polyphonic-character pronunciation (MiniMax models)

For rare or polyphonic Chinese characters, pin the exact reading instead of rewriting the text with a homophone:

{
  "model_options": {
    "minimax": {
      "pronunciation_dict": {
        "tone": ["湛/(zhan4)", "晞/(xi1)", "厌/(yan1)"]
      }
    }
  }
}

The format is character/(pinyin+tone digit), with tone digits 1–4 for the four tones and 5 for the neutral tone. MiniMax models only; other models ignore this field.

Languages

language is an optional provider-neutral BCP-47 tag such as zh-CN, yue-HK, or en-US. Beatra matches the primary language subtag against the selected model; omit the field to let the voice or model detect the language. An unsupported language is rejected instead of being silently replaced.

Current speech models cover the 40 languages below; constraints.supported_languages from beatra.models.list is the live, model-specific source.

Code	Language	Code	Language
`zh`	Chinese	`tr`	Turkish
`yue`	Cantonese	`nl`	Dutch
`en`	English	`uk`	Ukrainian
`es`	Spanish	`th`	Thai
`fr`	French	`pl`	Polish
`ru`	Russian	`ro`	Romanian
`de`	German	`el`	Greek
`pt`	Portuguese	`cs`	Czech
`ar`	Arabic	`fi`	Finnish
`it`	Italian	`hi`	Hindi
`ja`	Japanese	`bg`	Bulgarian
`ko`	Korean	`da`	Danish
`id`	Indonesian	`he`	Hebrew
`vi`	Vietnamese	`ms`	Malay
`fa`	Persian	`sk`	Slovak
`sv`	Swedish	`hr`	Croatian
`fil`	Filipino	`hu`	Hungarian
`no`	Norwegian	`sl`	Slovenian
`ca`	Catalan	`nn`	Nynorsk
`ta`	Tamil	`af`	Afrikaans

Task status and recovery

queued and running are not failures. Keep polling the same task_id; never submit a replacement because work is still running. On a lost create response, retry the identical arguments with the same client_request_id. If any input changes, use a new ID. Failed tasks automatically refund the charged credits. Return the audio artifact, resolved model, and charged credits only from the terminal task response; artifact URLs are CDN addresses — copy them to your own storage promptly.

REST API

Direct protocol integrations may use POST /v1/audio/speech and the shared task endpoints. Follow the generated API operation. Skill + MCP is the recommended integration; use REST for custom, non-agent applications.