Puter 语音转写入门到进阶全面掌握 puter.ai.speech2txt() 的转写、翻译与说话人分离【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter本文基于 Puter 开源仓库中的官方 API 文档 speech2txt.md 与相关源码编写系统讲解puter.ai.speech2txt()这一语音转文本Speech-to-Text能力如何把本地文件、远程 URL 或浏览器内存中的音频转写为文字、强制翻译成英文以及如何借助 xAIGrok与 OpenAI 背后的多说话人识别diarization获得带时间戳的分段结果。读完本文你将能够直接在自己的 Website / App、Node.js 或 Worker 中调用该接口并理解请求从 JS SDK 到后端统一ai-speech2txt驱动的完整链路。puter.ai.speech2txt()把一段口语音频转换成文本并可选用英文翻译与说话人分离输出。它是围绕 Puter“驱动driver驱动”的转写 API 封装层目前后端可路由到 OpenAI 与 xAIGrok两类提供方因此你可以用同一种前端写法处理本地文件、远程 URL 或浏览器中内存态的 Blob。语法与三种调用形态与文档同步接口支持以下三种等价写法puter.ai.speech2txt(source, testMode false) puter.ai.speech2txt(source, options, testMode false) puter.ai.speech2txt({ audio: source, ...options })从 SDK 源码 stt.js 可以看到实际函数签名是一个三参重载speech2txt(audioOrOptions, optionsOrTestMode, testModeFlag)运行时按参数类型做归一化第一个参数若是普通对象plain object整包视为options否则视为source并自动经过toDataUriIfBlob处理第二个参数若是普通对象则合并进options若是布尔值则视为testMode第三个参数若为布尔值覆盖testModeoptions.audio被当作options.file的别名源码中赋值后即删除该字段见 stt.js这一行为也有对应测试ai.test.js。如果完全不带任何参数调用SDK 会直接抛出{ code: arguments_required }当所有输入来源都不存在时会抛出{ code: audio_required }。参数详解sourceString | File | Blob除非已在 options 中提供否则必填待转写的音频可接受以下任意形式Puter 路径如~/Desktop/meeting.mp3Data URL如data:audio/wav;base64,...File或Blob对象会被自动转换成 Data URL远程 HTTPS URL。当省略source时需要通过options.file或options.audio提供音频。optionsObject可选用于精细调节转写行为file/audioString | File | Blob传入音频输入的另一种方式。providerString使用的 STT 提供方openai默认或xai。别名whisper、grok、x-ai同样被接受其余取值会以bad_request错误拒绝。别名的正式解析发生在后端 providerAliases.tsSDK 端不重复维护别名表这样新增别名或修正对旧版打包客户端也能即时生效。modelString可选gpt-4o-mini-transcribe、gpt-4o-transcribe、gpt-4o-transcribe-diarize、whisper-1或任意后端后续支持的模型。默认在转写场景为gpt-4o-mini-transcribe翻译场景默认为whisper-1。translateBoolean设为true强制输出英文走后端 translations 端点。前端会把translate折成驱动方法名translatetrue时调用驱动translate方法否则调用transcribe见 stt.js。response_formatString期望的输出形态例如json、text、diarized_json、srt、verbose_json、vtt是否可用取决于模型。当取text时SDK 会直接把结果中的文本字符串返回见 stt.js。languageString输入音频的语言 ISO 代码提示。promptString对支持 prompt 的模型提供的额外上下文除gpt-4o-transcribe-diarize外均支持。temperatureNumber支持的模型上的采样温度0–1。logprobsBoolean在支持的位置请求 token 对数概率。timestamp_granularitiesArrayString在支持的模型当前为whisper-1上请求segment或word级别时间戳。chunking_strategyStringgpt-4o-transcribe-diarize输入时长超过 30 秒时必须提供推荐auto。known_speaker_names/known_speaker_referencesArray可选的说话人参照信息编码为 Data URL。extra_bodyObject原样透传给 OpenAI API 的实验性开关。streamBoolean为未来的流式转写预留当前不支持流式。test_modeBoolean为true时不消耗额度并返回示例响应默认false。xAI 专有参数当provider: xai时生效languageString语言代码如en、fr。当format为true时启用文本格式化。formatBoolean为true时启用反向文本归一化Inverse Text Normalization把数字/货币还原为书写形式。需要提供language。diarizeBoolean为true时单词附带speaker字段标识检测到的说话人。multichannelBoolean为true时独立转写每个音频声道。channelsNumber音频声道数2–8。多声道裸音频必填。audio_formatString无文件头的裸音频格式提示pcm、mulaw、alaw。sample_rateNumber采样率Hz。裸音频必填。testModeBoolean可选为true时跳过真实 API 调用返回一份静态示例转写文本便于在不消耗额度的情况下联调开发见文档中的“test mode”示例与 stt.js 中透传给makeDriverMethod的testMode参数。返回值与 Speech2TxtResult返回一个Promise结果形态取决于请求当response_format: text时返回字符串其余情况包括不传 options 直接传裸source返回 Speech2TxtResult 对象包含转写载荷按所选模型与格式不同可能含说话人分段、时间戳等。Speech2TxtResult的主要属性包括textString从音频转写出的文本。languageString检测或指定的音频语言。segmentsArray可选包含详细转写信息的分段对象数组。durationNumber可选音频时长秒取决于提供方如 xAI 会返回。wordsArray可选逐词时间戳对象数组如 xAI 会返回每个词含text、start、end当diarize: true时还含speaker字段。底层原理一次调用如何走完前端到驱动要理解本接口的能力边界值得看一下它背后的三层结构第一层SDK 客户端。stt.js 负责参数归一化、Blob 到 Data URL 的转换以及 25 MB 的输入上限检查const MAX_INPUT_SIZE 25 * 1024 * 1024; const STT_DRIVER ai-speech2txt;当options.file是data:前缀字符串且其字节数超过 25 MB 时会抛出{ code: input_too_large }。随后通过utils.makeDriverMethod发起puter-speech2txt接口、ai-speech2txt驱动、transcribe/translate方法的调用。第二层统一驱动。后端 SpeechToTextDriver.ts 定义了transcribe、translate、list_models等接口方法把请求路由到已注册的提供方。它有一个值得关注的设计无论后端是否配置了对应密钥提供方都会注册以便模型目录始终可被list_models列出没有配置密钥的提供方会在真正调用时报错。list_models默认只列默认提供方的模型传provider: all可聚合所有已配置提供方的模型见 SpeechToTextDriver.ts。第三层别名归一化与错误码。后端 providerAliases.ts 声明合法提供方集合为[openai, xai]默认提供方是openaiwhisper→openai、grok/x-ai→xai同时还兼容老 SDK 把提供方写进驱动槽位的写法openai-speech2txt、xai-speech2txt。若传入无法识别的提供方名驱动会抛出 HTTP 400、legacyCode: bad_request的错误见 SpeechToTextDriver.ts。由于解析逻辑放在后端新别名无需升级前端 SDK 即可对所有客户端生效。完整可运行示例示例一转写一个文件官方文档示例可直接在浏览器运行html body script srchttps://js.puter.com/v2//script script (async () { const transcript await puter.ai.speech2txt(https://assets.puter.site/example.mp3); puter.print(Transcript:, transcript.text); })(); /script /body /html说明js.puter.com/v2/是云端托管的 puter.js SDK 入口在自托管场景中把它替换为你自己部署环境的 SDK 地址即可调用方式不变。示例二翻译成英文并启用说话人分离html body script srchttps://js.puter.com/v2//script script (async () { const meeting await puter.ai.speech2txt({ file: ~/test.mp3, translate: true, model: gpt-4o-transcribe-diarize, response_format: diarized_json, chunking_strategy: auto }); meeting.segments.forEach(segment { console.log(${segment.speaker}: ${segment.text}); }); })(); /script /body /html注意这里同时用到了几项关键约定translate: true走翻译端点、gpt-4o-transcribe-diarize提供说话人分离、diarized_json输出带speaker的分段、超过 30 秒的输入需要chunking_strategy: auto这类分块策略。逐字打印“说话人 文本”时正好对应返回对象里segments[].speaker与segments[].text字段。示例三使用 xAIGrok转写并读取逐词时间戳html body script srchttps://js.puter.com/v2//script script (async () { const transcript await puter.ai.speech2txt({ file: https://assets.puter.site/example.mp3, provider: xai, language: en, format: true }); puter.print(Transcript:, transcript.text); puter.print(Duration:, transcript.duration s); if (transcript.words) { transcript.words.forEach(w { puter.print( ${w.start.toFixed(2)}s - ${w.end.toFixed(2)}s: ${w.text}); }); } })(); /script /body /html这个例子演示了 xAI 特有能力的组合用法language指定语言后format: true才会把数字/货币等还原为书面写法返回结果中duration与逐词数组words含start/end都由 xAI 提供。示例四开发期使用 test modehtml body script srchttps://js.puter.com/v2//script script (async () { const sample await puter.ai.speech2txt(~/test.mp3, true); console.log(Sample output:, sample.text); })(); /script /body /htmlspeech2txt(~/test.mp3, true)中第二个布尔参数即testMode无需真实音频、不消耗额度即可先打通页面展示、UI 排版等开发流程。以上四个示例在仓库中还有对应的可交互 Playground 页面分别是 ai-speech2txt.html 与 ai-speech2txt-xai.html。实用边界与注意事项结合文档与 stt.js 的实现实际开发中有几个容易踩坑的点值得记住25 MB 输入上限Data URL 形式的输入超过 25 MB 会被 SDK 直接拦截input_too_large长音频请先切分或压缩。提供方别名的“宽容”与“严格”whisper、grok、x-ai都能用但拼写错误或未知名称会收到bad_requestHTTP 400x-ai的正确写法是带连字符的小写形式。translate决定底层方法该开关不仅影响输出语言还会让请求改走驱动的translate方法因此翻译模式下默认模型是whisper-1而非gpt-4o-mini-transcribe。长输入的说话人分离gpt-4o-transcribe-diarize对超过 30 秒的输入要求显式chunking_strategy官方建议auto。response_format: text会改变返回值类型此时拿到的是字符串而非对象类型签名上对应TextFormatSpeech2TxtOptions重载返回Promisestring见 stt.js。流式尚未开放stream字段为未来预留目前传入不会获得流式响应请勿依赖。凭据缺失时行为从驱动源码结构看提供方在未配置密钥时仍会注册、可被list_models列出但真实调用会在运行期被拒绝——如果你在自托管环境遇到这类报错应优先检查该提供方的服务端配置。若想进一步了解返回对象的完整字段与类型说明可继续阅读仓库内的 Speech2TxtResult 文档并把示例代码与 ai.test.js 中的断言结合起来验证你理解的请求参数结构如driver、method、args的形态。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考