Building blocks
Voices
Two ways to get a voice: clone a real one from a few seconds of audio, or pick a ready-made library voice by language — free. Either way you get a voice_id to use in TTS and videos, scoped to your account alone.
Two ways to create one
Clone (sample_urls) reproduces a specific real voice — your customer's own voice on their videos. 30 credits, and clone slots are scarce (see the cap below). Library (language) picks a high-quality ready-made voice for that language from our built-in voice library — free, instant, and perfect when any good narrator will do. You choose implicitly by which field you send.
Create a voice
| Field | Type | Description |
|---|---|---|
| name | string ≤80 required | Your label for this voice. |
| sample_urls | string[] 1–25 | Clone mode. Public https audio URLs (mp3/wav/m4a), each at least ~5 seconds of one person talking naturally; 30–60s total gives a noticeably better clone. |
| language | string | Library mode. A language name or code — "english", "british english", "arabic", "spanish", "hindi", "ja"… Every pick is verified with a tiny TTS probe before it's saved, so the id you get back is guaranteed to synthesize. |
| gender | "female" | "male" | Library mode only — which voices to search. Default female. |
curl -X POST https://platform.promoat.ai/api/partner/v1/voices \
-H "Authorization: Bearer $PROMOAT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Ava voice",
"sample_urls": [
"https://your-cdn.com/audio/ava-sample-1.mp3",
"https://your-cdn.com/audio/ava-sample-2.mp3",
"https://your-cdn.com/audio/ava-sample-3.mp3"
]
}'
# → { "voice_id": "…", "name": "Ava voice", "kind": "cloned", "credits_charged": 30 }curl -X POST https://platform.promoat.ai/api/partner/v1/voices \
-H "Authorization: Bearer $PROMOAT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Spanish narrator",
"language": "spanish",
"gender": "female"
}'
# → { "voice_id": "…", "kind": "library", "language": "spanish", "credits_charged": 0 }voice_id is an opaque id — store it as a string, don't parse it. Re-creating with the same name picks the same library voice; use a different name to get a different one.
Cloned voices are capped at 3 per account (clone slots are a finite upstream resource) — the 4th clone returns 409 VOICE_LIMIT_REACHED; delete an old one to free its slot. Library voices don't touch those slots and have their own roomier cap of 10. Treat voices as long-lived setup, not per-video throwaways.
List & delete
Your voices, newest first — each with kind (cloned | library) and, for library voices, the language you asked for.
Deletes the voice. For cloned voices this frees the slot; for library voices it just removes the entry from your account. TTS audio and videos already generated keep working either way.
Try it
The library pick is free — try it for real: