> ## AI Agent Context > Get the complete documentation index at: https://aistudio.google.com/llms.txt > Use this file to discover all available pages. > For the full documentation in a single file, fetch: https://aistudio.google.com/llms-full.txt # Listing voices {% callout type="note" %} This API is in Beta. Endpoints are under `/v1beta/`. {% /callout %} {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/voices` Lists custom stored voices owned by the caller (ordered newest first) followed by prebuilt system voices from Google's voice catalog. {% two-column-layout %} {% left-column %} ## Parameters {% class="hide-from-toc" id="parameters" %} {% section class="api-ref-property-list" %} **accent**: `string array` Optional. Filter by accent description (e.g. "American", "British"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified accents (OR). {% hr /%} **context**: `string array` Optional. Filter by intended context or domain (e.g. "News, Commercial"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified contexts (OR). {% hr /%} **gender**: `string array` Optional. Filter by gender presentation (e.g. "female", "male", "neutral"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified genders (OR). {% hr /%} **language_code**: `string array` Optional. Filter by BCP-47 language code (e.g. "en-US"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified language codes (OR). {% hr /%} **page_size**: `integer` Optional. The maximum number of voices to return per page. The service may return fewer than this value. If unspecified, at most 50 voices are returned. The maximum value is 1000; values above 1000 are coerced to 1000. {% hr /%} **page_token**: `string` Optional. A page token received from a previous `ListVoices` call. Provide this to retrieve the subsequent page. When paginating, all filter query parameters (`language_code`, `region_code`, `accent`, `persona`, `context`, `gender`, `pitch`, `type`, and `search`) must match the call that returned this token; otherwise the request fails with `INVALID_ARGUMENT`. `page_size` may change between pages. {% hr /%} **persona**: `string array` Optional. Filter by vocal persona (e.g. "Warm, Friendly"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified personas (OR). {% hr /%} **pitch**: `string array` Optional. Filter by vocal pitch. Accepts `"low"`, `"medium"`, `"high"` (case-insensitive). If multiple values are specified, matches voices with any of the specified pitches (OR). {% hr /%} **region_code**: `string array` Optional. Filter by ISO 3166-1 alpha-2 or UN M.49 region code (e.g. "US", "001"). Case-insensitive exact match. If multiple values are specified, matches voices with any of the specified region codes (OR). {% hr /%} **search**: `string` Optional. Free-text substring search query matched case-insensitively against both `display_name` and `description`. Maximum 2048 bytes. {% hr /%} **type**: `string array` Optional. Filter by voice type. Accepts `"prebuilt"`, `"replicated"`, `"prompted"` (case-insensitive). If multiple values are specified, matches voices with any of the specified types (OR). {% /section %} {% /left-column %} {% right-column class="sticky" %} **Example request** {% class="example-heading" %} {% tabs %} {% tab label="REST" %} ```sh curl -X GET https://generativelanguage.googleapis.com/v1beta/voices \ -H "x-goog-api-key: $GEMINI_API_KEY" ``` {% /tab %} {% tab label="Python" %} ```python from google import genai client = genai.Client(http_options={"api_version": "v1beta"}) response = client.voices.list() for voice in response.voices or []: print(voice.id, voice.display_name) ``` {% /tab %} {% tab label="JavaScript" %} ```javascript import {GoogleGenAI} from '@google/genai'; const ai = new GoogleGenAI({apiVersion: 'v1beta'}); const response = await ai.voices.list(); for (const voice of response.voices ?? []) { console.log(voice.id, voice.display_name); } ``` {% /tab %} {% tab label="Go" %} ```go package main import ( "context" "fmt" "log" "google.golang.org/genai" "google.golang.org/genai/interactions/models/operations" ) func main() { ctx := context.Background() client, err := genai.NewClient(ctx, &genai.ClientConfig{ HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"}, }) if err != nil { log.Fatal(err) } res, err := client.Voices.List(ctx, operations.ListVoicesRequest{}) if err != nil { log.Fatal(err) } if res.ListVoicesResponse != nil { for _, voice := range res.ListVoicesResponse.Voices { if voice.ID != nil && voice.DisplayName != nil { fmt.Println(*voice.ID, *voice.DisplayName) } } } } ``` {% /tab %} {% /tabs %} {% /right-column %} {% /two-column-layout %} ## Response {% class="hide-from-toc" id="response" %} {% section class="api-ref-property-list" %} **voices**: [`Voice`](/api-reference/voices/list-voices#Resource:Voice) `array` The voices from the specified collection. {% hr /%} **next_page_token**: `string` A token that can be sent as `page_token` to retrieve the next page. If empty, there are no subsequent pages. {% /section %} ## Resources {% class="hide-from-toc" id="resources" %} ### Voice {% class="hide-from-toc" id="Resource:Voice" %} A voice resource representing either a custom voice (created via `CreateVoice`) or a prebuilt system voice (returned by `ListVoices`). **Properties:** {% section class="api-ref-property-list" %} {% details %} {% summary %} **type**: {% mark %}required{% /mark %} `VoiceType` The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`. {% /summary %} Possible values: - `replicated`: A custom voice replicated from a reference audio sample and speaker consent recording. - `prompted`: A custom voice generated from a natural-language text prompt (optionally editing or remixing a `base_voice`). - `prebuilt`: A built-in system voice from Google's voice catalog (e.g., `Puck`, `Charon`). Returned in responses; cannot be specified as the type in `CreateVoice`. {% /details %} {% hr /%} **id**: `string` Output only. The unique identifier of the voice. - For Google-managed custom voices (`store = true`), this is a generated ID with prefix `voice_` (for example, `voice_abc123def456`). Pass `voices/{id}` as the `name` in `GetVoice` and `DeleteVoice`, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis. - For prebuilt catalog voices (`"prebuilt"` returned by `ListVoices`), this is the speaker name (for example, `Puck` or `Charon`). - Unset when `CreateVoice` is called with `store = false`. {% hr /%} **model**: `string` Optional. The model used to design or replicate the voice. If omitted in `CreateVoice`, defaults to the latest supported voice design model. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for custom voices (`"prompted"` and `"replicated"`); unset for `"prebuilt"` voices. Created voices can be synthesized across any supported TTS synthesis model. {% hr /%} **key**: `string` Output only. The client-managed voice replication key (with prefix `voicekey_`). Returned only by `CreateVoice` when `type` is `"replicated"` and `store` is `false`. Pass this key to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis. {% hr /%} {% details %} {% summary %} **replicated**: `ReplicatedVoice` Input only. Parameters for replicated voice generation. Required on input when `type` is `"replicated"`. Not returned in responses. {% /summary %} {% details %} {% summary %} **source_audio**: {% mark %}required{% /mark %} `AudioData` The reference audio sample of the speaker's voice to replicate. Must be an unmodified recording of an adult human voice. {% /summary %} **mime_type**: {% mark %}required{% /mark %} `string` The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`). **data**: {% mark %}required{% /mark %} `string` The raw audio bytes. {% /details %} {% details %} {% summary %} **consent_audio**: {% mark %}required{% /mark %} `AudioData` Audio recording of the same speaker reading the required consent phrase, confirming authorization to replicate the voice. {% /summary %} **mime_type**: {% mark %}required{% /mark %} `string` The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`). **data**: {% mark %}required{% /mark %} `string` The raw audio bytes. {% /details %} {% /details %} {% hr /%} **expire_time**: `string` Output only. The timestamp at which a custom stored voice (`store = true`) or replicated voice key (`store = false`) expires. For custom stored voices (`store = true`), this expiration time is extended when the voice is used for speech synthesis or as a `base_voice` in `CreateVoice`. Unset for prebuilt catalog voices (`"prebuilt"`), which do not expire. {% hr /%} **display_name**: `string` Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice. {% hr /%} {% details %} {% summary %} **prompted**: `PromptedVoice` Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices. {% /summary %} **input**: {% mark %}required{% /mark %} `string` The natural-language prompt describing the desired voice, e.g. "A deep, booming male voice of a massive evil ogre in his middle years." **base_voice**: `string` Optional. The name or ID of an existing base voice to edit or remix. Use the voice name for prebuilt voices (e.g., `Puck`) or the voice ID for previously created voices (e.g., `voice_abc123`). This can be any prompted or replicated voice that the user has access to. When present, `input` describes relative alterations to make to the base voice. {% /details %} {% hr /%} **language_code**: `string` Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR"). {% hr /%} **region_code**: `string` Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001"). {% hr /%} **accent**: `string` Optional. Regional accent descriptor (e.g. "American", "British"). {% hr /%} **persona**: `string` Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator"). {% hr /%} **context**: `string` Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News"). {% hr /%} **gender**: `string` Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral"). {% hr /%} {% details %} {% summary %} **pitch**: `Pitch` Optional. Voice pitch classification. {% /summary %} Possible values: - `low`: Lower pitch voice. - `medium`: Medium pitch voice. - `high`: Higher pitch voice. {% /details %} {% hr /%} **description**: `string` Optional. Descriptive summary of vocal timbre, personality, and tone. {% hr /%} {% details %} {% summary %} **usage**: `Usage` Output only. Token usage statistics for the voice creation request. Populated only in the response of `CreateVoice` when `type` is `"prompted"`; unset for `"replicated"` and in `GetVoice` and `ListVoices` responses. {% /summary %} **total_input_tokens**: `integer` Number of tokens in the prompt (context). **initial_input_tokens**: `integer` Number of input tokens used in the first turn of this interaction. {% details %} {% summary %} **input_tokens_by_modality**: `ModalityTokens array` A breakdown of input token usage by modality. {% /summary %} {% details %} {% summary %} **modality**: `ResponseModality` The modality associated with the token count. {% /summary %} Possible values: - `text`: Indicates the model should return text. - `image`: Indicates the model should return images. - `audio`: Indicates the model should return audio. - `video`: Indicates the model should return video. - `document`: Indicates the model should return documents. {% /details %} **tokens**: `integer` Number of tokens for the modality. {% /details %} **total_cached_tokens**: `integer` Number of tokens in the cached part of the prompt (the cached content). {% details %} {% summary %} **cached_tokens_by_modality**: `ModalityTokens array` A breakdown of cached token usage by modality. {% /summary %} {% details %} {% summary %} **modality**: `ResponseModality` The modality associated with the token count. {% /summary %} Possible values: - `text`: Indicates the model should return text. - `image`: Indicates the model should return images. - `audio`: Indicates the model should return audio. - `video`: Indicates the model should return video. - `document`: Indicates the model should return documents. {% /details %} **tokens**: `integer` Number of tokens for the modality. {% /details %} **total_output_tokens**: `integer` Total number of tokens across all the generated responses. {% details %} {% summary %} **output_tokens_by_modality**: `ModalityTokens array` A breakdown of output token usage by modality. {% /summary %} {% details %} {% summary %} **modality**: `ResponseModality` The modality associated with the token count. {% /summary %} Possible values: - `text`: Indicates the model should return text. - `image`: Indicates the model should return images. - `audio`: Indicates the model should return audio. - `video`: Indicates the model should return video. - `document`: Indicates the model should return documents. {% /details %} **tokens**: `integer` Number of tokens for the modality. {% /details %} **total_tool_use_tokens**: `integer` Number of tokens present in tool-use prompt(s). {% details %} {% summary %} **tool_use_tokens_by_modality**: `ModalityTokens array` A breakdown of tool-use token usage by modality. {% /summary %} {% details %} {% summary %} **modality**: `ResponseModality` The modality associated with the token count. {% /summary %} Possible values: - `text`: Indicates the model should return text. - `image`: Indicates the model should return images. - `audio`: Indicates the model should return audio. - `video`: Indicates the model should return video. - `document`: Indicates the model should return documents. {% /details %} **tokens**: `integer` Number of tokens for the modality. {% /details %} **total_thought_tokens**: `integer` Number of tokens of thoughts for thinking models. **total_tokens**: `integer` Total token count for the interaction request (prompt + responses + other internal tokens). {% details %} {% summary %} **grounding_tool_count**: `GroundingToolCount array` Grounding tool count. {% /summary %} {% details %} {% summary %} **type**: `string enum` The grounding tool type associated with the count. {% /summary %} Possible values: - `google_search`: Grounding with Google Web Search and Image Search, & Web Grounding for Enterprise. - `google_maps`: Grounding with Google Maps. {% /details %} **count**: `integer` The number of grounding tool counts. {% /details %} {% /details %} {% hr /%} {% details %} {% summary %} **sample_audio**: `AudioData` Output only. Sample audio (synthesizer prompt audio) generated for a prompted voice. Populated only in `CreateVoice` and `GetVoice` responses when `type` is `"prompted"`; unset in `ListVoices` responses and for `"replicated"` or `"prebuilt"` voices. {% /summary %} **mime_type**: {% mark %}required{% /mark %} `string` The IANA MIME type of the audio data (for example, `audio/wav` or `audio/mpeg`). **data**: {% mark %}required{% /mark %} `string` The raw audio bytes. {% /details %} {% /section %}