You can create a new custom voice by editing an existing voice with the
voice remixing feature. Instead of describing a voice from scratch, you choose
a base voice and describe the changes to make, such as a different age, pitch,
energy, timbre, or accent. The Voices API stores the result as a new voice in
your project and returns a reusable voice_... ID that you pass in speech
generation requests.
You can remix the following voices:
- A prebuilt voice,
such as
PuckorKore. - An Extended Voice Library voice.
- A designed voice or a previously remixed voice that's stored in your project.
Remixed voices work with both
Gemini 3.8 Flash TTS
(gemini-3.8-flash-tts) and
Gemini 3.8 Flash-Lite TTS
(gemini-3.8-flash-lite-tts).
How voice remixing works
Voice remixing uses the same Voices API create method as
voice design, with the
voice.prompted.base_voice field added:
- Choose a base voice and describe the changes: Call the Voices API
createmethod withvoice.typeset toVOICE_TYPE_PROMPTED,storeset totrue,voice.prompted.base_voiceset to the name or ID of an existing voice, andvoice.prompted.inputset to a description of the changes. - Receive a new voice ID and a sample: The Voices API applies your
changes to the base voice, stores the result as a new voice in your
project, and returns its ID (for example,
voice_abc123...) in theidfield and a sample of the voice in thesample_audiofield. The base voice doesn't change. - Generate speech or remix again: Pass the new voice ID in
speechConfig.voiceConfig.voicewhen you callgenerateContentorstreamGenerateContent. To refine the voice further, pass the new voice ID as thebase_voiceof anothercreaterequest.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init -
Create or select a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_IDwith a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_IDwith your Google Cloud project name.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled:
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.gcloud services enable aiplatform.googleapis.com
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init -
Create or select a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace
PROJECT_IDwith a name for the Google Cloud project you are creating. -
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace
PROJECT_IDwith your Google Cloud project name.
-
If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled:
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.gcloud services enable aiplatform.googleapis.com
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
To use the Python samples, install version 2.33.0 or later of the Google Gen AI SDK:
pip install --upgrade "google-genai>=2.33.0"
The Voices API is available in the global location through the v1beta1 API
version.
Required roles
To get the permissions that you need to remix voices and generate speech with them, ask your administrator to grant you the following IAM roles on your Google Cloud project:
-
Create, list, get, and delete voices, and generate speech:
Agent Platform User (
roles/aiplatform.user)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Create a remixed voice
Set the following fields in the request:
store: Must betrue. Remixed voices are always stored in your project. Requests that setbase_voicewithstore: falsefail with anINVALID_ARGUMENTerror.voice.type:VOICE_TYPE_PROMPTED.voice.prompted.base_voice: The voice to remix. Use the voice name for a prebuilt voice (for example,Puck), the voice ID for an Extended Voice Library voice, or thevoice_...ID for a designed or remixed voice. If the voice doesn't exist, the request fails with aNOT_FOUNDerror.voice.prompted.input: A natural-language description of the changes to make to the base voice.voice.display_name,voice.gender,voice.language_code: Optional metadata for the new voice.
Don't set voice.model. Requests that set a model together with
store: true fail with an INVALID_ARGUMENT error.
Remixing a voice can take several seconds. The Python sample sets the request timeout to 60 seconds.
The response contains the following fields:
id: The ID of the new voice.prompted.base_voice: The base voice that you remixed.sample_audio: A sample of the new voice. Thedatafield holds the base64-encoded audio, and themime_typefield names its encoding. By default, the sample is a complete WAV file (audio/wav) with a RIFF header: 16-bit PCM, 24 kHz, mono. Some voices can return headerless 16-bit PCM (audio/l16; rate=24000; channels=1) instead, so checkmime_typebefore you save the audio.usage: The number of tokens that the request used. For more information, see Pricing.
The following samples remix the prebuilt Puck voice:
Python
Install
pip install --upgrade google-genai
To learn more, see the SDK reference documentation.
Set environment variables to use the Google Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
import base64 import wavefrom google import genai
client = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
voice = client.voices.create( store=True, voice={ "type": "VOICE_TYPE_PROMPTED", "display_name": "Older British Puck", "prompted": { "base_voice": "Puck", "input": ( "Make the voice sound slightly older and more grounded, with a" " warm British accent and measured audiobook narration pacing." ), }, }, timeout=60, )
print(f"Created voice ID: {voice.id}")
Save the voice sample. The SDK returns sample_audio.data as a base64
string. By default, it's a complete WAV file (audio/wav). For
compatibility, add a WAV header if the sample is raw 16-bit PCM
(audio/l16).
sample = base64.b64decode(voice.sample_audio.data) if voice.sample_audio.mime_type.lower().startswith("audio/l16"): with wave.open("remixed_voice_sample.wav", "wb") as wf: wf.setnchannels(1) wf.setsampwidth(2) wf.setframerate(24000) wf.writeframes(sample) else: with open("remixed_voice_sample.wav", "wb") as f: f.write(sample)
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
HTTP method and URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
Request JSON body:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"displayName": "Older British Puck",
"prompted": {
"baseVoice": "Puck",
"input": "Make the voice sound slightly older and more grounded, with a warm British accent and measured audiobook narration pacing."
}
}
}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
Save the request body in a file named request.json,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
You should receive a JSON response similar to the following. The sample_audio.data field is truncated.
{
"id": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124",
"prompted": {
"base_voice": "Puck"
},
"usage": {
"total_tokens": 578,
"total_input_tokens": 297,
"input_tokens_by_modality": [
{"modality": "text", "tokens": 38},
{"modality": "audio", "tokens": 259}
],
"total_output_tokens": 281,
"output_tokens_by_modality": [
{"modality": "audio", "tokens": 281}
]
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRpTwAwBXQVZF..."
}
}
By default, sample_audio.mime_type is audio/wav, and
sample_audio.data holds a base64-encoded, complete WAV file. If
mime_type is audio/l16, the decoded data is headerless
16-bit PCM audio at 24 kHz, mono, and needs a WAV header before most players
can open it.
Generate speech with a remixed voice
Pass the voice ID in speechConfig.voiceConfig.voice, the same way that you
pass a designed voice:
Python
Install
pip install --upgrade google-genai
To learn more, see the SDK reference documentation.
Set environment variables to use the Google Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
from google import genaiclient = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
response = client.models.generate_content( model="gemini-3.8-flash-tts", contents=[{ "role": "user", "parts": [{ "text": "Chapter One. The fog rolled quietly across the harbor at dawn.", "speech_metadata": {"style": "calm and reflective"}, }], }], config={ "response_modalities": ["AUDIO"], "speech_config": {"voice_config": {"voice": "VOICE_ID"}}, }, )
The SDK has already decoded the base64 audio, so inline_data.data is a
complete WAV file by default.
with open("remixed_voice.wav", "wb") as f: f.write(response.candidates[0].content.parts[0].inline_data.data)
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- VOICE_ID: The voice ID that the Voices API
createmethod returned.
HTTP method and URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent
Request JSON body:
{
"contents": [{
"role": "user",
"parts": [{
"text": "Chapter One. The fog rolled quietly across the harbor at dawn.",
"speechMetadata": {"style": "calm and reflective"}
}]
}],
"generationConfig": {
"responseModalities": ["AUDIO"],
"speechConfig": {
"voiceConfig": {"voice": "VOICE_ID"}
}
}
}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent"
PowerShell
Save the request body in a file named request.json,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.8-flash-tts:generateContent" | Select-Object -Expand Content
The response contains the audio as a base64-encoded, complete WAV file in candidates[0].content.parts[0].inlineData.data. The data field is truncated.
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"inlineData": {
"mimeType": "audio/wav",
"data": "UklGRhRlBABXQVZF..."
}
}
]
},
"finishReason": "STOP"
}
]
}
In the Python sample, replace PROJECT_ID with your Google Cloud
project ID and VOICE_ID with the voice ID that the create method
returned.
Refine a voice step by step
Each remixed voice is a stored voice_... voice, so you can use it as the base
voice of another remix. This step-by-step workflow lets you change one or two
traits at a time and listen to each result before you make the next change. You can also start from
a designed voice.
The following samples remix an existing designed or remixed voice:
Python
Install
pip install --upgrade google-genai
To learn more, see the SDK reference documentation.
Set environment variables to use the Google Gen AI SDK with Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
from google import genaiclient = genai.Client(enterprise=True, project="PROJECT_ID", location="global")
voice = client.voices.create( store=True, voice={ "type": "VOICE_TYPE_PROMPTED", "prompted": { "base_voice": "BASE_VOICE_ID", "input": ( "Keep the same speaker identity and accent, but make the" " delivery calmer, softer, and slightly lower in pitch." ), }, }, timeout=60, )
print(f"Created voice ID: {voice.id}") print(f"Remixed from: {voice.prompted.base_voice}")
REST
Before using any of the request data, make the following replacements:
- PROJECT_ID: Your Google Cloud project ID.
- BASE_VOICE_ID: The
voice_...ID of a designed or remixed voice in your project.
HTTP method and URL:
POST https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices
Request JSON body:
{
"store": true,
"voice": {
"type": "VOICE_TYPE_PROMPTED",
"prompted": {
"baseVoice": "BASE_VOICE_ID",
"input": "Keep the same speaker identity and accent, but make the delivery calmer, softer, and slightly lower in pitch."
}
}
}
To send your request, choose one of these options:
curl
Save the request body in a file named request.json,
and execute the following command:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices"
PowerShell
Save the request body in a file named request.json,
and execute the following command:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/global/voices" | Select-Object -Expand Content
You should receive a JSON response similar to the following. The sample_audio.data field is truncated.
{
"id": "voice_f70c942e-7d78-427d-8466-cae3cb9b0371",
"prompted": {
"base_voice": "voice_7bd85ebf-761b-4969-8544-4ec60f06d124"
},
"sample_audio": {
"mime_type": "audio/wav",
"data": "UklGRhT4AgBXQVZF..."
}
}
In the Python sample, replace BASE_VOICE_ID with the voice_... ID
of a designed or remixed voice in your project.
Manage remixed voices
Remixed voices are stored in your project with the type VOICE_TYPE_PROMPTED,
the same type as designed voices. To list, get, or delete remixed voices, use
the same methods as for designed voices. For details, see
Manage stored voices.
A remixed voice is independent of its base voice:
- Remixing never changes the base voice.
- Deleting the base voice doesn't affect voices that were remixed from it.
Limits
- Stored voices expire one year after they were last used. Generating speech
with a voice, or using it as the
base_voiceof a remix, restarts this period. Delete voices that you no longer need. - Remix requests count toward the same per-project, per-minute voice creation
quota as voice design and voice replication. If you exceed it, the
createmethod returns aRESOURCE_EXHAUSTEDerror. Wait and retry. For more information, see Quotas and system limits.
Pricing
Remixing a voice is billed at the Gemini 3.8 Flash TTS rates for the following tokens:
- Text input tokens for the description in
voice.prompted.input. - Audio input tokens for the base voice audio.
- Audio output tokens for the voice sample that the Voices API generates.
The usage field in the create response reports each count. For example, the
remix in the create sample uses about 40 text input tokens, about
260 audio input tokens, and about 280 audio output tokens.
The get, list, and delete methods aren't billed. Speech that you generate
with a remixed voice is billed at the rates of the model that you call.
For token rates, see Gemini Enterprise pricing.
Prompting best practices
- Describe only the changes: The model keeps the sound of the base voice, so describe only the traits to change, such as age, timbre, pitch, pacing, or energy. Don't repeat the full description of the voice.
- State a new language or accent explicitly: A remix keeps the language
and regional accent of the base voice unless
voice.prompted.inputasks for a different one. - Change one or two traits per step: When you refine a voice over
several remixes, change a small set of traits in each request, and listen
to the
sample_audiobefore you make the next change. - Use remixing for permanent traits and
speech_metadata.stylefor each turn: Use voice remixing to change the baseline of a voice, such as its age, accent, pitch, or persona. Use shortspeech_metadata.stylevalues, such as"whispered urgently"or"excited", to direct the delivery of individual turns.
The following table shows example remix requests:
| Goal | base_voice |
prompted.input |
|---|---|---|
| Change age and timbre | Puck |
Make the voice sound 20 years older with a deeper, slightly
gravelly baritone timbre while keeping the friendly warmth. |
| Change regional accent | Kore |
Change the accent to Australian English while preserving the
clear, confident studio delivery. |
| Adapt to a domain | A designed voice (voice_...) |
Adapt this voice for late-night meditation narration: lower the
vocal projection, slow the pacing, and soften the tone. |
| Increase energy | A remixed voice (voice_...) |
Increase vocal energy and projection so the speaker sounds like
an upbeat live event announcer. |
What's next
- Create a custom voice from a text description with voice design.
- Replicate an existing speaker's voice with voice replication.
- Learn about turn-level styling, inline tags, and multi-speaker dialogue in Generate speech with Gemini TTS.