POST/v1beta/models/gemini-2.5-pro-preview-tts:generateContent

Gemini TTS：双人对话与音色配置

使用 AUDIO 与 speechConfig 生成语音，从 inlineData 解码 PCM 并转换为 WAV。

API Key application/json

功能与适用场景

通过两位说话者与音色映射生成一段对话音频。提示词中的说话者标签必须与配置一致。

支持模型与组合

示例 gemini-3.1-flash-tts-preview，预览型号；主持人用 Kore，嘉宾用 Puck。两人上限，speaker 标签逐字匹配提示词。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY。替换占位符，保留 Bearer 后的空格。无需厂商 API Key。

第二步：调用模型

POST https://top.qingyuntop.ai/v1beta/models/gemini-3.1-flash-tts-preview:generateContent

请求为 application/json。

Request

请求

/v1beta/models/gemini-2.5-pro-preview-tts:generateContent

Body

必填

Bodyobject

contentsarray必填

必填，顶层 content 数组。role 使用 user / model，parts 保持原始顺序；下一轮重新发送历史。

元素object

数组元素。

partsarray<object>

每条 content 必填。文本 {text:...}；媒体 {inlineData:{mimeType,data}}；一张图片一个 part，顺序影响引用。

元素object

数组元素。

textstring

generationConfigobject

选填，顶层对象。输出长度、采样、结构化格式、思考和语音设置分别放在对象对应子字段。

responseModalitiesarray

语音生成时必填 ["AUDIO"]。不要对普通文本模型设置 AUDIO；仅使用专门 TTS 型号。

元素string

speechConfigobject

语音配置，选填。单人使用 voiceConfig.prebuiltVoiceConfig.voiceName；多人使用 multiSpeakerVoiceConfig.speakerVoiceConfigs，speaker 对应提示词中的说话者。

voiceConfigobject必填

指定的声音角色的名字

prebuiltVoiceConfigobject必填

voiceNamestring必填

temperaturenumber

topPnumber

topKinteger

maxOutputTokensinteger

选填，正整数，无统一默认。限制输出 token，思考也占用预算；示例 4096。

stopSequencesarray<string>

元素string

数组元素。

model（路径）string必填

必填，在 /v1beta/models/{model}:动作中填写；generateContent 请求体无需重复 model。

safetySettingsarray<object>

选填字段；是否可用取决于当前模型和协议。

元素object

数组元素。

categorystring

thresholdstring

toolsarray<object>

选填，顶层工具数组。按本页选择 functionDeclarations、googleSearch、urlContext 或 codeExecution；名称区分大小写。

元素object

数组元素。

systemInstructionobject

选填，顶层。parts 中填写文本指令，不放入 generationConfig。

partsarray<object>

元素object

数组元素。

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`key`	Query	string	是	-	YOUR_API_KEY
`Content-Type`	Header	string	是	-	application/json

请求示例application/json

set -euo pipefail
python3 - <<'PY'
import base64
import json
from pathlib import Path

payload = json.loads(r'''{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "用轻松自然的语气朗读：\n主持人：欢迎收听我们的节目。\n嘉宾：很高兴来到这里。"
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": [
      "AUDIO"
    ],
    "speechConfig": {
      "multiSpeakerVoiceConfig": {
        "speakerVoiceConfigs": [
          {
            "speaker": "主持人",
            "voiceConfig": {
              "prebuiltVoiceConfig": {
                "voiceName": "Kore"
              }
            }
          },
          {
            "speaker": "嘉宾",
            "voiceConfig": {
              "prebuiltVoiceConfig": {
                "voiceName": "Puck"
              }
            }
          }
        ]
      }
    }
  }
}''')
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
Path("request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1beta/models/gemini-3.1-flash-tts-preview:generateContent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  --output response.json
python3 - <<'PY'
import base64
import json
from pathlib import Path
result = json.loads(Path("response.json").read_text(encoding="utf-8"))
candidate = result["candidates"][0]
if candidate.get("finishReason") != "STOP":
    raise ValueError("语音未正常结束，请检查完整响应")
chunks = []
for part in candidate["content"]["parts"]:
    audio = part.get("inlineData", {})
    if not audio.get("mimeType", "").startswith("audio/"):
        continue
    if "pcm" not in audio["mimeType"].lower() or "24000" not in audio["mimeType"]:
        raise ValueError("输出并非本示例的24kHz PCM，请按实际MIME解码")
    decoded = base64.b64decode(audio["data"], validate=True)
    if not decoded or len(decoded) % 2:
        raise ValueError("PCM 字节为空或不完整")
    chunks.append(decoded)
if not chunks:
    raise ValueError("响应没有音频内容")
Path("speech.pcm").write_bytes(b"".join(chunks))
PY

Response

返回响应 `200`

HTTP 响应

响应 200object

响应示例json

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "audio/L16;codec=pcm;rate=24000",
              "data": "<请替换为实际内容>"
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": null
    }
  ],
  "promptFeedback": {
    "safetyRatings": null
  },
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 51,
    "totalTokenCount": 60,
    "thoughtsTokenCount": 0,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 9
      }
    ]
  },
  "modelVersion": "gemini-2.5-pro-preview-tts",
  "responseId": "nXxoaf7mPM6j_uMPyICzkQo"
}

常见错误与参考

输出尺寸、时长和模型可用性会变化，不承诺生成固定秒数。面向用户时说明是合成语音。语音理解请使用音频理解。

401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发；其他通用排查见聊天接入总览。

Google TTS 官方示例。

Gemini TTS：双人对话与音色配置

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

请求

Body

路径、查询与 Header 参数

返回响应 200

常见错误与参考

返回响应 `200`