Voices

A Voice is a custom ElevenLabs voice profile scoped to your workspace. Each voice is created from an audio sample file and is available for use within the workspace that created it.

Workspaces also have access to default voices (platform-wide, read-only) returned alongside workspace voices in the list endpoint. Default voices have workspaceId: null and isDefault: true.

Voice creation deducts credits from your workspace's voice_creation monthly allowance. The credit cost per voice and the maximum number of voices per workspace are configured by the platform administrator. Automatic internal voices created during the dubbing pipeline do not consume this public voice creation allowance.

Create a voicePOST/v1/voiceschevron_right
List voicesGET/v1/voiceschevron_right
Retrieve a voiceGET/v1/voices/{voiceId}chevron_right
Update a voicePATCH/v1/voices/{voiceId}chevron_right
Delete a voiceDELETE/v1/voices/{voiceId}chevron_right

The Voice object

voiceIdstring: Unique identifier (vce_…).
workspaceIdstring | null: Owning workspace. null for default platform voices.
namestring: Display name for the voice.
descriptionstring: Optional description of the voice.
isDefaultboolean: true for platform default voices visible to all workspaces.
createdAttimestamp: When the voice was created.
updatedAttimestamp: Last update time.

{
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wks_01HX...",
  "name": "Sarah - warm narrator",
  "description": "Smooth, calm voice for narration",
  "isDefault": false,
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
}

Create a voice

POST/v1/voices

Creates a new custom voice for the workspace by uploading an audio sample directly. The request must be sent as multipart/form-data.

Voice creation consumes credits from the workspace's voice_creation monthly allowance. The credit cost is set by the platform administrator (default: 1 credit per voice).

This credit rule applies to public /v1/voices calls. Automatic voices created internally by the dubbing pipeline are tied to that dubbing run and do not consume the public voice creation allowance.

Supported audio formats: .mp3, .wav, .m4a, .ogg, .flac, .webm. Maximum file size: 5 MB.

Requires permission

voices:create

Parameters

namestring (form field): Display name for the voice. Required.
descriptionstring (form field), optional: Short description of the voice.
audiofile (form field): Audio sample file. Accepted formats: .mp3, .wav, .m4a, .ogg, .flac, .webm. Maximum 5 MB.

Returns

Returns the created Voice object.

See the the voice object for attribute details.

curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/voices" \
  -H "Authorization: Bearer sk_prj_..." \
  -F "name=Sarah - warm narrator" \
  -F "description=Smooth, calm voice for narration" \
  -F "audio=@/path/to/voice_sample.mp3"

{
  "data": {
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wks_01HX...",
  "name": "Sarah - warm narrator",
  "description": "Smooth, calm voice for narration",
  "isDefault": false,
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

List voices

GET/v1/voices

Returns all voices visible to the workspace: workspace-owned voices and platform default voices. Default voices are sorted first; workspace voices follow ordered by creation time ascending.

Requires permission

voices:list

Returns

Returns an array of Voice objects.

See the the voice object for attribute details.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/voices" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": [
  {
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wks_01HX...",
  "name": "Sarah - warm narrator",
  "description": "Smooth, calm voice for narration",
  "isDefault": false,
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
},
  {
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W9N",
  "workspaceId": null,
  "name": "Standard English",
  "description": "Default platform voice",
  "isDefault": true,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}
],
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Retrieve a voice

GET/v1/voices/{voiceId}

Returns a single voice by its voiceId. The voice must belong to the workspace or be a platform default.

Requires permission

voices:read

Parameters

voiceIdstring: Voice identifier (vce_…).

Returns

Returns a Voice object.

See the the voice object for attribute details.

curl "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/voices/vce_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wks_01HX...",
  "name": "Sarah - warm narrator",
  "description": "Smooth, calm voice for narration",
  "isDefault": false,
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Update a voice

PATCH/v1/voices/{voiceId}

Updates the name and/or description of a workspace-owned voice. Default platform voices cannot be updated.

Requires permission

voices:edit

Parameters

voiceIdstring: Voice identifier (vce_…).
namestring, optional: New display name.
descriptionstring, optional: New description.

Returns

Returns the updated Voice object.

See the the voice object for attribute details.

curl -X PATCH "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/voices/vce_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..." \
  -H "Content-Type: application/json" \
-d '{
  "name": "Sarah - updated",
  "description": "Revised description"
}'

{
  "data": {
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wks_01HX...",
  "name": "Sarah - warm narrator",
  "description": "Smooth, calm voice for narration",
  "isDefault": false,
  "createdAt": "2024-05-15T10:30:00.000Z",
  "updatedAt": "2024-05-15T10:30:00.000Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Delete a voice

DELETE/v1/voices/{voiceId}

Soft-deletes a workspace-owned voice and removes it from ElevenLabs. Default platform voices cannot be deleted. The voice is immediately removed from the GET /v1/voices list.

Requires permission

voices:delete

Parameters

voiceIdstring: Voice identifier (vce_…).

Returns

Returns an object confirming deletion: { voiceId: "...", deleted: true }

See the the voice object for attribute details.

curl -X DELETE "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/voices/vce_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_prj_..."

{
  "data": {
  "voiceId": "vce_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "deleted": true
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}