Building blocks

Voices

Two ways to get a voice: clone a real one from audio samples, or pick a ready-made studio voice — 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 account's first clone is free — once per account, ever (deleting and re-creating does not make it free again); later clones cost 30 credits. Library picks one of our studio voices — free and instant. You choose by which fields you send.

Create a voice

POST/api/partner/v1/voices

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) of one person talking. Aim for 30–60 s of speech in total; under 25 s of usable speech still works but returns a `LOW_SAMPLE_AUDIO` warning. Samples that fail the URL check are skipped; only the first 25 URLs are used. Don't send `language` with `sample_urls` (that is a 400); use `preview_language`.
preview_language	string	Clone mode — language of the `preview_url` clip.
studio_voice	string	Library mode. One of the names from `GET /voices/presets`. An unknown name → `400 INVALID_STUDIO_VOICE`.
language	string	Library mode — the language you will speak (name or code).
gender	"female" \| "male"	Library mode — used to pick a studio voice when you don't name one.

Clone a real voice — free the first time, 30 credits after

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"
    ],
    "preview_language": "en"
  }'

# → { "voice_id": "pv_…", "name": "Ava voice", "kind": "cloned",
#     "credits_charged": 0, "preview_url": "https://…/preview.mp3", "warnings": [] }

Pick a studio voice — free

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", "studio_voice": "Sarah", "language": "spanish" }'

# → { "voice_id": "sv_…", "name": "Spanish narrator", "kind": "library",
#     "language": "spanish", "credits_charged": 0, "studio_voice": "Sarah", "gender": "female" }

Clone failure	What happened
400 (with sample_errors)	No usable sample — every URL failed to load or the check.
`422 NO_SPEECH`	The samples contain no speech. Refunded.
`502 CLONE_UNAVAILABLE`	Cloning is temporarily unavailable. Refunded; try again later.
`409 VOICE_LIMIT_REACHED`	Voice cap reached — delete one first. Refunded if two clones raced past the cap.
`409 FREE_CLONE_ATTEMPTS_EXHAUSTED`	Your free first clone failed 20 times. Nothing is charged; contact support to try again.

voice_id is opaque — store it as a string. Existing voice ids keep working.

Studio voices

GET/api/partner/v1/voices/presets

Free. Eight studio voices — Brian, Daniel, George, Chris (male); Sarah, Laura, Alice, Jessica (female). All are multilingual. Pass the name as studio_voice to POST /voices; without one, a voice is picked for you from gender (same account and name → same voice).

GET /voices/presets

curl https://platform.promoat.ai/api/partner/v1/voices/presets \
  -H "Authorization: Bearer $PROMOAT_KEY"

# → { "voices": [
#     { "studio_voice": "Brian", "gender": "male", "languages": "multilingual" },
#     …
#     { "studio_voice": "Sarah", "gender": "female", "languages": "multilingual" },
#     …
#   ] }

Re-clone a voice

POST/api/partner/v1/voices/{voice_id}/reclone

Body { "sample_urls": [...], "preview_language"? }. Makes a new voice id from new samples and removes the old one: { voice_id, previous_voice_id, name, kind: "cloned", credits_charged, preview_url, warnings }. It is free when the old voice expired (a 409 VOICE_UNAVAILABLE from /tts tells you), and 30 credits when it still works. Library voices → 400 NOT_A_CLONED_VOICE.

Re-clone an expired voice — free

curl -X POST https://platform.promoat.ai/api/partner/v1/voices/pv_OLD_ID/reclone \
  -H "Authorization: Bearer $PROMOAT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sample_urls": ["https://your-cdn.com/audio/ava-new-sample.mp3"], "preview_language": "en" }'

# → { "voice_id": "pv_…", "previous_voice_id": "pv_OLD_ID", "name": "Ava voice", "kind": "cloned",
#     "credits_charged": 0, "preview_url": "https://…/preview.mp3", "warnings": [] }

Point new videos and TTS calls at the new voice_id; the old id stops working.

Caps: 3 cloned, 10 library

Cloned voices are capped at 3 per account and library voices at 10 (separate caps). Over the cap → 409 VOICE_LIMIT_REACHED.

List & delete

GET/api/partner/v1/voices

Your voices, newest first — each with kind (cloned | library).

DELETE/api/partner/v1/voices/{id}

DELETE /voices/{id}

curl -X DELETE https://platform.promoat.ai/api/partner/v1/voices/pv_… \
  -H "Authorization: Bearer $PROMOAT_KEY"

# → { "deleted": true }

Frees the slot; audio and videos already made keep working.

Try it

Try itGET/api/partner/v1/voices/presetsfree

Add your API key in the sidebar to enable this.

Try itPOST/api/partner/v1/voicesfree

Request body (editable)

Add your API key in the sidebar to enable this.

Try itGET/api/partner/v1/voicesfree

Add your API key in the sidebar to enable this.

Try itPOST/api/partner/v1/voicescharges free for your first clone, then 30 credits

Request body (editable)

Add your API key in the sidebar to enable this.

← PreviousCharacters Next →Text-to-speech