API reference · Voice Intelligence

Voice Cloning and Design

There are two ways to add a voice to your account:

Clone a real voice from a recording.
Design a new voice from a written description.

Either way, the result shows up in GET /voice/public/voices and works anywhere a voice_id is accepted: tts_body sends, voice broadcasts, AI agents and text-to-speech.

Get consent from the person whose voice you clone.

Clone a voice

POST /voice/public/voices/clone · scope media:write

curl https://api-v2.dropcowboy.com/voice/public/voices/clone \
  -H "x-key: $DROPCOWBOY_KEY" -H "x-secret: $DROPCOWBOY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan",
    "sample_url": "https://media.example.com/samples/jordan.wav",
    "gender": "female"
  }'

{
  "data": {
    "voice_id": "7d2a9e4b-1c6f-4b3a-8e5d-2f9c7a1b4e63",
    "long_job_id": "1d5b9f3e-7a2c-4e8d-b6f1-3c7a9e5d2b84"
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

The route answers 202 straight away and clones in the background.

Field	Notes
`sample_url`	Public URL of a clean recording. `url` is accepted as an alias.
`media_id`	A recording already in your media library, instead of `sample_url`. Pass `ext` (for example `.mp3`) with it.
`voice_id`	Re-clone one of your existing voices instead of creating a new one.
`name`	Defaults to "My Voice".
`gender`, `instructions`, `speed`	Optional. `speed` is 0.25 to 4.

One of sample_url, media_id or voice_id is required.

Wait for it to finish

Poll GET /voice/public/voices and find your voice_id:

`status`	Meaning
`ready`	Usable.
`pending_payment`	Cloned, but the voice slot has not been purchased. Buy it in the dashboard. The clone response also sets `pending_payment: true` in this case.
anything else	Still processing. A non-null `failed_at` means it failed.

Poll every few seconds, and stop after a few minutes. There is no webhook for clone completion.

Design a voice

POST /voice/public/voices/design · scope media:write

curl https://api-v2.dropcowboy.com/voice/public/voices/design \
  -H "x-key: $DROPCOWBOY_KEY" -H "x-secret: $DROPCOWBOY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Warm, friendly receptionist in her thirties, relaxed pace.",
    "text": "Thanks for calling Example Dental. How can I help?"
  }'

The route answers 202 with a long_job_id. Previews are free.

Field	Notes
`instructions`	Required. Up to 500 characters describing the voice.
`text`	Required. The line the preview reads.
`language`, `name`	Optional.
`speed`	Optional, 0.25 to 4.

You review the preview and save it as a voice in the dashboard. The API has no route to fetch a design preview yet. Once saved, the voice appears in GET /voice/public/voices with type: "designed".

Delete a voice

DELETE /voice/public/voices/{voice_id} · scope media:write

curl -X DELETE https://api-v2.dropcowboy.com/voice/public/voices/7d2a9e4b-1c6f-4b3a-8e5d-2f9c7a1b4e63 \
  -H "x-key: $DROPCOWBOY_KEY" -H "x-secret: $DROPCOWBOY_SECRET"

{
  "data": {
    "voice_id": "7d2a9e4b-1c6f-4b3a-8e5d-2f9c7a1b4e63",
    "deleted": true
  },
  "meta": { "request_id": "e4b8a2c6-9d3f-4a1e-b7c5-8f2d6a9e3b17" }
}

The voice is removed from GET /voice/public/voices, its clone at the speech provider is deleted, and it can no longer be used in sends or synthesis. Saved voices past your first are billed monthly, so deleting one lowers that count by one. A voice still in pending_payment is removed from your checkout cart instead.

Only your account's voices can be deleted. Platform catalog voices, other accounts' voices, already deleted voices and unknown ids answer 404. Wait until a clone's status is ready or failed before deleting it.

Errors

Status	Cause
`400`	No sample given, `instructions` too long, `speed` out of range, or the sample could not be read. On delete, a `voice_id` that is not a UUID.
`402`	Billing blocks the clone, for example a voice still awaiting checkout. `type` ends `payment-required`.
`404`	Re-clone or delete of a `voice_id` that is not one of your voices.

See Errors and limits.