跳转至

1. 模型说明

Gemini TTS 通过 文本（及可选多模态输入）生成语音，调用形态为 Vertex generateContent（同步） 与 streamGenerateContent（SSE 流式）。

2. 计费

2.1 平台的计费项与用量

chargeItemCode 中文名 用量计算（用户侧） 触发接口
in_token 输入 token 响应 usageMetadata.promptTokenCount 四条 TTS 接口
out_token_audio 输出音频 token 响应 usageMetadata.candidatesTokensDetails 中 modality 为 AUDIO 的 token 之和 四条 TTS 接口
in_token_create
 语音设计/复制创建输入 token
 创建响应 usage.input_tokens_by_modality 中 modality=text 的 tokens POST .../google/voices（Prompted 或 Replicated 且 store: true）
out_token_audio_create 语音设计/复制创建输出音频 token 创建响应 usage.output_tokens_by_modality 中 modality=audio 的 tokens 同上

3. 功能接口详情

3.0 公共请求 Body（四条接口共用）

Content-Type: application/json。Body 为 Vertex GenerateContentRequest JSON（camelCase 或 snake_case 均可，与官方一致）。

主要字段

参数名 字段类型 是否必填 描述
contents Object（Content），array / object 是 与模型当前对话的内容。对于单轮查询，这是单个实例。对于多轮查询，这是包含对话历史记录和最新请求的重复字段。
generationConfig Object（GenerationConfig） 否 生成配置设置。TTS 场景下常用其中的 speechConfig（音色、语言等）。
systemInstruction Object（Content） 否 适用于 gemini-2.0-flash 和 gemini-2.0-flash-lite。有关引导模型获得更好性能的说明。text 字符串会计入 token 限制。systemInstruction 的 role 字段会被忽略，不会影响模型的性能。
safetySettings array（SafetySetting） 否 针对每个请求的设置，用于屏蔽不安全内容。在 GenerateContentResponse.candidates 上强制执行。
tools array（Tool） 否 一段代码，可让系统与外部系统进行交互，以在模型知识和范围之外执行操作或一组操作。
toolConfig Object（ToolConfig） 否 请参阅函数调用。
cachedContent string 否 用作提供预测的上下文的缓存内容的名称。格式：projects/{project}/locations/{location}/cachedContents/{cachedContent}
labels Object（map\） 否 您可以采用键值对格式添加到 API 调用中的元数据。

generationConfig.speechConfig（TTS 常用）

参数名 字段类型 是否必填 描述
voiceConfig
 Object（VoiceConfig） 否 单说话人预置音色；字段结构见 PrebuiltVoiceConfig（对外音色字段名为 voice）。
multiSpeakerVoiceConfig
 Object（MultiSpeakerVoiceConfig） 否 多说话人音色配置。
languageCode string 否 语言代码（如 en-US）。

公共响应字段（同步 / 流式单 chunk）

参数名 字段类型 描述
candidates
 array（Candidate） 模型生成的候选结果；TTS 音频通常在 candidates[].content.parts[].inlineData（base64 音频）。
usageMetadata Object（UsageMetadata） Token 用量；含 promptTokenCount、candidatesTokenCount、candidatesTokensDetails 等。
modelVersion string 用于生成的模型及版本。
responseId string 响应 ID。
promptFeedback
 Object（PromptFeedback） 提示相关反馈（如安全拦截）。

3.1 同步 generateContent（平台路径）

3.1.1 请求 url

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

3.1.2 请求 Body 参数

见 §3.0。

3.1.3 响应参数

见 §3.0 公共响应字段。HTTP 200 时 body 为完整 GenerateContentResponse JSON。

3.1.4 请求示例

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" }
      }
    }
  }
}'

注：使用自定义音色时，音色id需传递给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 响应示例（节选）

{
  "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 流式 streamGenerateContent（平台路径）

3.2.1 请求 url

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

可选 Query：

参数名 字段类型 是否必填 描述
alt string 否 为 sse 时，使用 Servlet SSE（text/event-stream）写回，适配部分 HTTP 客户端；省略时返回响应式 SSE 流（text/event-stream）。

3.2.2 请求 Body 参数

见 §3.0。

3.2.3 响应说明

  • Content-Type：text/event-stream

  • 每个事件 data 为 GenerateContentResponse JSON（部分实现会在 JSON 前带一空格，解析时请 trim）。

  • 错误时可能推送含 error 字段的 JSON 后结束流。

  • 用量以最后一个包含 usageMetadata 的事件为准（见 §2.2）。

3.2.4 请求示例

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 同步 generateContent（原生 Vertex 路径）

3.3.1 请求 url

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

路径参数 {modelName}：与 Google 模型资源名一致（如 gemini-2.5-flash-preview-tts），建议与端点配置的官方 model 相同。

3.3.2 请求 Body / 响应

同 §3.1（Body 见 §3.0）。

3.3.3 请求示例

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 流式 streamGenerateContent（原生 Vertex 路径）

3.4.1 请求 url

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

3.4.2 请求 Body / 响应

Body 同 §3.0；响应为 SSE（text/event-stream），语义同 §3.2.3（原生路径当前以 SSE 写回）。

3.4.3 请求示例

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 自定义音色（google/voices）

语音设计和语音复刻（Store: true）将创建的音色存储在Google，存储期限是1年，每次使用（如在generateContent接口的speechConfig.voiceConfig.voice中）将刷新存储期限

语音复刻密钥 (store: false)：Google 不会存储复刻的语音。该服务会在 key 字段中返回加密的语音复刻密钥 (voicekey_...)

3.5.1 创建音色（语音设计 / 语音复制）

3.5.1.1 请求 url

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

3.5.1.2 请求 Body 参数

参数名 字段类型 是否必填 默认值 描述
store boolean 是 — 是否存储
voice object 是 — 音色定义
voice.type string 是 — 音色设计：VOICE_TYPE_PROMPTED
音色复制：VOICE_TYPE_REPLICATED
voice.displayName
 string 是 — 音色设计：VOICE_TYPE_PROMPTED
音色复制：VOICE_TYPE_REPLICATED
voice.gender
 string 否 展示名称
voice.language_code
 string 否 语言代码
voice.prompted.input string
 设计时必填 — 音色的描述词，用于音色设计
voice.replicated.source_audio
 object
 复制时必填 — 参考音频，10 到 30 秒的清晰、自然的语音，来自您想要复制其声音的说话者。较长的样本通常会产生更好的结果。
voice.replicated.consent_audio object
 复制时必填
 同意音频：同一位说话者逐字朗读其语言版本的同意声明的录音。如需查看这些声明，请参阅支持的语言和意见征求声明。创建中文音色时：我是这段声音的所有者，并已同意通过 Google Cloud 创建我的声音合成模型。

3.5.1.3 响应参数

3.5.1.4 请求示例

语音设计

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..." }
  }
}'

创建存储的语音复刻

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}"
        }
      }
   }
}'

创建语音复刻密钥

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 响应示例（语音设计，节选）

{
  "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 获取音色列表

3.5.2.1 请求 url

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

3.5.2.2 请求 Query 参数

参数名 字段类型 是否必填 默认值 描述
type string
 是 — prebuilt / prompted / replicated
search string 否 — 对 display_name、description 不区分大小写子串匹配搜索
page integer 否 1 platform 页码，从 1 起；响应 body 中 page 回显本参数；下一页请求 page+1
pageSize integer 否 20 1–50
sync boolean 否 false 为true时，将同步本批查询的音色状态后再返回，为false时，将立刻返回，并异步更新所有音色的状态

3.5.2.3 响应示例（节选）

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

3.5.3 查询单个音色

GET https://genaiapi-m2.cloudsway.net/v1/ai/{YOUR_ENDPOINT}/google/voices/{voiceId}；路径参数 voiceId 为 voice_... 或 prebuilt id。不存在或已删除返回统一错误体。

3.5.4 删除音色

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

3.5.5 错误响应

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

列表缺少 type 或为空时返回 400。