2026-10-20 · every Google voice tier, what each can do, and which settings matter. Ratings and notes save in this browser; tap Copy results when done and paste them back to me.
Two voices per tier, all saying: “Okay, I looked into it. The short answer is yes, but there's a catch: the cheaper plan drops the offline mode, and honestly, that's the part you'd miss. Want me to compare the two?” “Ready in” is the time for the whole clip from our server (a call starts speaking sooner, sentence by sentence). ≈/mo is the estimate for your last 30 days of speech; * = worst case, the free 4M pool is shared with the podcasts.
Same line, every 3.8 voice (Flash-Lite uses the same 30 names). Mark the ones you like; “Love” = shortlist.
These were checked only by length and status code, not by ear. Tell me whether each one actually did what it says.
These were checked only by length and status code, not by ear. Tell me whether each one actually did what it says.
These were checked only by length and status code, not by ear. Tell me whether each one actually did what it says.
These were checked only by length and status code, not by ear. Tell me whether each one actually did what it says.
3.8 rejects a speed setting, so the shim would stretch the audio after Google returns it. These are the 3.8 Flash “Kore” clip above, stretched on our server. The page-wide speed slider at the bottom does the same thing in your browser (pitch kept) — the app could do it on playback instead.
Today the app sends Google four things: the text, the voice, the audio format and a speed. Everything below is unused so far. In rough order of payoff for Calliope:
speechMetadata.style): a short phrase like “warm, relaxed, a little wry” sent with each reply. It costs about 3 text tokens, effectively free. Google warns that long or changing style text makes the voice drift, so I'd keep it short and fixed per voice.<laugh> <sigh> <short pause> <whispers> and about 40 more, plus CAPITALS for emphasis. The idea: when a 3.8 voice is picked, Calliope's prompt tells her she may use them, and she directs her own delivery.style, never in the text.Yes, asking 3.8 to speak faster lowers the bill. Google bills exactly 25 audio tokens per second of speech; we checked the billed count on every call:
| 3.8 Flash-Lite, same 2 sentences | Audio | Billed audio tokens | Cost per reply |
|---|---|---|---|
| No style | 6.8 s | 169–171 | $0.00103 |
| “speaking rapidly” | 4.5–4.9 s | 113–123 | $0.00069–0.00075 (−28 to −33%) |
| “speaking quickly but clearly” | 4.7–5.2 s | 118–129 | $0.00072–0.00079 (−24 to −30%) |
Today each sentence is synthesized in full before it plays. Streaming starts playing while Google is still generating. It's available for 3.8 (streamGenerateContent, raw audio chunks) and for Chirp 3 HD / Gemini 2.5–3.1 (Cloud TTS streaming, gRPC only). This is the biggest latency lever on the list, and the biggest build too: a new code path in the shim. Note: no SSML in streaming mode.
Describe a voice in a paragraph; Google returns a reusable voice ID. A test voice was created, used and deleted fine (clip above). It replaces the 30 shared presets with one persona that stays consistent across replies. IDs are kept for a year after last use. There's also a 2,000-voice library with accent and persona tags, if we want a browsable picker beyond the 30.
[pause long] only works in the separate markup field. Sent as plain text, as we do today, it seems to be read out (clip above).<say-as> for dates, numbers and phone numbers; <sub> to say “Doctor” for “Dr.”. Useful on the cheap tiers; moot on Gemini, which already reads naturally.Volume gain and device profiles (handset, headphones, telephony EQ) are cheap one-field wins on the classic tiers. Unverified on Chirp 3 and Gemini. 8 kHz μ-law/A-law output exists on every API if Calliope ever answers real phone calls; 3.8 can return it directly, skipping our conversion.
<mark> + time-pointing returns the exact moment each marked word is spoken, which is what you'd need to highlight text in sync or drive the orb from words. It works only on Neural2/WaveNet; Chirp 3 returns nothing and Gemini has no such feature. Not worth choosing a voice for.
Gender (ignored once a voice is named) · long-audio synthesis (async to a storage bucket, not real-time) · safety-filter settings (off by default; one is deprecated) · language code on 3.8 (auto-detected) · temperature/top-p on 3.8 (rejected) · voice cloning (needs a consent recording) · custom-voice fields (enterprise-only).
(a) 3.8 style + tags, with the transcript stripping them. (b) A Pace setting that uses style on 3.8 and the native speed elsewhere. (c) Log the billed tokens 3.8 reports into the new usage page, so Gemini voice costs are exact rather than estimated. Streaming and a designed voice come after you've rated the clips.
Per tier: live we tried it and it worked · doc documented, not tried · rejected Google refused it.
POST https://texttospeech.googleapis.com/v1/text:synthesize · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
input.textstring | The raw text to be synthesized. Plain text. Whole request limit 5000 bytes (Gemini: text<=4000 B and prompt<=4000 B, sum<=8000 B). Exactly one of text/ssml/markup/multiSpeakerMarkup. | yes | live | live | live | live | live | live | live | n/a |
input.ssmlstring | The SSML document to be synthesized. The SSML document must be valid and well-formed. Otherwise the RPC will fail and return google.rpc.Code.INVALID_ARGUMENT. For more information, see [SSML](https://cloud.google.com/text-to-speech/docs/ssml). LIVE: Chirp-HD -> HTTP 400; Chirp 3 HD honors <break> (preview, sync only, not in streaming). Studio drops <mark>,<emphasis>,<prosody pitch>,<lang>. Shim sends text, so SSML would be read literally. Gemini: no SSML documented. | no | doc | live | live | live | rejected | live | unknown | n/a |
input.markupstring | Markup for Chirp 3: HD voices specifically. This field may not be used with any other voices. Chirp 3 HD only: pause tags [pause], [pause short], [pause long] work ONLY here, not in text (live: markup 3.98 s vs text 4.54 s, text path appears to read tag aloud). | no | rejected | rejected | rejected | rejected | rejected | live | rejected | n/a |
input.promptstring | This system instruction is supported only for controllable/promptable voice models. If this system instruction is used, we pass the unedited text to Gemini-TTS. Otherwise, a default system instruction is used. AI Studio calls this system instruction, Style Instructions. Gemini style instruction, <=4000 bytes. Not used by 3.8 (use speechMetadata.style). | no | n/a | n/a | n/a | n/a | n/a | n/a | live | n/a |
input.customPronunciations.pronunciations[]array<CustomPronunciationParams> | The pronunciation customizations are applied. Per-phrase IPA/X-SAMPA/Yomigana/Pinyin override; en-US first, many locales excluded for Chirp3 (see chirp3-hd doc). Instant-clone voices unsupported. Phrase must match exactly; use unique tokens (read1/read2) to disambiguate. | no | unknown | unknown | unknown | unknown | unknown | live | unknown | n/a |
input.customPronunciations.pronunciations[].phrasestring | The phrase to which the customization is applied. The phrase can be multiple words, such as proper nouns, but shouldn't span the length of the sentence. | no | unknown | unknown | unknown | unknown | unknown | live | unknown | n/a |
input.customPronunciations.pronunciations[].phoneticEncodingstring | The phonetic encoding of the phrase. Values: PHONETIC_ENCODING_UNSPECIFIED, PHONETIC_ENCODING_IPA, PHONETIC_ENCODING_X_SAMPA, PHONETIC_ENCODING_JAPANESE_YOMIGANA, PHONETIC_ENCODING_PINYIN | no | unknown | unknown | unknown | unknown | unknown | live | unknown | n/a |
input.customPronunciations.pronunciations[].pronunciationstring | The pronunciation of the phrase. This must be in the phonetic encoding specified above. | no | unknown | unknown | unknown | unknown | unknown | live | unknown | n/a |
input.multiSpeakerMarkup.turns[]array<Turn> | Required. Speaker turns. Structured dialogue: turns[{speaker,text}]; speakers must match voice.multiSpeakerVoiceConfig aliases (Gemini) or Studio multispeaker names (e.g. R,S,T,U). | no | n/a | n/a | n/a | doc | n/a | n/a | doc | n/a |
voice.languageCodestring | Required. The language (and potentially also the region) of the voice expressed as a [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tag, e.g. "en-US". This should not include a script tag (e.g. use "cmn-cn" rather than "cmn-Hant-cn"), because the script will be inferred from the input provided in the SynthesisInput. The TTS service will use this parameter to help choose an appropriate voice. Note tha Shim derives it from the voice name (first two hyphen segments); Gemini uses DEFAULT_LANGUAGE en-US. | yes | live | live | live | live | live | live | live | n/a |
voice.namestring | The name of the voice. If both the name and the gender are not set, the service will choose a voice based on the other parameters such as language_code. Classic: en-US-Wavenet-D etc. Chirp3: en-US-Chirp3-HD-Kore. Gemini: bare speaker (Kore) + modelName. | yes | live | live | live | live | live | live | live | n/a |
voice.modelNamestring | Optional. The name of the model. If set, the service will choose the model matching the specified configuration. Gemini model id: gemini-2.5-flash-tts, gemini-2.5-flash-lite-preview-tts, gemini-2.5-pro-tts, gemini-3.1-flash-tts-preview. | yes | n/a | n/a | n/a | n/a | n/a | n/a | live | n/a |
voice.ssmlGenderstring | The preferred gender of the voice. If not set, the service will choose a voice based on the other parameters such as language_code and name. Note that this is only a preference, not requirement; if a voice of the appropriate gender is not available, the synthesizer should substitute a voice with a different gender rather than failing the request. Values: SSML_VOICE_GENDER_UNSPECIFIED, MALE, FEMALE, NEUTRAL Preference only; ignored when name is set. NEUTRAL not yet supported. | no | doc | doc | doc | doc | doc | doc | doc | n/a |
voice.customVoice.modelstring | Required. The name of the AutoML model that synthesizes the custom voice. AutoML Custom Voice resource; not in our tiers. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | n/a |
voice.customVoice.reportedUsagestring | Optional. Deprecated. The usage of the synthesized audio to be reported. Values: REPORTED_USAGE_UNSPECIFIED, REALTIME, OFFLINE Deprecated. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | n/a |
voice.voiceClone.voiceCloningKeystring | Required. Created by GenerateVoiceCloningKey. Chirp 3 HD Instant Custom Voice key (GenerateVoiceCloningKey, allowlisted access). Not tested. 3.8 has its own voice replication. | no | n/a | n/a | n/a | n/a | n/a | unknown | n/a | n/a |
voice.multiSpeakerVoiceConfig.speakerVoiceConfigs[]array<MultispeakerPrebuiltVoice> | Required. A list of configurations for the voices of the speakers. Exactly two speaker voice configurations must be provided. Exactly two [{speakerAlias,speakerId}]. | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
audioConfig.audioEncodingstring | Required. The format of the audio byte stream. Values: AUDIO_ENCODING_UNSPECIFIED, LINEAR16, MP3, MP3_64_KBPS, OGG_OPUS, MULAW, ALAW, PCM, M4A Shim sends MP3, LINEAR16, OGG_OPUS. LIVE: v1 rejected MP3_64_KBPS (400, enum invalid in v1); M4A returned HTTP 200 on WaveNet (decode not checked). Chirp3: ALAW unsupported (doc); streaming supports only PCM/ALAW/MULAW/OGG_OPUS. Gemini unary: LINEAR16,ALAW,MULAW,MP3,OGG_OPUS,PCM. Enum descriptions: MP3=32kbps, MP3_64_KBPS=64kbps, LINEAR16 has WAV header, PCM headerless, MULAW/ALAW 8-bit G.711 with WAV header. | yes | live | live | live | live | live | live | live | n/a |
audioConfig.speakingRatenumber(double) | Optional. Input only. Speaking rate/speed, in the range [0.25, 2.0]. 1.0 is the normal native speed supported by the specific voice. 2.0 is twice as fast, and 0.5 is half as fast. If unset(0.0), defaults to the native 1.0 speed. Any other values < 0.25 or > 2.0 will return an error. Values: 1.0 Default: Range 0.25-4.0 for classic voices per older docs; discovery text says [0.25, 2.0] (cap) while the shim clamps to 4.0. Chirp3 pace 0.25-2.0. LIVE: Chirp-HD 3.86->2.69 s @1.5, Chirp3 4.49->2.71, Gemini2.5 3.98->2.64. Shim clamps 0.25-4.0 - clamp to 2.0 for Chirp3/Gemini. | yes | doc | live | doc | doc | live | live | live | n/a |
audioConfig.pitchnumber(double) | Optional. Input only. Speaking pitch, in the range [-20.0, 20.0]. 20 means increase 20 semitones from the original pitch. -20 means decrease 20 semitones from the original pitch. Semitones -20..+20. Chirp3 -> HTTP 400 'does not support pitch'. LIVE accepted (HTTP 200) on Gemini 2.5 and Studio but audible effect not verified. | no | doc | doc | doc | doc | unknown | rejected | live | n/a |
audioConfig.volumeGainDbnumber(double) | Optional. Input only. Volume gain (in dB) of the normal native volume supported by the specific voice, in the range [-96.0, 16.0]. If unset, or set to a value of 0.0 (dB), will play at normal native signal amplitude. A value of -6.0 (dB) will play at approximately half the amplitude of the normal native signal amplitude. A value of +6.0 (dB) will play at approximately twice the amplitude of the normal native signal a -96..+16 dB; >+10 no benefit. Accepted live on Chirp3 and Gemini2.5; effect not measured. Cheap loudness normalization for phone speaker. | no | doc | live | doc | doc | unknown | live | live | n/a |
audioConfig.sampleRateHertzinteger(int32) | Optional. The synthesis sample rate (in hertz) for this audio. When this is specified in SynthesizeSpeechRequest, if this is different from the voice's natural sample rate, then the synthesizer will honor this request by converting to the desired sample rate (which might result in worse audio quality), unless the specified sample rate is not supported for the encoding chosen, in which case it will fail the request an Resamples from natural rate (Chirp3 LINEAR16 16 kHz returned HTTP 200). Unsupported rate for the encoding -> 400. | no | doc | doc | doc | doc | doc | live | unknown | n/a |
audioConfig.effectsProfileId[]array<string> | Optional. Input only. An identifier which selects 'audio effects' profiles that are applied on (post synthesized) text to speech. Effects are applied on top of each other in the order they are given. See [audio profiles](https://cloud.google.com/text-to-speech/docs/audio-profiles) for current supported profile ids. Values: wearable-class-device, handset-class-device, headphone-class-device, small-bluetooth-speaker-class-device, medium-bluetooth-speaker-class-device, large-home-entertainment-class-device, large-automotive-class-device, telephony-class-application Post-synthesis EQ chain applied in given order; do not repeat a profile. | no | doc | live | doc | doc | doc | unknown | unknown | n/a |
advancedVoiceOptions.enableTextnormboolean | Optional. If true, textnorm will be applied to text input. This feature is enabled by default. Only applies for Gemini TTS. Default: true Gemini only; text normalization (numbers/dates) on by default. LIVE: false accepted. | no | n/a | n/a | n/a | n/a | n/a | n/a | live | n/a |
advancedVoiceOptions.safetySettings.settings[].categorystring | The harm category to apply the safety setting to. Values: HARM_CATEGORY_UNSPECIFIED, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_SEXUALLY_EXPLICIT Gemini TTS only. If no settings, filters are OFF by default. | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
advancedVoiceOptions.safetySettings.settings[].thresholdstring | The harm block threshold for the safety setting. Values: HARM_BLOCK_THRESHOLD_UNSPECIFIED, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH, BLOCK_NONE, OFF | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
advancedVoiceOptions.relaxSafetyFiltersboolean | Optional. Input only. Deprecated, use safety_settings instead. If true, relaxes safety filters for Gemini TTS. Deprecated -> use safetySettings. | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
advancedVoiceOptions.lowLatencyJourneySynthesisboolean | Only for Journey voices. If false, the synthesis is context aware and has a higher latency. Journey voices only; none in our tiers. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | n/a |
audioContentstring(byte) | Base64 audio in the requested encoding (LINEAR16/OGG/MP3 include container header). No usage/token info in the response. | yes | live | live | live | live | live | live | live | n/a |
POST https://texttospeech.googleapis.com/v1beta1/text:synthesize · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
enableTimePointing[]array<string> | Whether and what timepoints are returned in the response. Values: TIMEPOINT_TYPE_UNSPECIFIED, SSML_MARK Only SSML_MARK: returns timepoints for <mark name=.../> tags (word/sentence sync, captions, orb). LIVE Neural2: marks at 0.37 s and 0.84 s. Chirp3: request accepted but timepoints empty. Studio drops <mark>. Requires /v1beta1 endpoint. [v1beta1 only] | no | doc | doc | live | rejected | unknown | rejected | unknown | n/a |
timepoints[]array<Timepoint{markName,timeSeconds}> | Mark times (v1beta1 only). | no | doc | doc | live | doc | doc | rejected | doc | n/a |
audioConfig (response)AudioConfig | Echo of the audio metadata (v1beta1 only). | no | doc | doc | doc | doc | doc | doc | doc | n/a |
gRPC google.cloud.texttospeech.v1.TextToSpeech/StreamingSynthesize (global/us/eu endpoints) · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
streaming_config.voiceVoiceSelectionParams | Required; same as unary voice. | no | n/a | n/a | n/a | n/a | n/a | doc | doc | n/a |
streaming_config.streaming_audio_config.audio_encodingenum | Required. All other encodings error. Values: PCM, ALAW, MULAW, OGG_OPUS Chirp3 ALAW unsupported per voice docs. | no | n/a | n/a | n/a | n/a | n/a | doc | doc | n/a |
streaming_config.streaming_audio_config.sample_rate_hertzint32 | Optional output rate. | no | n/a | n/a | n/a | n/a | n/a | doc | doc | n/a |
streaming_config.streaming_audio_config.speaking_ratedouble | Pace; no pitch/volume in streaming config. Values: 0.25-2.0 Default: 1.0 | no | n/a | n/a | n/a | n/a | n/a | doc | doc | n/a |
streaming_config.custom_pronunciationsCustomPronunciations | Same as unary; en-US first. | no | n/a | n/a | n/a | n/a | n/a | doc | n/a | n/a |
streaming_config.advanced_voice_optionsAdvancedVoiceOptions | Gemini safety/textnorm. | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
input.textstring | Chunk of text; send complete sentences for better prosody. | no | n/a | n/a | n/a | n/a | n/a | doc | doc | n/a |
input.markupstring | Chirp 3 HD pause markup. | no | n/a | n/a | n/a | n/a | n/a | doc | n/a | n/a |
input.multi_speaker_markupMultiSpeakerMarkup | Gemini multi-speaker. | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
input.promptstring | Gemini style instruction (in the first input chunk). | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | n/a |
response.audio_contentbytes | Headerless LINEAR16 24 kHz chunks. | no | n/a | n/a | n/a | n/a | n/a | doc | doc | n/a |
POST https://texttospeech.googleapis.com/v1/{parent=projects/*/locations/*}:synthesizeLongAudio ; poll GET v1/{name=projects/*/locations/*/operations/*} · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
parent (path)string | projects/*/locations/* (docs example uses locations/global on v1beta1 and us-central1). | no | unknown | unknown | unknown | unknown | unknown | unknown | unknown | n/a |
inputSynthesisInput | Text or SSML, up to ~1 MB. | no | unknown | unknown | unknown | unknown | unknown | unknown | unknown | n/a |
voiceobject | Required. The desired voice of the synthesized audio. | no | unknown | unknown | unknown | unknown | unknown | unknown | unknown | n/a |
audioConfigobject | Required. The configuration of the synthesized audio. Docs example LINEAR16. | no | unknown | unknown | unknown | unknown | unknown | unknown | unknown | n/a |
outputGcsUristring | Required. Specifies a Cloud Storage URI for the synthesis results. Must be specified in the format: `gs://bucket_name/object_name`, and the bucket must already exist. gs://bucket/object; bucket must exist. | no | unknown | unknown | unknown | unknown | unknown | unknown | unknown | n/a |
operations.get/list/cancel/deleteREST | Long-running operation management (poll progressPercentage in metadata). | no | unknown | unknown | unknown | unknown | unknown | unknown | unknown | n/a |
GET https://texttospeech.googleapis.com/v1/voices?languageCode=en-US · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
languageCode (query)string | BCP-47 filter; 'no' also returns nb-*. Default: all voices | yes | doc | doc | doc | doc | doc | doc | doc | n/a |
voices[].namestring | The name of this voice. Each distinct voice has a unique name. | yes | doc | doc | doc | doc | doc | doc | doc | n/a |
voices[].languageCodes[]array<string> | The languages that this voice supports, expressed as [BCP-47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt) language tags (e.g. "en-US", "es-419", "cmn-tw"). | yes | doc | doc | doc | doc | doc | doc | doc | n/a |
voices[].ssmlGenderstring | The gender of this voice. Values: SSML_VOICE_GENDER_UNSPECIFIED, MALE, FEMALE, NEUTRAL | no | doc | doc | doc | doc | doc | doc | doc | n/a |
voices[].naturalSampleRateHertzinteger(int32) | The natural sample rate (in hertz) for this voice. Chirp3/Gemini 24000; classic 24000 (WaveNet/Neural2) or 22050 (Standard). | no | doc | doc | doc | doc | doc | doc | doc | n/a |
POST/GET/DELETE https://aiplatform.googleapis.com/v1beta1/projects/{p}/locations/global/voices[:create|:list|:get|:delete] · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
storeboolean | true: Google stores and returns voice_<id> (1 yr after last use, per-project quota). false: returns client-held voicekey_ (7 days). prompted voices REQUIRE store=true. Values: True, False Default: false | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.promptedobject | Parameters for prompted voice generation. Required in `CreateVoice` when `type` is `"prompted"`. Returned in `CreateVoice`, `GetVoice`, and `ListVoices` responses for prompted voices. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.sampleAudioobject | 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. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.typestring | Required. The type of the voice. In `CreateVoice`, must be `"replicated"` or `"prompted"`. In `ListVoices` responses, may also be `"prebuilt"`. Values: VOICE_TYPE_UNSPECIFIED, VOICE_TYPE_REPLICATED, VOICE_TYPE_PROMPTED, VOICE_TYPE_PREBUILT | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.descriptionstring | Optional. Descriptive summary of vocal timbre, personality, and tone. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.pitchstring | Optional. Voice pitch classification. Values: PITCH_UNSPECIFIED, PITCH_LOW, PITCH_MEDIUM, PITCH_HIGH | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.expireTimestring(google-datetime) | 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. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.usageobject | 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. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.personastring | Optional. Intended persona or character archetype (e.g. "Warm, Friendly", "Narrator"). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.accentstring | Optional. Regional accent descriptor (e.g. "American", "British"). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.modelstring | 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 | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.languageCodestring | Optional. Primary BCP-47 language tag (e.g. "en-US", "fr-FR"). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.genderstring | Optional. Perceived voice gender presentation (e.g. "female", "male", "neutral"). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.replicatedobject | Input only. Parameters for replicated voice generation. Required on input when `type` is `"replicated"`. Not returned in responses. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.keystring | 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. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.idstring | 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 | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.regionCodestring | Optional. ISO 3166-1 alpha-2 or UN M.49 geographic region code (e.g. "US", "GB", "001"). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.displayNamestring | Optional. User-provided display name for a stored voice (`store = true`), or the catalog name for a prebuilt voice. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.contextstring | Optional. Optimal usage context or domain (e.g. "Conversational", "Audiobook", "News"). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.prompted.inputstring | Required for VOICE_TYPE_PROMPTED: natural-language persona (age, timbre, accent, delivery). Designing takes several seconds (60 s timeout). LIVE: create+synthesize+delete worked with store=true, display_name, gender, language_code, prompted.input | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
voice.replicated.sourceAudio / consentAudioAudioData | 10-30 s adult reference + consent-phrase recording. DOC only; not run. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
list query: pageToken,pageSize(<=50),search,type(prebuilt|prompted|replicated),gender,pitch,persona,context,accent,regionCode,languageCodequery | Browse 2000+ Extended Library voices + own voices. Doc says language_code/gender filters fail with INVALID_ARGUMENT; discovery lists them. LIVE: search=narrator and search='conversational agent' worked. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
POST https://aiplatform.googleapis.com/v1/projects/{p}/locations/global/publishers/google/models/{model}:generateContent · docs
| Field | What it does | App sends it today | Standard | WaveNet | Neural2 | Studio | Chirp HD | Chirp 3 HD | Gemini 2.5/3.1 | Gemini 3.8 |
|---|---|---|---|---|---|---|---|---|---|---|
contents[].rolestring | Turn role. Values: user | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
contents[].parts[].textstring | Verbatim transcript. Instructions in text may be spoken aloud. Angle-bracket tags: <sigh> <laugh> <cough> <gasp> <breath> <short pause> <long pause> <whispers> and ~35 more. CAPS = emphasis. |word| = backchannel/overlap (multi-speaker). Shim sends text only. Gemini 2.5/3.1 on Vertex take style/tags inside the text itself, with [tag] syntax. | yes | n/a | n/a | n/a | n/a | n/a | n/a | doc | live |
contents[].parts[].speechMetadata.stylestring | Turn-level delivery: emotion, pace, volume (e.g. 'whispering softly', 'speaking rapidly'). Keep short and constant; 'speaking rapidly' cut audio 33% live. Default: empty Billed as input text tokens (+2 to +4 tokens). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
contents[].parts[].speechMetadata.speakerstring | Speaker name per turn; must match a speakerVoiceConfigs speaker. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
generationConfig.responseModalities[]array<string> | Must include AUDIO. Values: AUDIO | yes | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
generationConfig.speechConfig.voiceConfig.voicestring | Prebuilt speaker (Kore), Extended Library id, designed voice_..., or voicekey_... Shim forwards the Speaker name only. | yes | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
generationConfig.speechConfig.voiceConfig.prebuiltVoiceConfig.voiceNamestring | Older spelling; still works for prebuilt. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
generationConfig.speechConfig.voiceConfig.replicatedVoiceConfigobject | Inline reference audio; NOT supported on 3.8 (use Voices API). | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | rejected |
generationConfig.speechConfig.languageCodestring | Optional hint; 3.8 auto-detects (Flash 130 languages, Flash-Lite 101). Default: auto-detected | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |
generationConfig.speechConfig.multiSpeakerVoiceConfig.speakerVoiceConfigs[]array | Exactly two {speaker, voiceConfig.voice}. Mutually exclusive with voiceConfig. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
generationConfig.speechConfig.speakingRatedouble | Does not exist in 3.8 schema. LIVE: HTTP 400 Unknown name speakingRate. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | rejected |
generationConfig.responseFormat[].audio.mimeTypeenum | Output encoding. Schema lists MP3 and OGG_OPUS but docs say unsupported: LIVE AUDIO_MP3 (+bitRate) -> HTTP 400. MULAW/ALAW come back 8 kHz raw (LIVE MULAW ok, no WAV header). Values: AUDIO_WAV, AUDIO_L16, AUDIO_MULAW, AUDIO_ALAW, AUDIO_MP3, AUDIO_OGG_OPUS Default: AUDIO_WAV unary / AUDIO_L16 streaming Shim transcodes WAV->MP3 itself. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
generationConfig.responseFormat[].audio.sampleRateint32 | Ignored by 3.8: LIVE sampleRate=16000 still returned a 24 kHz WAV. Default: 24000 | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | rejected |
generationConfig.responseFormat[].audio.bitRateint32 | Compressed formats only; moot since MP3/Opus unsupported. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | rejected |
generationConfig.responseFormat[].audio.deliveryenum | Inline base64 vs URI delivery. Values: INLINE, URI, DELIVERY_UNSPECIFIED Default: INLINE | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | unknown |
generationConfig.temperature / topP / topK / candidateCount / seed / stopSequences ...various | Rejected with INVALID_ARGUMENT on 3.8 (doc). Ignored on 2.5/3.1. | no | n/a | n/a | n/a | n/a | n/a | n/a | doc | rejected |
systemInstructionContent | Rejected on 3.8; put persona in Voices API instead. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | rejected |
response.candidates[0].content.parts[0].inlineData{data,mimeType}object | Base64 WAV (unary). Shim decodes WAV or audio/L16. | yes | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
response.usageMetadata.{promptTokenCount,candidatesTokenCount,candidatesTokensDetails[AUDIO],promptTokensDetails[TEXT]}object | Billing basis. Audio output = 25 tokens per second of audio (measured 25.0). LIVE present on 3.8; absent on Cloud TTS. Shim could log it for exact cost. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | live |
streamGenerateContent?alt=ssemethod | Streams raw L16 24 kHz chunks; first-audio latency win. | no | n/a | n/a | n/a | n/a | n/a | n/a | n/a | doc |