饭耳「自建服务」转写接口说明

饭耳按 OpenAI 的语音转文字接口 POST /v1/audio/transcriptions 对接你自己的转写服务。服务端用什么软件、什么模型都行,请求和返回按下面来就能接。没有转写接口、只有对话接口(/v1/chat/completions)能收音频的大模型也能接,见「对话接口(音频大模型)」。

饭耳发什么

表单字段 值
file 文件名 audio.m4a,Content-Type: audio/mp4(AAC 单声道;默认原样,15 分钟约 7MB,不压缩)
model 设置里填的模型名
response_format 「分说话人」关:verbose_json;开:diarized_json;只回文字的服务切小段送时用测试连接测出的那种(一般是 json)
temperature 0
language 转写语言(设置 › 语音转文字 › 转写语言,2026-10-22 起),ISO-639-1:zh(繁体)、en、ja、ko、es、fr、de、it、pt;转写语言是简体中文时不发,服务自己认(中英夹杂、粤语不被强制成普通话)
chunking_strategy 只在整块送 diarized_json 时发,值 auto(OpenAI 的分人模型超过 30 秒必须带);切小段送不发
prompt 常用词(2026-11-03 起):设置 › 常用词里的人名、地名、品牌、产品名,只有词,不是指令;中文用「,」隔开、「。」结尾(日文「、」,其他语言「, 」),最多 200 字,本人自己加的排在前面。每块、每段都带(不跨请求记)。「测试连接」测出服务收这个字段才带,见「出错时」;没有常用词不发

不发 timestamp_granularities、stream。服务不认识的字段请忽略,不要报错(OpenAI 也是忽略的,2026-10-18 实测)。

prompt 怎么用由服务定:当热词或上文(Qwen3-ASR 类当上下文,Whisper 类当前文)都行。Whisper 类模型会照 prompt 的写法和标点出字,所以饭耳把词拼成带标点的一句;不想用就忽略这个字段。

饭耳要什么返回

HTTP 200,一个 JSON 对象。饭耳只读下表几样;task、language、duration、usage、id、type、words 等有没有都行。

字段 要求
segments 有就整块送:数组,一句一项;没人说话回 []。没有就按只回文字的服务切小段送(见下)
segments[].start、segments[].end 有 segments 时必须有,数字,单位秒,从这块录音开头算;0 ≤ start ≤ end ≤ 14400
segments[].text 有 segments 时必须有,字符串
segments[].speaker 可选;字符串("A"、"SPEAKER_00"、"S01")或整数(0、1)都行;没有就按不分说话人显示
words 可选;没有 segments 时才用:逐词时间数组,每项 word(字符串)、start、end(秒,0 ≤ start ≤ end ≤ 14400),OpenAI verbose_json 的写法;只在「分说话人」关(要 verbose_json)时这样读,diarized_json 要回 segments。饭耳按顶层 text 的句末标点(。!?!?,英文句号)把词拼成句子,一句的起止取这句第一个词和最后一个词,整块送,没有标点的长段满 20 秒后在逗号或停顿处断、满 30 秒硬断;说话人由手机按声音分(同只回文字的服务);只数字母、数字和汉字,words 和 text 的字要一个个对得上(比如一边「四百」一边「400」就对不上),对不上、时间不对就按只回文字处理
text 只回文字的服务必须有(整段文字);有 segments 时只用来分清「没人说话」和「有字没有每句时间」;只回 words 时用它的标点切句

异步(推荐,跑得慢的模型必用)

一块 15 分钟的录音,CPU 或小显卡上的模型常要转好几分钟,同步等容易超时(反向代理、隧道、手机切网都会断)。支持异步的服务交上就回,饭耳过一会再来查,连接不用一直开着;App 被挂起、断网,回来凭任务号接着查,不重交。

交任务:饭耳的 POST {地址}/audio/transcriptions 带 Prefer: respond-async,表单和同步一样。服务回:

查任务:GET {地址}/audio/transcriptions/{id}(有 Location 用 Location),带同样的 Authorization。交上即可查询;未完成时从约 3 秒间隔起退避,最长 30 秒一次;一块最多查 24 小时。服务回 HTTP 200 和下面之一:

回包 意思
{"id":"…","status":"queued"} 或 "processing" 还在排队或在转,过一会再查(回 HTTP 202 也算还在转)
{"id":"…","status":"completed", …} 转完了:其余字段和同步的返回一样(segments、text,见「饭耳要什么返回」)
{"id":"…","status":"failed","error":{"message":"…","code":"…"}} 转失败了:饭耳把 code 和 message 放进出错详情;点重试会重新交

密钥校验、结果按 24 小时清理、同一时间只跑一个任务(显存不够时)请按自己的情况加。

只回文字的服务

只回整段文字、没有每句时间的服务也能接:返回里没有 segments、或 segments 空着却有 text,或者不认 verbose_json、diarized_json 但认 json。

对话接口(音频大模型)

服务没有 /audio/transcriptions、只有 OpenAI 对话接口 POST /v1/chat/completions 能收音频的(比如小红书 dots3-note-prev,官方接口或自己用 vLLM、SGLang 部署的)也能接:设置里照样填到 /v1 为止的地址和模型名。

出错时

已核对的服务(2026-10-18)

「实测」是真调了接口;「源码」「文档」是看了对方的代码或官方文档,没有真调。

服务 「分说话人」关 「分说话人」开 依据
OpenAI whisper-1 能用(不分人) 400,关掉即可 实测
OpenAI gpt-4o-transcribe-diarize 400,要打开 能用,speaker 是 A、B 实测
OpenAI gpt-4o-transcribe、gpt-4o-mini-transcribe 只回文字:切小段送 只回文字:切小段送 实测只回文字;切小段送没真调
vLLM + Whisper 能用;解码时长上限默认 600 秒,要调到 900 以上 不支持 源码
vLLM + MOSS-Transcribe-Diarize 不支持 能用,speaker 是 S01… 源码
vLLM + Qwen3-ASR 只回文字:切小段送 只回文字:切小段送 源码
speaches(原 faster-whisper-server) 能用 422 源码
LocalAI(2026-05 以后的版本) 能用;更早的版本时间是纳秒,用不了 400 源码
whisper.cpp server(加 --request-path /v1 --inference-path /audio/transcriptions --convert) 能用 只回文字:切小段送,或关掉 源码
WhisperLiveKit(加 --diarization) 能用 能用 源码
FunASR 官方 openai_api server 能用 只回文字:切小段送,或关掉 源码
Groq 能用 不支持 文档
Together AI 能用(不分人;它的说话人要另传 diarize=true,饭耳不发) 不支持 文档
Mistral Voxtral 多半只回文字(要另传 timestamp_granularities=segment 才有分句,饭耳不发):切小段送 同左 文档
硅基流动 SiliconFlow 只回文字:切小段送 只回文字:切小段送 文档

走对话接口的(2026-10-22 看过官方文档,没真调):小红书 dots3-note-prev(官方接口只认 api-key 请求头;官方文档没写收不收内嵌音频),自己用 vLLM、SGLang 部署的音频大模型。

不是这个接口的服务接不上:ElevenLabs、Deepgram、AssemblyAI,以及 whisper-asr-webservice(/asr)。阿里云百炼、火山引擎、腾讯云饭耳已经单独接好,不走这里。