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

# 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 that you create or a
prebuilt system voice (returned when listing voices).

**Properties:**

{% section class="api-ref-property-list" %}
  {% details %}
  {% summary %}
  **type**: {% mark %}required{% /mark %} `VoiceType`

  The type of the voice. When creating a voice, must be `"replicated"` or `"prompted"`. When listing voices, 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 when creating a voice.

  {% /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` when getting or deleting the voice, and pass `{id}` directly to `SpeechConfig.voice_config.voice` (or `SpeechConfig.voice`) during speech synthesis.
  - For prebuilt catalog voices (`"prebuilt"` returned when listing voices), this is the speaker name (for example, `Puck` or `Charon`).
  - Unset when the voice is created with `store = false`.

  {% hr /%}

  **model**: `string`

  Optional. The model used to design or replicate the voice. If omitted when creating a voice, defaults to the latest supported voice design model. Returned when creating, getting, or listing 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 when creating a voice with `type` `"replicated"` and `store` `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` when creating another voice. 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 when creating a voice with `type` `"prompted"`. Returned when creating, getting, or listing 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 when creating a voice with `type` `"prompted"`; unset for `"replicated"` and when getting or listing voices.

  {% /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 when creating or getting a voice with `type` `"prompted"`; unset when listing voices 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 %}

