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

# Gemini Voices API

{% callout type="note" %}
  This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

The Voices API allows you to create custom voices from natural language prompts (Voice Design) or from reference audio and speaker consent recordings (Voice Replication), as well as list, retrieve, and manage custom and prebuilt voices for Text-to-Speech (TTS) synthesis.

## Methods  {% id="methods" %}

{% table %}
  * Method
  * HTTP request

  ---

  * [Creating a voice](/api-reference/voices/create-voice)
  *     {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/voices`

    Creates a custom voice from a natural-language prompt (`VOICE_TYPE_PROMPTED`) or from reference and consent audio recordings (`VOICE_TYPE_REPLICATED`).


  ---

  * [Listing voices](/api-reference/voices/list-voices)
  *     {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/voices`

    Lists custom stored voices owned by the caller (ordered newest first) followed by prebuilt system voices from Google's voice catalog.


  ---

  * [Getting a voice](/api-reference/voices/get-voice)
  *     {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/voices/{voicesId}`

    Gets a custom stored voice (`store = true`) by resource name.


  ---

  * [Deleting a voice](/api-reference/voices/delete-voice)
  *     {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/voices/{voicesId}`

    Deletes a custom stored voice (`store = true`) by resource name.

{% /table %}

## Resources  {% id="resources" %}

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