> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List Voices
> List all voices available for agents.
Read only
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
Returns every text-to-speech voice supported by DialNexa, paginated and filterable by language code or gender. Each entry includes the voice's stable `id`, display `name`, BCP-47 `language_code`, perceived `gender`, and upstream `provider`. Use the `id` field as the value for `voice.id` when creating or updating an agent. The catalogue evolves as upstream providers add new voices, call this endpoint at deploy time rather than hard-coding the list.
## When to use this
* **Voice pickers**: populate the dropdown when an operator is choosing a voice for an agent.
* **Brand audits**: confirm a given voice is still available before publishing an agent change.
* **Localization**: find every voice that supports a specific BCP-47 language for a multi-region rollout.
* **Gender-balanced selection**: sample voices by gender for accessibility or brand reasons.
For deeper detail on a specific voice (preview URL, default model, supported accents), use [Get Voice Details](/docs/api-reference/v1/voices/get). For the model variants of a voice, use [List Voice Models](/docs/api-reference/voices/voice-models).
## Query parameters
| Parameter | Description |
| --------------- | ------------------------------------------------------------- |
| `language_code` | Filter by BCP-47 language code, for example `en-US`, `hi-IN`. |
| `gender` | Filter by `male`, `female`, or `neutral`. |
| `provider` | Filter by upstream provider, for example `elevenlabs`. |
| `page` | Page number, starting from 1. |
| `limit` | Results per page (default 50, max 100). |
## Errors
* `401 Unauthorized` is returned when the API key is missing or revoked.
## Related endpoints
* [Get Voice Details](/docs/api-reference/v1/voices/get): detail for a single voice.
* [List Voice Models](/docs/api-reference/voices/voice-models): model variants for a voice.
* [List Accents](/docs/api-reference/v1/voices/accents): accent filter dimension.
* [Text-to-speech and voices](/docs/voice-ai/text-to-speech-and-voices): guidance on choosing the right voice.
## OpenAPI
````yaml GET /v1/voices
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/voices:
get:
tags:
- Voices
- Voices V1
- V1
summary: List Voices
description: >-
Returns all available voices with optional filtering by provider,
accent, gender, or name.
operationId: VoicesV1Controller_findAll
parameters:
- name: provider
required: false
in: query
description: Filter by TTS provider
schema:
enum:
- elevenlabs
- smallestai
- sarvam
- cartesia
type: string
- name: accent
required: false
in: query
description: Accent of the voice
schema:
enum:
- indian
- british
- american
- canadian
- african
- australian
- swedish
type: string
- name: gender
required: false
in: query
description: Gender of the voice
schema:
enum:
- male
- female
- non-binary
type: string
- name: name
required: false
in: query
description: Search by voice name
schema:
example: English
type: string
- name: page
required: false
in: query
description: Page number (starts from 1)
schema:
default: '1'
example: 1
type: number
- name: limit
required: false
in: query
description: Max 50
schema:
default: '20'
example: 20
type: number
- name: language_id
required: false
in: query
description: Filter voices that support a specific language ID
schema:
example: abc12345678901
type: string
- name: llm_id
required: false
in: query
description: Filter voices compatible with a specific LLM ID (S2S models only)
schema:
example: abc12345678901
type: string
responses:
'200':
description: Voices returned successfully.
content:
application/json:
schema:
type: object
properties:
voices:
type: array
items:
type: object
total:
type: number
page:
type: number
limit:
type: number
totalPages:
type: number
examples:
success:
summary: Successful response
value:
voices:
- id: voice_abc123
name: Aditi
provider: elevenlabs
language_code: en-IN
gender: female
total: 1
page: 1
limit: 20
totalPages: 1
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden - API key does not have access to this organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this resource
error: Forbidden
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````