v1

latestOpenAPI 3.0.02026-07-262088144.5 KB

VoiceService

Lists voices in a workspace

Returns SYSTEM voices (visible to all workspaces) plus IVC voices owned by the calling workspace, with optional filtering, sorting, and pagination.

Calling with no parameters (no filter, pageSize, or pageToken) uses a legacy code path that returns the full list in a single response — existing clients continue to work without changes. The unpaginated path is capped at 2000 voices.

get/voices/v1/voices

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"
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"
starred	=	"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: "SYSTEM" voices are Inworld built-ins visible to every workspace. "IVC" voices are clones or designed voices owned by your workspace only.

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, star_count. 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

A successful response.

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.

Example response

{
  "voices": [
    {
      "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"
      ]
    }
  ]
}