跳到主要内容

文本转语音

所选 TTS 服务为 ctx.textToSpeech。它返回 ReadableStream，使用方无需等待完整响应即可开始播放或保存。

const speech = await ctx.textToSpeech.synthesize('欢迎登船。', {
  voice: 'alloy',
  signal,
})

const response = new Response(speech.audio, {
  headers: {'content-type': speech.mediaType},
})

结果包含音频流、媒体类型和模型。必须消费或取消该流；流完成或被丢弃前会持续占用并发容量。

voices() 返回可发现的声音。空列表表示提供方无法枚举声音，此时 UI 应允许手动填写声音 ID。

OpenAI 兼容选项​

选项含义
voice声音 ID，覆盖配置默认值
responseFormatmp3、opus、aac、flac、wav 或 pcm
speed0.25 到 4 的语速
instructions模型支持时使用的朗读指令
user可选最终用户标识

合成调用 POST /audio/speech。声音发现调用 GET /audio/voices；HTTP 404 或 405 视为不支持，并返回空列表。

流的所有权​

返回流由调用方负责。用于播放时，应交给能在播放被替换或组件卸载时取消读取器的组件；用于持久化时，应将流输送到目标并等待完成，再把资源记录为可用。

const {audio, mediaType, model} = await ctx.textToSpeech.synthesize(text, {
  priority: 'foreground',
  signal,
})

await audio.pipeTo(destination, {signal})

不要只根据请求格式推断扩展名，应使用返回的 mediaType，因为兼容服务器仍决定实际响应。服务不会解码、重采样或规范化音频；若使用方要求特定采样率或容器，应在合成后自行转换。

声音选择​

声音 ID 应视为不透明且属于特定提供方。保存声音时，应同时关联提供该声音的提供方与连接。voices() 返回条目时，可显示其 name 和 description，但提交稳定的 id。发现结果为空时，只需验证手动 ID 非空，再由提供方判断它是否存在。

空合成文本为 invalid-input。若在请求前即可判断格式或指令不受支持，则为 unsupported；提供方拒绝则为 rejected。