curl --request PUT \
--url https://app.thinnest.ai/api/v1/agents/{id}/byok-voice \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"voice": "EXAVITQu4vr4xnSDxMaL"
}
'{
"voice": "a0e99841-438c-4a64-b679-ae501e7d6091",
"provider": "cartesia",
"speed": 0.95,
"volume": 1.4,
"emotion": null,
"agentModel": null,
"pronunciationDictId": null
}Set Agent BYOK Voice
Chooses the voice this agent speaks with on your own voice provider: an id from List BYOK Voices, checked against the provider’s list for your key, or null for the provider’s default. On Cartesia an id that is not on the list yet, such as a voice cloned a moment ago, is checked with Cartesia directly and accepted if your key owns it. The agent needs a voice channel first. A build key may do this.
On a Cartesia key you can also set how this agent’s voice sounds: speed (0.6 to 1.5), volume (0.5 to 2.0), emotion (one of Cartesia’s values; English only), model (sonic-3.6, sonic-3.6-2026-08-27, sonic-3.5, sonic-3 or sonic-2 for this agent alone; sonic-3.6 follows Cartesia’s latest stable snapshot, the dated one never changes) and pronunciationDictId (a dictionary id from your Cartesia account). Every field is optional and the request only changes what it names: a key left out stays as it is, null goes back to the default, a value sets it. So { "voice": "…" } alone changes the voice and keeps the settings; { "voice": null } goes back to the provider’s default voice and clears them. The settings belong to a voice of the agent’s own: sending one before a voice is chosen, or with voice: null, is refused. speed, volume and emotion need a Sonic 3 model, and speed does not apply to a Cartesia Professional Voice Clone. A refused field answers 400 with code: validation_failed and field naming it.
curl --request PUT \
--url https://app.thinnest.ai/api/v1/agents/{id}/byok-voice \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"voice": "EXAVITQu4vr4xnSDxMaL"
}
'{
"voice": "a0e99841-438c-4a64-b679-ae501e7d6091",
"provider": "cartesia",
"speed": 0.95,
"volume": 1.4,
"emotion": null,
"agentModel": null,
"pronunciationDictId": null
}Authorizations
Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.
Headers
Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.
"org_3fKq9TzQ1mN8vB2xR7cLpA"
Path Parameters
The agent's id (ag_…), as List Agents returns it. Another workspace's agent is the same 404 as one that never existed.
Body
Every field is optional, one at least. A key left out keeps what is saved, null resets it, a value sets it.
A voice id from List BYOK Voices, or null for the provider's default (which clears the settings below).
160Cartesia only. How fast the voice speaks; 1 is Cartesia's own. Needs a Sonic 3 model. Does not apply to a Professional Voice Clone.
0.6 <= x <= 1.5Cartesia only. How loud the voice is; 1 is Cartesia's own. Needs a Sonic 3 model.
0.5 <= x <= 2Cartesia only. One of Cartesia's emotions, for example neutral, calm, content, sad, angry, scared, happy, excited. Works in English only. Needs a Sonic 3 model.
Cartesia only. The Sonic model this agent speaks on; null uses your key's model.
sonic-3.6, sonic-3.6-2026-08-27, sonic-3.5, sonic-3, sonic-2, null Cartesia only. The id Cartesia gave a pronunciation dictionary in your account; null for none.
^[A-Za-z0-9][A-Za-z0-9_-]{2,79}$Response
The voice saved on the agent, with the provider it belongs to, and its settings (null while unset). The voice and provider are null after choosing the default.
The voice saved, or null for the provider's default.
The provider id the voice belongs to, or null with the default.
Cartesia only: the speed now saved, or null.
Cartesia only: the volume now saved, or null.
Cartesia only: the emotion now saved, or null.
Cartesia only: the Sonic model now saved for this agent (the request's model), or null.
Cartesia only: the dictionary id now saved, or null.