> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Gemini 3.1 Flash TTS > Gemini 3.1 Flash TTS API 可使用预设音色、行内演绎标签和可选的风格指令，将文本转换为单人或双人语音。可选设置语言，并返回 MP3、WAV 或 Opus 音频。 > [!TIP] > > 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。 > 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)接口获取结果。 `gemini-3-1-flash-tts` 使用 Google 的 Gemini 3.1 Flash TTS 模型，将文本输入转换为富有表现力的语音音频。结果以任务 `files` 返回，与图像、视频、3D 和音频任务的标准响应结构一致。 ## 模型 * **gemini-3-1-flash-tts** - Gemini 3.1 Flash 文本转语音生成 ## 必填参数 * **text**：要转换为语音的文本 * 长度：`1-50000` 个字符 * 支持在文本中用自然语言指定风格、语速、口音和情绪 * 支持富有表现力的音频标签，例如 `[sigh]`、`[laughing]`、`[whispering]` 和 `[short pause]` * 多说话人合成时，在文本行前加上与 `speakers[].speaker_id` 匹配的说话人别名 ## 可选参数 * **style\_instructions**：可选，应用于本次请求的风格、演绎、语速、口音、语气或情绪指令 * **voice**：单说话人合成的预设音色。设置了 `speakers` 时忽略。默认：`Kore` * **language\_code**：可选的语言枚举，用于引导多语言合成。省略时模型根据 `text` 自动检测 * **speakers**：用于对话的恰好两个说话人对象。设置后忽略顶层 `voice`。每一项包括： * `voice`：Gemini 预设音色 * `speaker_id`：只包含字母、数字和下划线、不含空白的别名，在请求内唯一，在 `text` 中用作前缀 * **temperature**：控制演绎变化程度的数值。默认：`1`。范围：`0-2` * **output\_format**：`mp3`、`wav` 或 `ogg_opus`。默认：`mp3`。`mp3` 适合紧凑播放，`wav` 适合无压缩后期制作，`ogg_opus` 在质量与体积之间取得平衡 ## 预设音色 支持的值：`Achernar`、`Achird`、`Algenib`、`Algieba`、`Alnilam`、`Aoede`、`Autonoe`、`Callirrhoe`、`Charon`、`Despina`、`Enceladus`、`Erinome`、`Fenrir`、`Gacrux`、`Iapetus`、`Kore`、`Laomedeia`、`Leda`、`Orus`、`Pulcherrima`、`Puck`、`Rasalgethi`、`Sadachbia`、`Sadaltager`、`Schedar`、`Sulafat`、`Umbriel`、`Vindemiatrix`、`Zephyr`、`Zubenelgenubi`。 ## 示例 ### 带音频标签的单说话人 ```json theme={"dark"} { "model": "gemini-3-1-flash-tts", "callback_url": "https://your-domain.com/callback", "input": { "text": "Good morning, team. [short pause] Our release is stable, and the customer demo starts in ten minutes.", "style_instructions": "Warm, confident product narrator with clear pacing.", "voice": "Kore", "temperature": 1, "output_format": "mp3" } } ``` ### 多语言店铺助手 ```json theme={"dark"} { "model": "gemini-3-1-flash-tts", "callback_url": "https://your-domain.com/callback", "input": { "text": "English: Your order is ready for pickup.\nSpanish: Su pedido esta listo para recoger.\nFrench: Votre commande est prete a etre retiree.", "style_instructions": "Friendly store assistant voice, natural and concise.", "voice": "Zephyr", "language_code": "English (US)", "temperature": 1, "output_format": "wav" } } ``` ### 双人播客 ```json theme={"dark"} { "model": "gemini-3-1-flash-tts", "callback_url": "https://your-domain.com/callback", "input": { "text": "Host: Welcome back to Launch Notes. [laughing] Today's build finally passed.\nGuest: Great news. Let's keep the update clear and calm for users.", "style_instructions": "Conversational podcast tone with distinct speaker energy.", "speakers": [ { "speaker_id": "Host", "voice": "Charon" }, { "speaker_id": "Guest", "voice": "Kore" } ], "temperature": 1, "output_format": "ogg_opus" } } ``` ## 注意事项 * PoYo 对外公开的参数名是 `text`。 * 通过标准任务状态 API 查询状态。 * 成功响应返回 `files`，其中生成的语音使用 `file_type: audio`。 ## OpenAPI ````yaml zh/api-manual/music-series/gemini-3-1-flash-tts.json POST /api/generate/submit openapi: 3.0.0 info: title: PoYo AI - Gemini 3.1 Flash TTS API description: >- Gemini 3.1 Flash TTS API 使用预设音色、行内表达标签和可选的风格指令，将文本转换为单人或双人语音。可设置可选的语言，并返回 MP3、WAV 或 Opus 音频。 version: 1.0.0 servers: - url: https://api.poyo.ai description: 生产环境 security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - Gemini 3.1 Flash TTS summary: 提交 Gemini 3.1 Flash TTS 任务 description: 将文本输入转换为富有表现力的语音音频。 operationId: submitGemini31FlashTtsTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: single-audio-tags-mp3: summary: 带音频标签的单人语音 value: model: gemini-3-1-flash-tts callback_url: https://your-domain.com/callback input: text: >- Good morning, team. [short pause] Our release is stable, and the customer demo starts in ten minutes. style_instructions: Warm, confident product narrator with clear pacing. voice: Kore temperature: 1 output_format: mp3 multilingual-store-wav: summary: 多语言单音色输出 value: model: gemini-3-1-flash-tts callback_url: https://your-domain.com/callback input: text: |- English: Your order is ready for pickup. Spanish: Su pedido esta listo para recoger. French: Votre commande est prete a etre retiree. style_instructions: Friendly store assistant voice, natural and concise. voice: Zephyr language_code: English (US) temperature: 1 output_format: wav two-speaker-podcast-ogg: summary: 双人播客对话 value: model: gemini-3-1-flash-tts callback_url: https://your-domain.com/callback input: text: >- Host: Welcome back to Launch Notes. [laughing] Today's build finally passed. Guest: Great news. Let's keep the update clear and calm for users. style_instructions: Conversational podcast tone with distinct speaker energy. speakers: - speaker_id: Host voice: Charon - speaker_id: Guest voice: Kore temperature: 1 output_format: ogg_opus responses: '200': description: 任务提交成功 content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' '400': description: 请求参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 未授权 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SubmitRequest: type: object required: - model - input additionalProperties: false properties: model: type: string description: 模型标识符。 enum: - gemini-3-1-flash-tts example: gemini-3-1-flash-tts callback_url: type: string format: uri description: 接收结果通知的 Webhook 回调 URL example: https://your-domain.com/callback input: $ref: '#/components/schemas/Gemini31FlashTtsInput' SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-unified-1757165031-uyujaw3d status: type: string enum: - not_started - running - finished - failed example: not_started description: >- 任务状态。提交后立即返回时始终为 `not_started`。后续状态请通过[查询任务状态](/zh/api-manual/task-management/status)接口或 `callback_url` 获取。 - `not_started`：排队中，等待处理 - `running`：生成中 - `finished`：已完成，结果在 `files` 或 `output` 中 - `failed`：失败，详情见 `error_message` created_time: type: string format: date-time example: '2026-06-25T10:30:00' ErrorResponse: type: object properties: code: type: integer enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 error: type: object properties: message: type: string type: type: string Gemini31FlashTtsInput: type: object required: - text additionalProperties: false properties: text: type: string description: >- 要转换为语音的文本。支持在行内用自然语言指定风格、语速、口音和情绪，并支持 [sigh]、[laughing]、[whispering]、[short pause] 等表现力音频标签。多人合成时，在每行前加上与 speakers[].speaker_id 匹配的说话人别名作为前缀。 minLength: 1 maxLength: 50000 example: >- Good morning, team. [short pause] Our release is stable, and the customer demo starts in ten minutes. style_instructions: type: string description: 可选的风格、表达方式、语速、口音、语气或情绪指令，作用于整个请求。 example: Warm, confident product narrator with clear pacing. voice: $ref: '#/components/schemas/VoiceEnum' language_code: $ref: '#/components/schemas/LanguageCodeEnum' speakers: type: array description: >- 用于对话的说话人对象，必须恰好两个。设置后将忽略顶层的 voice。每个 speaker_id 只能包含字母、数字和下划线，不能有空白字符，在请求内唯一，并须在 text 中用作前缀。 minItems: 2 maxItems: 2 items: $ref: '#/components/schemas/SpeakerConfig' temperature: type: number description: 控制语音变化程度，取值 0 到 2。值越高，表达越多变。 minimum: 0 maximum: 2 default: 1 example: 1 output_format: type: string description: 音频输出格式。mp3 体积小，推荐用于播放；wav 未压缩，适合后期制作；ogg_opus 兼顾质量与体积。 enum: - mp3 - wav - ogg_opus default: mp3 example: mp3 VoiceEnum: type: string description: Gemini TTS 预设音色。 enum: - Achernar - Achird - Algenib - Algieba - Alnilam - Aoede - Autonoe - Callirrhoe - Charon - Despina - Enceladus - Erinome - Fenrir - Gacrux - Iapetus - Kore - Laomedeia - Leda - Orus - Pulcherrima - Puck - Rasalgethi - Sadachbia - Sadaltager - Schedar - Sulafat - Umbriel - Vindemiatrix - Zephyr - Zubenelgenubi default: Kore example: Kore LanguageCodeEnum: type: string description: 多语言合成的语言。省略时，模型根据文本自动检测。 enum: - Arabic (Egypt) - Bangla (Bangladesh) - Dutch (Netherlands) - English (India) - English (US) - French (France) - German (Germany) - Hindi (India) - Indonesian (Indonesia) - Italian (Italy) - Japanese (Japan) - Korean (South Korea) - Marathi (India) - Polish (Poland) - Portuguese (Brazil) - Romanian (Romania) - Russian (Russia) - Spanish (Spain) - Tamil (India) - Telugu (India) - Thai (Thailand) - Turkish (Turkey) - Ukrainian (Ukraine) - Vietnamese (Vietnam) - Afrikaans (South Africa) - Albanian (Albania) - Amharic (Ethiopia) - Arabic (World) - Armenian (Armenia) - Azerbaijani (Azerbaijan) - Basque (Spain) - Belarusian (Belarus) - Bulgarian (Bulgaria) - Burmese (Myanmar) - Catalan (Spain) - Cebuano (Philippines) - Chinese Mandarin (China) - Chinese Mandarin (Taiwan) - Croatian (Croatia) - Czech (Czech Republic) - Danish (Denmark) - English (Australia) - English (UK) - Estonian (Estonia) - Filipino (Philippines) - Finnish (Finland) - French (Canada) - Galician (Spain) - Georgian (Georgia) - Greek (Greece) - Gujarati (India) - Haitian Creole (Haiti) - Hebrew (Israel) - Hungarian (Hungary) - Icelandic (Iceland) - Javanese (Java) - Kannada (India) - Konkani (India) - Lao (Laos) - Latin (Vatican City) - Latvian (Latvia) - Lithuanian (Lithuania) - Luxembourgish (Luxembourg) - Macedonian (North Macedonia) - Maithili (India) - Malagasy (Madagascar) - Malay (Malaysia) - Malayalam (India) - Mongolian (Mongolia) - Nepali (Nepal) - Norwegian Bokmal (Norway) - Norwegian Nynorsk (Norway) - Odia (India) - Pashto (Afghanistan) - Persian (Iran) - Portuguese (Portugal) - Punjabi (India) - Serbian (Serbia) - Sindhi (India) - Sinhala (Sri Lanka) - Slovak (Slovakia) - Slovenian (Slovenia) - Spanish (Latin America) - Spanish (Mexico) - Swahili (Kenya) - Swedish (Sweden) - Urdu (Pakistan) example: English (US) SpeakerConfig: type: object required: - voice - speaker_id additionalProperties: false properties: voice: $ref: '#/components/schemas/VoiceEnum' speaker_id: type: string description: 别名，只能包含字母、数字和下划线，不能有空白字符，在请求内唯一，在 text 字段中作为前缀用于标识该说话人。 example: Host securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- 所有 API 接口都需要 Bearer Token 认证。 创建 API Key：登录 PoYo，进入 **仪表盘 → API 密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建 Key。 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.