1. Model Description

Gemini TTS generates speech from text (and optional multimodal inputs), with invocation methods being Vertex generateContent (synchronous) and streamGenerateContent (SSE streaming).

2. Billing

2.1 Billing Items and Usage of the Platform

chargeItemCode	Chinese name	Usage Calculation (User Side)	Trigger Interface
`in_token`	Input token	Response `usageMetadata.promptTokenCount`	Four TTS interfaces
`out_token_audio`	output audio tokens	Sum of tokens in the response `usageMetadata.candidatesTokensDetails`where the modality is AUDIO	Four TTS interfaces
`in_token_create`	Voice Design / Copy to Create Input Tokens	Create a response `usage.input_tokens_by_modality`where `modality= text`has `tokens`	`POST .../google/voices`(Prompted or Replicated and `store: true`)
`out_token_audio_create`	Voice Design / Copy to Create Output Audio Tokens	Create response `usage.output_tokens_by_modality`where `modality= audio`has `tokens`	Ditto

3. Details of Functional Interfaces

3.0 Common Request Body (Shared by Four Interfaces)

Content-Type: application/json. The body is a Vertex GenerateContentRequest JSON object (either camelCase or snake_case is acceptable, consistent with the official specification).

Main Fields

Parameter Name	Field Type	Required or not	Description
contents	Object(Content), array / object	Yes	The content of the current conversation with the model. For single-turn queries, this is a single instance. For multi-turn queries, this is a repeated field that contains conversation history along with the latest request.
generationConfig	Object(GenerationConfig)	No	Generate configuration settings. In TTS scenarios, the commonly used component is `speechConfig` (for voice timbre, language, etc.).
systemInstruction	Object(Content)	No	Applicable to gemini-2.0-flash and gemini-2.0-flash-lite. For instructions on guiding the model to achieve better performance. Text strings count towards the token limit. The role field of systemInstruction will be ignored and will not affect the model's performance.
safetySettings	array(SafetySetting)	No	A per-request setting to block insecure content. Enforced on GenerateContentResponse. Candidates.
tools	array(Tool)	No	A piece of code that enables a system to interact with external systems to perform an action or a set of actions beyond the scope and knowledge of the model.
toolConfig	Object(ToolConfig)	No	Please refer to function calls.
cachedContent	string	No	The name of the cached content used as context to provide predictions. Format: projects/{project}/locations/{location}/cachedContents/{cachedContent}
labels	Object(map\)	No	You can add metadata in the Attribute–Value Pair format to API calls.

generationConfig.speechConfig (commonly used for TTS)

Parameter Name	Field Type	Required or not	Description
voiceConfig	Object(VoiceConfig)	No	Preset timbre for single speaker; for the field structure, see PrebuiltVoiceConfig (the external field name for timbre is `voice`).
multiSpeakerVoiceConfig	Object(MultiSpeakerVoiceConfig)	No	Multi-speaker voice configuration.
languageCode	string	No	Language code (e. g. `en-US`).

Common Response Fields (Synchronous / Streaming Single Chunk)

Parameter Name	Field Type	Description
candidates	array(Candidate)	Candidate results generated by the model; TTS audio is usually located at `candidates[]. content.parts[]. inlineData` (base64 audio).
usageMetadata	Object(UsageMetadata)	Token usage; includes `promptTokenCount`, `candidatesTokenCount`, `candidatesTokensDetails`, etc.
modelVersion	string	The model and version used for generation.
responseId	string	Response ID.
promptFeedback	Object(PromptFeedback)	Prompt relevant feedback (e. g., security interception).

3.1 Synchronous generateContent (Platform Path)

3.1.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/tts/generateContent

3.1.2 Request Body Parameters

See §3.0.

3.1.3 Response Parameters

See §3.0 Common Response Fields. When the HTTP status code is 200, the body is a complete GenerateContentResponseJSON object.

3.1.4 Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/tts/generateContent' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "contents": [{
    "role": "user",
    "parts": [{ "text": "Say hello in a friendly tone." }]
  }],
  "generationConfig": {
    "speechConfig": {
      "voiceConfig": {
        "prebuiltVoiceConfig": { "voiceName": "Kore" }
      }
    }
  }
}'

Note: When using a custom voice, the voice ID needs to be passed to speechConfig.voiceConfig.voice

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/tts/generateContent' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "contents": [{
    "role": "user",
    "parts": [{ "text": "Say hello in a friendly tone." }]
  }],
  "generationConfig": {
    "speechConfig": {
      "voiceConfig": {
        "voiceName": "voice_xxxxx"
      }
    }
  }
}'

3.1.5 Response Example (Excerpt)

{
  "candidates": [{
    "content": {
      "parts": [{
        "inlineData": {
          "mimeType": "audio/L16;codec=pcm;rate=24000",
          "data": "<base64-audio>"
        }
      }]
    }
  }],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 85,
    "candidatesTokensDetails": [
      { "modality": "AUDIO", "tokenCount": 80 }
    ]
  }
}

3.2 Streaming streamGenerateContent (Platform Path)

3.2.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/tts/streamGenerateContent

Optional Query:

Parameter Name	Field Type	Required or not	Description
alt	string	No	When set to `sse`, Servlet SSE (`text/event-stream`) is used for write-back to adapt to some HTTP Clients; when omitted, a reactive SSE stream (`text/event-stream`) is returned.

3.2.2 Request Body Parameters

See §3.0.

3.2.3 Response Description

Content-Type: text/event-stream
The data of each eventis a GenerateContentResponse JSON (some implementations may add a space before the JSON, please trim it during parsing).
When an error occurs, the system may push a JSON containing the errorfield and then terminate the stream.
The usage amount shall be based on the last event that contains usageMetadata (see §2.2).

3.2.4 Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/tts/streamGenerateContent?alt=sse' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
  "contents": [{
    "role": "user",
    "parts": [{ "text": "Stream this sentence as speech." }]
  }],
  "generationConfig": {
    "speechConfig": {
      "voiceConfig": {
        "prebuiltVoiceConfig": { "voiceName": "Kore" }
      }
    }
  }
}'

3.3 Synchronous generateContent (Native Vertex Path)

3.3.1 Request URL

POST https://genaiapi-m2.cloudsway.net/{YOUR_ENDPOINT}/tts/v1beta1/publishers/google/models/{modelName}:generateContent

Path parameter{modelName}: Consistent with the Google model resource name (e. g. gemini-2.5-flash-preview-tts), it is recommended to be the same as the official model configured for the endpoint.

3.3.2 Request Body / Response

Same as §3.1 (for Body, see §3.0).

3.3.3 Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/{YOUR_ENDPOINT}/tts/v1beta1/publishers/google/models/gemini-2.5-flash-preview-tts:generateContent' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "contents": [{
    "role": "user",
    "parts": [{ "text": "Hello." }]
  }],
  "generationConfig": {
    "speechConfig": {
      "voiceConfig": {
        "prebuiltVoiceConfig": { "voiceName": "Kore" }
      }
    }
  }
}'

3.4 Streaming streamGenerateContent (Native Vertex Path)

3.4.1 Request URL

POST https://genaiapi-m2.cloudsway.net/{YOUR_ENDPOINT}/tts/v1beta1/publishers/google/models/{modelName}:streamGenerateContent

3.4.2 Request Body / Response

Body is the same as §3.0; the response is SSE (text/event-stream), with the same semantics as §3.2.3 (the native path currently writes back via SSE).

3.4.3 Request Example

curl --location 'https://genaiapi-m2.cloudsway.net/{YOUR_ENDPOINT}/tts/v1beta1/publishers/google/models/gemini-2.5-flash-preview-tts:streamGenerateContent' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/event-stream' \
--data '{
  "contents": [{
    "role": "user",
    "parts": [{ "text": "Hello." }]
  }],
  "generationConfig": {
    "speechConfig": {
      "voiceConfig": {
        "prebuiltVoiceConfig": { "voiceName": "Kore" }
      }
    }
  }
}'

3.5 Custom Tones (google/voices)

Voice design and voice cloning (Store: true) will store the created voice on Google, with a retention period of 1 year, and each usage (e. g., in speechConfig.voiceConfig.voice of the generateContent API) will refresh the retention period.

Voice Replication Key (store: false): Google will not store the replicated voice. The service will return an encrypted voice replication key (voicekey_. ..) in the key field.

3.5.1 Create Timbre (Voice Design / Voice Cloning)

3.5.1.1 Request URL

POST https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices

3.5.1.2 Request Body Parameters

Parameter Name	Field Type	Required or not	default value	Description
store	boolean	Yes	—	Whether to store
voice	object	Yes	—	Timbre Definition
voice.type	string	Yes	—	Timbre Design: `VOICE_TYPE_PROMPTED` Timbre Replication: `VOICE_TYPE_REPLICATED`
voice.displayName	string	Yes	—	Timbre Design: `VOICE_TYPE_PROMPTED` Timbre Replication: `VOICE_TYPE_REPLICATED`
voice.gender	string	No		Display Name
voice.language_code	string	No		Language Code
voice.prompted.input	string	Required at design time	—	Timbre descriptors for timbre design
voice.replicated.source_audio	object	Required when copying	—	Reference audio: clear, natural speech of 10 to 30 seconds from the speaker whose voice you want to clone. Longer samples usually yield better results.
voice.replicated.consent_audio	object	Required when copying		Consent Audio: A recording of the same speaker reading a word-for-word version of the consent statement in their language. To view these statements, see Supported Languages and Consent Statements. When creating a Chinese voice: `I am the owner of this voice and consent to the creation of my voice synthesis model via Google Cloud.`

3.5.1.3 Response Parameters

3.5.1.4 Request Example

Voice Design

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "store": true,
  "voice": {
    "type": "VOICE_TYPE_PROMPTED",
    "display_name": "Warm British Astronomer",
    "prompted": { "input": "A warm, thoughtful astronomer..." }
  }
}'

Create stored voice cloning

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "store": true,
  "voice": {
    "type": "VOICE_TYPE_REPLICATED",
    "displayName": "Custom replicated speaker",
    "replicated": {
      "sourceAudio": {
          "mimeType": "audio/wav",
          "data": "${SOURCE_B64}"
        },
      "consentAudio": {
          "mimeType": "audio/wav",
          "data": "${CONSENT_B64}"
        }
      }
   }
}'

Create Voice Replication Key

curl --location 'https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices' \
--header 'Authorization: Bearer {YOUR_AK}' \
--header 'Content-Type: application/json' \
--data '{
  "store": false,
  "voice": {
    "type": "VOICE_TYPE_REPLICATED",
    "replicated": {
      "sourceAudio": {
          "mimeType": "audio/wav",
          "data": "${SOURCE_B64}"
        },
      "consentAudio": {
          "mimeType": "audio/wav",
          "data": "${CONSENT_B64}"
        }
      }
   }
}'

3.5.1.5 Response Example (Excerpt from Voice Design)

{
  "id": "voice_658fb1ee-da2b-4b18-b855-52f23a52f5dc",
  "usage": { "total_tokens": 1493, "total_input_tokens": 219, "total_output_tokens": 1274 },
  "sample_audio": { "mime_type": "audio/l16; rate=24000; channels=1", "data": "base64 data" }
}

3.5.2 Obtain Timbre List

3.5.2.1 Request URL

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices

3.5.2.2 Request Query Parameters

Parameter Name	Field Type	Required or not	default value	Description
type	string	Yes	—	`prebuilt` / `prompted` / `replicated`
search	string	No	—	Performs case-insensitive substring matching search on display_name and description
page	integer	No	1	platform page number, starting from 1; this parameter is echoed back in the page field of the response body; for the next page request, increment the page value by 1
pageSize	integer	No	20	1–50
sync	boolean	No	false	When set to true, the status of the voices in this batch query will be synchronized before a response is returned; when set to false, a response will be returned immediately, and the status of all voices will be updated asynchronously.

3.5.2.3 Response Example (Excerpt)

{
  "page": 1,
  "pageSize": 50,
  "result": [
    {
      "id": "voice_658fb1ee-da2b-4b18-b855-52f23a22f5dc",
      "type": "VOICE_TYPE_PROMPTED",
      "display_name": "test_only_2"
    }
  ]
}

3.5.3 Query a Single Timbre

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices/{voiceId}; Path parameters voiceIdis voice_. ..or a prebuilt ID. A unified error object will be returned if it does not exist or has been deleted.

3.5.4 Delete Timbre

DELETE https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices/{voiceId}

3.5.5 Error Response

{
  "error": {
    "code": 404,
    "message": "Voice `voice_...` not found.",
    "status": "NOT_FOUND"
  }
}

Return 400when the list is missing type or is empty.