VoiceService

List voices in a workspace

Returns system catalog voices available to the calling workspace and its custom voices, including instant clones (IVC), designed voices (TVD), and professional voices (PVC), with optional filtering, sorting, and pagination. The source field describes provenance and can also be OTHER; it does not indicate ownership. Community voices from other workspaces require the community="true" filter.

Responses contain up to 2000 voices. Set pageSize explicitly and follow nextPageToken until it is empty or absent. Pagination is offset-based, not a stable snapshot: concurrent catalog changes can repeat or skip entries.

GET/voices/v1/voices

By default, this endpoint returns your workspace's cloned and designed voices along with Inworld system voices. Voices shared by other users to the community Voice Library are excluded unless you set the community="true" filter.

Want to hear how a voice sounds? Use the Get voice preview endpoint to listen to a short audio sample of any voice — not billed, though rate and concurrency limits are stricter than synthesis, so cache the audio you serve to many users.

List and select voices

Send GET https://api.inworld.ai/voices/v1/voices with Authorization: Basic <INWORLD_API_KEY>. The API key determines the workspace. Use pageSize and follow nextPageToken to populate a voice picker:

bash

curl --get 'https://api.inworld.ai/voices/v1/voices' \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --data-urlencode 'pageSize=20' \
  --data-urlencode 'filter=source="SYSTEM"'

Query parameter	Use
`filter`	AIP-160 filter expression; see Filter expressions
`pageSize`	Page size, up to 2,000; set explicitly for a paginated picker
`pageToken`	Previous response's `nextPageToken`, passed back unchanged
`orderBy`	Sort order: `display_name`, `created_at`, `gender`, or `age_group`, each optionally `asc` or `desc`; defaults to `display_name asc`
`languages`	Legacy language filter matching ANY listed language; do not combine with `filter`

Filter expressions

Quote every value. Combine conditions with AND, OR, NOT, and parentheses, for example (gender="female" OR gender="neutral") AND tags:"funny" AND lang_code="en".

Filterable field	Operators	Values
`source`	`=`, `!=`	`SYSTEM`, `IVC`, `TVD`, `PVC`, `OTHER`
`gender`	`=`, `!=`	`male`, `female`, `neutral`
`age_group`	`=`, `!=`	`young`, `middle_aged`, `elderly`
`lang_code`	`=`, `!=`	BCP-47 (`en-US`), underscore form (`en_US`), or a bare language prefix (`en`)
`tags`	`:` (has)	Any tag string
`categories`	`:` (has)	`companions`, `enterprise`, `education_training`, `developer_assistants`, `healthcare`, `interactive_media`
`owned`	`=`	`true` matches only custom voices created in your workspace; system voices and other workspaces' community voices are `false`
`community`	`=`	`true` includes community voices shared by other workspaces; when omitted they are excluded

source describes provenance only — it does not imply ownership or community visibility, so use owned and community for those. lang_code matches the voice's primary language and ignores promptLanguages. Any filter applies on top of the voices already visible to the calling workspace.

Unknown fields, operator/field mismatches, and malformed syntax return 400 INVALID_ARGUMENT.

An illustrative response, with optional fields omitted:

json

{
  "voices": [{
    "voiceId": "Ashley",
    "displayName": "Ashley",
    "source": "SYSTEM",
    "languageCode": "en-US",
    "langCode": "EN_US"
  }],
  "nextPageToken": "<opaque-cursor>",
  "totalSize": 42
}

Repeat the same filters and ordering with the returned pageToken until nextPageToken is empty or absent. totalSize is the matching count across pages, not the length of the current page. Pagination is offset-based and does not provide a stable snapshot. Concurrent catalog changes can cause entries to repeat or be skipped. Key picker entries by voiceId to deduplicate them; this does not recover skipped entries. Refresh the listing when current completeness matters.

Voice field	Use
`voiceId`	Pass unchanged to synthesis (`voiceId`) or preview (`voice_id`)
`displayName`	Human-readable picker label; do not use as an API identifier
`name`	Resource identifier when supplied; system voices can have a bare ID rather than a workspace resource path
`source`	Voice provenance: `SYSTEM`, `IVC` (instant clone), `TVD` (voice design), `PVC`, or `OTHER`; tolerate additional values
`languageCode`	Language string such as `en-US`
`langCode`	Legacy enum form such as `EN_US`
`promptLanguages`	Available voice-prompt languages; does not enumerate every language the synthesis model supports
`owned`	On community voice results, indicates whether the calling workspace owns the voice; use alongside sharing metadata

Use Get voice preview to listen without synthesizing your own text. A system voice's voiceId works with preview and synthesis even when a voice-management GET constructed from that bare ID returns not found.

Authorizations

Authorizationstringrequired

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. You can create a key in one command with the Inworld CLI: inworld workspace add-key.

Query Parameters

filterstring

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

Filterable fields:

Field	Operators	Example
`source`	`=`, `!=`	`"SYSTEM"`, `"IVC"`, `"TVD"`, `"PVC"`, `"OTHER"`
`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"`
`owned`	`=`	`"true"`, `"false"`
`community`	`=`	`"true"`

`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: Filter by provenance: "SYSTEM" (system catalog), "IVC" (instant voice clone), "TVD" (voice design), "PVC" (professional or supplied custom voice), or "OTHER". Source does not determine ownership or community visibility; use owned and community for those filters. A filter only returns voices visible to the calling workspace.

`owned` note: owned = "true" matches only custom voices created in your workspace. System voices and community voices shared by other workspaces are owned = "false".

`community` note: Set community = "true" to list community voices shared by other users. If not specified, community voices are filtered out of the listed voices.

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

orderBystring

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.

pageSizeinteger

Maximum number of voices to return. Cannot exceed 2000.

pageTokenstring

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.

languagesstring[]

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

200 - application/json

voicesobject[]

Voices for this page.

Show child attributes

voiceIdstring

Voice ID. SYSTEM voices use a simple name (e.g. Alex); IVC voices are workspace-prefixed ({workspace}__{voice}).

langCodeenum<string>

Primary language of the voice in upper-snake format (e.g. EN_US). Note that when filtering via lang_code, you can pass BCP-47 (en-US), underscore form (en_US), or a language prefix (en) — but the response always returns upper-snake.

Available options:EN_USZH_CNKO_KRJA_JPRU_RUAUTOIT_ITES_ESPT_BRDE_DEFR_FRAR_SAPL_PLNL_NLHI_INHE_IL

languageCodestring

Canonical wire form of the voice's primary language as a single string (e.g. en-US, es-MX, vi). Populated on every read alongside the legacy langCode enum. Immutable after creation.

displayNamestring

The human-readable name shown anywhere the voice is listed or selected.

descriptionstring

Longer blurb that explains the voice's tone, accent, use cases, or other relevant attributes.

tagsstring[]

Free-form labels for filtering, grouping, and discovery (e.g. british, calm).

namestring

Resource identifier. Workspace voices use workspaces/{workspace}/voices/{voice}; system and shared voices may use a bare identifier. For synthesis and audio previews, use voiceId unchanged instead of constructing a resource path.

sourceenum<string>

Voice provenance: SYSTEM (Inworld system voice), IVC (instant voice clone), TVD (voice design), PVC (professional or supplied custom voice), or OTHER. Treat provenance separately from community-sharing and ownership metadata.

Available options:SYSTEMIVCTVDPVCOTHER

genderenum<string>

Voice gender (male, female, neutral). Empty string if unspecified. Voices with no gender are excluded when filtering with an explicit gender = predicate.

Available options:malefemaleneutral

ageGroupenum<string>

Age group of the voice (young, middle_aged, elderly). Empty string if unspecified.

Available options:youngmiddle_agedelderly

categoriesenum<string>[]

Use-case categories the voice belongs to. Filterable with the : (has) operator.

Supported values: companions, enterprise, education_training, developer_assistants, healthcare, interactive_media.

promptLanguagesstring[]

Languages the voice can handle, in BCP-47 format (e.g. en-US). May differ from langCode for multilingual voices.

ownedboolean

For a community voice result, whether the calling workspace owns the voice. Interpret alongside community-sharing metadata; this field is not a general test for whether synthesis is permitted.

totalSizeinteger

Total number of voices matching the filter across all pages.

nextPageTokenstring

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.

Lists voices in a workspace

# 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'

successful_response

{
  "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"
}