# Clone a voice over the API (/docs/voice-cloning-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](/docs/dashboard-guides/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 [#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.

    ```bash
    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 [#wait-for-the-voice-to-be-ready]

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

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

  
    ### Use it in an agent [#use-it-in-an-agent]

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

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

## Limits [#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 [#manage-your-voices]

The same API lists, reads, renames, deletes and previews your voices. See the
[voice cloning API reference](/docs/api-reference/voice-cloning/listClonedVoices)
for every field and response.