音频生成

POST /v1beta/models/{model}:generateContent

Gemini 音频生成接口。可使用 gemini-2.5-flash-preview-tts 等模型。

请求参数

路径参数

模型路径参数

参数	类型	默认值	说明	是否必填
`model`	string	—	模型名称，位于 `/v1beta/models/{model}` 路径中。	是

请求头

x-goog-api-key

使用 Gemini API Key 认证。

格式: x-goog-api-key: sk-xxxxxx

请求体

请求字段

参数	类型	默认值	说明	是否必填
`contents`	array	—	包含待合成文本的内容数组；文本放在 `contents[].parts[].text`。	是
`generationConfig`	object	—	必须包含 `responseModalities` 和 `speechConfig`。	是
`responseModalities`	array<string>	—	输出模态，TTS 请求设置为 `["AUDIO"]`。	是
`speechConfig.voiceConfig.prebuiltVoiceConfig.voiceName`	string	—	预置声音名称，必须是上游模型支持的声音。	是

请求体示例

查看 JSON 请求体示例

{
  "contents": [{ "parts": [{ "text": "欢迎使用 API接口文档。" }] }],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {
      "voiceConfig": { "prebuiltVoiceConfig": { "voiceName": "Kore" } }
    }
  }
}

请求示例代码

cURLJavaScriptGoPythonJavaC#

curl -X POST "https://10000router.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d @tts-request.json

const payload = {
  contents: [{ parts: [{ text: "欢迎使用 API接口文档。" }] }],
  generationConfig: {
    responseModalities: ["AUDIO"],
    speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: "Kore" } } }
  }
};
const response = await fetch("https://10000router.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent", {
  method: "POST",
  headers: { "x-goog-api-key": process.env.GEMINI_API_KEY },
  body: JSON.stringify(payload)
});
console.log((await response.json()).candidates?.[0]?.content?.parts);

payload := `{
  "contents": [{"parts": [{"text": "欢迎使用 API接口文档。"}]}],
  "generationConfig": {
    "responseModalities": ["AUDIO"],
    "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}}
  }
}`
req, _ := http.NewRequest("POST", "https://10000router.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent", strings.NewReader(payload))
req.Header.Set("x-goog-api-key", os.Getenv("GEMINI_API_KEY"))
res, err := http.DefaultClient.Do(req)
if err != nil { log.Fatal(err) }
defer res.Body.Close()

import os
import requests

payload = {
    "contents": [{"parts": [{"text": "欢迎使用 API接口文档。"}]}],
    "generationConfig": {
        "responseModalities": ["AUDIO"],
        "speechConfig": {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": "Kore"}}},
    },
}
response = requests.post(
    "https://10000router.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent",
    json=payload,
)
print(response.json())

var payload = "{"
    + "\"contents\":[{\"parts\":[{\"text\":\"欢迎使用 API接口文档。\"}]}],"
    + "\"generationConfig\":{\"responseModalities\":[\"AUDIO\"],"
    + "\"speechConfig\":{\"voiceConfig\":{\"prebuiltVoiceConfig\":{\"voiceName\":\"Kore\"}}}}}";
var request = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://10000router.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent"))
    .header("x-goog-api-key", System.getenv("GEMINI_API_KEY"))
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(payload))
    .build();
var response = java.net.http.HttpClient.newHttpClient().send(request, java.net.http.HttpResponse.BodyHandlers.ofString());

using System.Net.Http.Json;
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-goog-api-key", Environment.GetEnvironmentVariable("GEMINI_API_KEY"));
var payload = new {
    contents = new[] { new { parts = new[] { new { text = "欢迎使用 API接口文档。" } } } },
    generationConfig = new {
        responseModalities = new[] { "AUDIO" },
        speechConfig = new { voiceConfig = new { prebuiltVoiceConfig = new { voiceName = "Kore" } } }
    }
};
var response = await client.PostAsJsonAsync("https://10000router.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent", payload);
Console.WriteLine(await response.Content.ReadAsStringAsync());

返回响应

响应示例

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "inlineData": { "mimeType": "audio/wav", "data": "<BASE64_AUDIO>" } }]
    },
    "finishReason": "STOP",
    "safetyRatings": []
  }],
  "usageMetadata": { "promptTokenCount": 10, "candidatesTokenCount": 0, "totalTokenCount": 10 }
}

读取 candidates[0].content.parts[].inlineData.data，Base64 解码后按 mimeType 保存为音频文件。音频编码和采样率由模型决定，请以返回的 MIME 类型为准。usageMetadata 可能因上游渠道而省略部分字段。

响应字段

字段	类型	说明
`candidates`	array	模型生成的候选音频结果。
`candidates[].content.parts[].inlineData.mimeType`	string	音频 MIME 类型，例如 `audio/wav`。
`candidates[].content.parts[].inlineData.data`	string	音频的 Base64 数据，解码后保存为文件。
`candidates[].finishReason`	string	生成结束原因，例如 `STOP`。
`usageMetadata`	object	输入、输出及总 token 统计，字段可能因渠道而省略。

错误响应

200 成功 400 请求错误 429 请求频率限制

成功响应请参阅上方的音频响应示例。

{
  "error": {
    "code": 400,
    "message": "Invalid audio generation configuration",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded",
    "status": "RESOURCE_EXHAUSTED"
  }
}

音频(audio)