> ## AI Agent Context
> - Full documentation index: https://aistudio.google.com/llms.txt
> - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev
> - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md

# 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 %}

