Voices

Gemini 3.8 TTS routes advertise request_constraints.audio_outputs.voiceCreation, sharedVoices, styleDirection and expressive when enabled. Voice creation uses the Google API style, independently of the API style used for subsequent speech synthesis.

Browse voices

Call GET /v1/voices?model=google/gemini-3.8-flash-tts&search=warm (provider-neutral) or the equivalent GET /v1/google/voices. Both return the same shape:

• voices: the provider's prebuilt library page.
• custom_voices: voices created by the active Cloud project and tenant only.
• shared_voices: enabled platform voices compatible with the model. Empty unless the model advertises sharedVoices.
• next_page_token: pass it as page_token without changing the search. It pages voices only.

search filters all three lists. The playground provides search, pagination and voice cards grouped as your voices, Shared and Library.

The request requires ai:read, an enabled AI product and model policy access. Google credentials stay on the server. Cloud never returns the upstream account's other custom voices.

Design a voice

Submit POST /v1/google/voices with ai:generate and a stable Idempotency-Key:

{
  "model": "google/gemini-3.8-flash-tts",
  "store": true,
  "voice": {
    "type": "prompted",
    "display_name": "Warm narrator",
    "language_code": "en-GB",
    "prompted": { "input": "A warm, thoughtful narrator with a gentle British accent and measured pacing." }
  }
}

The result includes a Cloud-scoped voice_air_... ID and, when Google supplies it, a WAV sample_audio preview. Use the scoped ID as the voice in speech requests. The provider's custom voice identifier is resolved only after project and tenant authorization. Voice creation and previews remain encrypted in the existing AI request store.

Prompted creation is charged from the provider's returned input/output modality usage, including its preview audio, with the configured Cloud markup. Missing or inconsistent usage requires reconciliation; Cloud does not guess the price or automatically repeat the paid operation.

Replicate your voice

Choose Create new voice → Voice Replication in the playground. Record or upload 10–30 seconds of natural speech, then record the same adult speaker saying Google's required consent statement. Confirm the transfer and storage before submitting. The browser converts both recordings to mono 24 kHz, 16-bit PCM WAV and validates duration. Audio is sent to Google only when you choose Replicate voice.

The request uses the same envelope, with voice.type: "replicated" and:

{
  "replicated": {
    "source_audio": { "mime_type": "audio/wav", "data": "BASE64_REFERENCE_WAV" },
    "consent_audio": { "mime_type": "audio/wav", "data": "BASE64_CONSENT_WAV" }
  }
}

Both recordings are required. Cloud validates the WAV header, encoding, duration and size; Google performs the speaker and consent checks. Reference clips must be 10–30 seconds and consent clips 3–30 seconds. Stateless voicekey_..., arbitrary upstream custom IDs and voice remixing are not exposed.

The reviewed replication creation fee is currently zero when Google returns a successful replication receipt without token usage. If Google returns usage, Cloud prices it rather than discarding it. Subsequent speech synthesis is billed at the selected TTS route's rates. This replication price review expires November 10, 2026. An expired price card disables new work until reviewed.

Rename or remove a custom voice

Use POST /v1/google/voices/manage with a project credential granting ai:generate:

{
  "ids": ["VOICE_ID_FROM_CUSTOM_VOICES"],
  "operation": "rename",
  "name": "Narrator"
}

For removal, send the same ids with "operation": "delete" and omit name. Each ID must be a Cloud voice_air_... ID. A request accepts 1–200 distinct IDs; names must be nonblank and at most 100 characters, including surrounding whitespace in the submitted value. Cloud trims names before storing them. The complete selection must belong to the active project and tenant; if any voice is missing or inaccessible, none are updated. Success returns { "success": true }.

These operations change Cloud metadata without submitting provider generation. Removal hides the voice from the Cloud library and prevents future use; it does not delete Google's upstream resource or erase the encrypted generation and billing receipt. Renaming does not restore a removed voice.

Shared platform voices

Cloud administrators can design or replicate voices once and publish them to every project and tenant. Each appears in shared_voices as:

{
  "id": "voice_shared_0123456789abcdef0123456789abcdef",
  "display_name": "House narrator",
  "description": "Warm narrator for product explainers",
  "language_code": "en-US",
  "tags": ["narration", "calm"],
  "type": "prompted",
  "owner": "platform",
  "preview_url": "/v1/voices/voice_shared_0123456789abcdef0123456789abcdef/preview"
}

description, language_code, tags and preview_url are omitted when empty. Use the id as the voice in speech requests (voiceConfig.voice, a speaker's voiceConfig.voice, or OpenAI-style voice) on any route advertising request_constraints.audio_outputs.sharedVoices: true from the same provider voice family. Speech using a shared voice is billed to your project exactly like any other speech; the voice's creation was a platform cost and is never charged to a tenant. GET the preview_url path with ai:read credentials to play its WAV preview.

Shared voices are read-only for projects: POST /v1/google/voices/manage with a voice_shared_... ID returns 403 platform_voice_read_only. custom_voices never contains platform voices and shared_voices never contains project voices. A voice the platform disables or removes stops appearing and is refused in new requests.

Retry and lifetime

Retain the X-AI-Request-Id and the original idempotency key. Network failures and unknown provider outcomes must be retried using that same key. The UI preserves unresolved creation inputs and the key. Completed custom voices can be found by reopening the voice picker.

Cloud currently exposes voices created within the previous 365 days. Google's provider expiry can be earlier, and a rejected voice must be recreated through a new verified creation request. Each voice remains limited to its originating Cloud project, tenant and provider connection.

Provider contracts: speech generation, Voice Design, Voice Replication, and Voices API. The Google API team's billing clarification describes prompted creation usage and replication's lack of token usage.