Skip to main content
GET
/
voices
/
v1
/
voices
cURL
# Filter by source and language, sorted by name
curl -sG 'https://api.inworld.ai/voices/v1/voices' \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  --data-urlencode 'filter=source = "SYSTEM" AND lang_code = "en"' \
  --data-urlencode 'orderBy=display_name asc' \
  --data-urlencode 'pageSize=20'

# Fetch the next page using the token from the previous response
curl -sG 'https://api.inworld.ai/voices/v1/voices' \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  --data-urlencode 'pageSize=20' \
  --data-urlencode 'pageToken=1-20'
{
  "voices": [
    {
      "name": "workspaces/inworld/voices/Alex",
      "voiceId": "Alex",
      "langCode": "EN_US",
      "displayName": "Alex",
      "description": "Energetic and expressive mid-range male voice, with a mildly nasal quality",
      "tags": [
        "friendly",
        "expressive"
      ],
      "categories": [
        "companions"
      ],
      "source": "SYSTEM",
      "gender": "male",
      "ageGroup": "middle_aged",
      "promptLanguages": [
        "en-US"
      ]
    },
    {
      "name": "workspaces/your_workspace_id/voices/my_voice_clone_demo_20260218_223134z",
      "voiceId": "your_workspace_id__my_voice_clone_demo_20260218_223134z",
      "langCode": "EN_US",
      "displayName": "John",
      "description": "Cloned voice for narrations.",
      "tags": [
        "demo",
        "clone"
      ],
      "categories": [],
      "source": "IVC",
      "gender": "",
      "ageGroup": "",
      "promptLanguages": [
        "en-US"
      ]
    }
  ],
  "totalSize": 42,
  "nextPageToken": "1-20"
}

Documentation Index

Fetch the complete documentation index at: https://docs.inworld.ai/llms.txt

Use this file to discover all available pages before exploring further.

Short URL Path: /workspaces/{workspace} is no longer required in the path for simplicity and clarity. When omitted, the workspace is derived from your API key. The previous URL with the full path /voices/v1/workspaces/{workspace}/voices would continue to be supported.
Want to hear how a voice sounds? Use the Get voice preview endpoint to listen to a short audio sample of any voice — free and unbilled.

Authorizations

Authorization
string
header
required

Your API key. Read permissions are required for GET endpoints. Write permissions are required for POST, PATCH, and DELETE endpoints.

For Basic authentication, please populate Basic $INWORLD_API_KEY

Query Parameters

filter
string

AIP-160 filter expression. Combine conditions with AND / OR / NOT; values must be quoted.

Filterable fields:

FieldOperatorsExample
source=, !="SYSTEM", "IVC"
gender=, !="male", "female", "neutral"
age_group=, !="young", "middle_aged", "elderly"
lang_code=, !=e.g. "en-US"
tags: (has)any tag string
categories: (has)"companions", "enterprise", "education_training", "developer_assistants", "healthcare", "interactive_media"

lang_code note: the filter accepts BCP-47 (en-US), underscore form (en_US), or a language prefix (en). The response langCode field always uses upper-snake format (EN_US). This filter matches only the voice's primary language (langCode) — it does not consider the localized promptLanguages.

source note: "SYSTEM" voices are Inworld built-ins visible to every workspace. "IVC" voices are clones or designed voices owned by your workspace only.

Returns 400 INVALID_ARGUMENT for unknown fields, operator/field mismatches, or malformed syntax.

orderBy
string

Sort field with optional direction (asc or desc). Defaults to display_name asc.

Supported fields: display_name, created_at, gender, age_group. Unknown fields return 400.

pageSize
integer<int32>

Maximum number of voices to return. Cannot exceed 2000.

pageToken
string

Opaque pagination cursor from a previous response's nextPageToken. Pass it back unchanged to retrieve the next page. An empty string starts from the beginning.

languages
string[]

Legacy language filter — returns voices matching ANY of the specified languages. Supported formats: EN_US or en.

Do not combine with filter — using both together produces undefined behavior. Prefer lang_code inside a filter expression for new integrations.

Response

A successful response.

Response message for ListVoices.

voices
object[]

Voices for this page.

totalSize
integer<int32>

Total number of voices matching the filter across all pages.

nextPageToken
string

Opaque cursor to pass as pageToken to fetch the next page. Empty string when there are no more pages.

Note: pagination is offset-based. Concurrent inserts or deletes during a multi-page walk may cause a voice to appear twice or be skipped.