Promoat.Partner API

Building blocks

Text-to-speech

Turn text into speech audio with one of your voices. Useful on its own, and the same voice model video jobs use when you pass them a script.

Synthesize speech

POST/api/partner/v1/tts

Costs 10 credits per started 1,000 characters (minimum 10), charged immediately and refunded if synthesis fails. The voice_id must be one of yourvoices — someone else's id returns 404.

v4 voice model

Since 1.1.0, /tts uses the v4 voice model. The request is the same, but voices sound different from before — re-check anything you tuned by ear.

FieldTypeDescription
voice_idstring requiredFrom POST /voices — cloned or library.
textstring ≤5000 requiredWhat to say, spoken verbatim.
languagestringSpoken language — ISO code or name ("ar", "spanish").
language_codestringOlder spelling of the language hint, e.g. en. Still accepted.
voice_settingsobjectstability, similarity_boost, style (0–1), speed (0.7–1.2). Out-of-range values are clamped. Omit for tuned defaults.
Request
curl -X POST https://platform.promoat.ai/api/partner/v1/tts \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "VOICE_ID",
    "text": "Welcome back! Here is what is new this week.",
    "language": "en",
    "voice_settings": { "stability": 0.4, "similarity_boost": 0.75, "style": 0.3, "speed": 1.1 }
  }'
Response
{
  "audio_url": "https://…/tts-audio.mp3",
  "duration_sec": 4.02,
  "asset_id": "…",
  "characters": 44,
  "credits_charged": 10
}

A 600-character text costs 10 credits. If the voice no longer works (for example an expired clone), you get 409:

409 Conflict
{ "error": "VOICE_UNAVAILABLE", "error_code": "VOICE_UNAVAILABLE", "code": "voice_not_found",
  "message": "This voice is no longer available. Re-clone it or use another voice.", "voice_state": "expired" }

voice_state is expired or missing. Fix an expired clone with re-clone.

When to call this directly

  • Preview a voice before committing a video to it.
  • Audio-only products — voice notes, IVR lines, podcast inserts.
  • Reusable narration: pass the audio_url to a video, or the asset_id as tts_asset_id to fix-sound.

For a one-off video you can skip this endpoint — POST /videos with a script makes the speech inside the job.

Try it

Try itGET/api/partner/v1/voicesfree
Add your API key in the sidebar to enable this.
Try itPOST/api/partner/v1/ttscharges 10 credits
Add your API key in the sidebar to enable this.
← PreviousVoicesNext →First-frame images