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
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
Body
Every field is optional, one at least. A key left out keeps what is saved, null resets it, a value sets it.
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.