Clone a voice over the API

Create a cloned voice from an audio sample with the API, wait for it to be ready, and use it in an agent.

To create and manage cloned voices from your own code, use the voice cloning API. To try it by hand first, see Voice cloning.

Voice cloning must be included in your plan, and your API key's user needs access to it. If it is not, the endpoints answer 403.

Create a clone

Send the audio sample as Base64. You must also send consent: true to confirm you have the right to clone the voice. MP3, WAV and WebM are accepted, from 1 KB to 25 MB.

A real clip is too long for a command-line argument, so build the body in a file.

base64 < sample.mp3 | tr -d '\n' \
  | jq -Rs '{name:"Front desk", clip:., consent:true}' > body.json
curl -X POST "https://backend.omnidim.io/api/v1/voices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

The response is 202 with the new voice and status: processing. To retry safely after a network error, send an Idempotency-Key header: a retry with the same key returns the first clone instead of creating a second.

Wait for the voice to be ready

Creation runs in the background. Poll the voice until status is ready or failed.

curl "https://backend.omnidim.io/api/v1/voices/412" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use it in an agent

Once the status is ready, set the voice's voice_id on an agent with provider: cartesia.

{ "voice": { "provider": "cartesia", "voice_id": "<voice_id from the clone>" } }

Limits

Limits apply per user.

Limit	Value
New clones, from the API or the dashboard	5 an hour, 20 a day
Stored voices	200
Sample regenerations over the API	10 an hour

Over a limit, the API answers 429. For the hourly and daily limits, the Retry-After header says how many seconds to wait. At the stored limit, delete a voice to make room.

Manage your voices

The same API lists, reads, renames, deletes and previews your voices. See the voice cloning API reference for every field and response.