饭耳「自建服务」转写接口说明
饭耳按 OpenAI 的语音转文字接口 POST /v1/audio/transcriptions 对接你自己的转写服务。服务端用什么软件、什么模型都行,请求和返回按下面来就能接。没有转写接口、只有对话接口(/v1/chat/completions)能收音频的大模型也能接,见「对话接口(音频大模型)」。
饭耳发什么
- 地址:设置里填到
/v1为止,比如https://asr.example.com/v1,饭耳在后面接/audio/transcriptions。也可以把服务商文档、控制台里的完整接口地址整段粘进来(以/audio/transcriptions结尾,可以带?api-version=这类参数,比如 Azure OpenAI 的部署地址),饭耳认出结尾换成要发的接口,参数原样带上;地址里不收密钥参数(key=、token=这类),密钥填在「密钥」一栏。https 和 http 都收(http 不加密,公网上能用 https 就用 https);https 要正规证书,不收自签名证书。 - 一块录音(通常 15 分钟)发一次
POST,multipart/form-data。每次都带请求头Prefer: respond-async:服务支持异步就先回任务号、饭耳过一会再来查(见「异步」,推荐);不认这个头、照旧同步回结果的,饭耳等着,最多等 600 秒。没有流式。「测试连接」测出只回文字的服务不整块发,切成小段一段发一次(见「只回文字的服务」)。 - 填了密钥才带
Authorization: Bearer <密钥>,同时带api-key: <密钥>(交任务和查任务都带;有的服务只认api-key);没填两个都不带。地址是 Azure 上的部署(*.openai.azure.com、*.cognitiveservices.azure.com等)只带api-key(Azure 的Authorization: Bearer只收 Entra 令牌)。模型名没填、地址里有/deployments/<部署名>/的,用部署名当模型名。 - 整块送时一次就是一整块:通常 900 秒(15 分钟,切块结束可能多出零点几秒)的录音,文件约 7MB(约 7,000,000 字节)(AAC 单声道,实测平均每小时 29MB)。服务、反向代理的单次时长和上传体积上限都要放得下,体积建议留到 15MB 以上。收不下就回 HTTP
413,正文用错误体写清上限(如{"error":{"message":"audio longer than 300 seconds","code":"audio_too_long"}});饭耳把它显示成「你的服务拒收了这段录音」,带上状态码和原话,不会自己改小再送。
| 表单字段 | 值 |
|---|---|
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 时用它的标点切句 |
verbose_json和diarized_json按同一张表读:开着「分说话人」时回带speaker的verbose_json也行;关着时服务自己带了speaker也照样用。- 说话人标签只在这一块里有效:饭耳按出现顺序编成第 1、2、3 个人;跨块是不是同一个人由饭耳自己的声纹判断,服务不用管,也不用跨块保持一致。
- 分段没有长度和条数限制,按时间先后排。建议一句一段(几秒到二三十秒):饭耳里点一句话会从那句开头播放,一整块只回一段也能转,但只能从头播放。
- 某一句的 start、end 缺了或超出范围,这一块整块算失败,不会只丢那一句。
异步(推荐,跑得慢的模型必用)
一块 15 分钟的录音,CPU 或小显卡上的模型常要转好几分钟,同步等容易超时(反向代理、隧道、手机切网都会断)。支持异步的服务交上就回,饭耳过一会再来查,连接不用一直开着;App 被挂起、断网,回来凭任务号接着查,不重交。
交任务:饭耳的 POST {地址}/audio/transcriptions 带 Prefer: respond-async,表单和同步一样。服务回:
- HTTP
202,JSON{"id": "任务号", "status": "queued"}(status也可以是processing)。任务号是字符串,只用字母、数字和-._~最稳。 - 可以带
Location响应头指明查询地址(相对路径或同一个服务的完整网址;放在反向代理的子路径后面时要写对前缀,不确定就别带)。Location 必须与提交地址的协议、主机、端口相同;指向其他服务的会报错,不会把密钥带到别处。
查任务: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 放进出错详情;点重试会重新交 |
- 只认这四个
status,别的值饭耳报「任务状态不认识」,不会一直等。 - 找不到这个任务回 HTTP
404:饭耳重交一次;重交的也找不到就报失败,不再交(重交会让服务重算一遍)。 - 任务状态和结果至少保留 24 小时;即使已经被查询到也不要立即删除:手机刚收到结果时可能被挂起,恢复后仍需查询。处理完即可删除临时录音,结果按保留期限清理。
- 没带
Prefer: respond-async的请求照旧同步回结果(老版本饭耳这样发)。 - 只回文字的服务切小段送时,每段也照这个流程交和查。
- 「测试连接」也走异步:交上测试音以后在设置页查到完成:测试音约 6 秒,每次请求最多等 30 秒,异步查询最多等 60 秒;没转完会提示,不会一直等 600 秒。
密钥校验、结果按 24 小时清理、同一时间只跑一个任务(显存不够时)请按自己的情况加。
只回文字的服务
只回整段文字、没有每句时间的服务也能接:返回里没有 segments、或 segments 空着却有 text,或者不认 verbose_json、diarized_json 但认 json。
- 在设置里点「测试连接」时饭耳测出来并记住;换了地址、模型或「分说话人」开关,会重新测。
- 以后每块:用手机自带的声音识别找出哪里有人说话,在停顿处切成最长约 30 秒的小段,没人说话的部分不发;每段发一次,
response_format用测出来的那种(一般是json),不带chunking_strategy。 - 返回只要顶层的
text(字符串)。饭耳按句末标点(。!?!?)分句、按字数估每句的时间(点一句播放会差一两秒),说话的人由手机按声音认。 - 一块要发二三十到四十次请求(15 分钟),服务要撑得住连着来的请求;支持异步的每段也是交了再查。
对话接口(音频大模型)
服务没有 /audio/transcriptions、只有 OpenAI 对话接口 POST /v1/chat/completions 能收音频的(比如小红书 dots3-note-prev,官方接口或自己用 vLLM、SGLang 部署的)也能接:设置里照样填到 /v1 为止的地址和模型名。
- 「测试连接」先照旧测转写接口;它回
404、405、501、401、403(有的网关对不存在的路径也先回 401/403),或回400/422但不是不认response_format(比如 vLLM 说这个模型不支持转写),饭耳再试对话接口,转出字就记住,以后都走对话接口。429、413、连不上、超时不会改试对话接口。 - 对话接口也不通时只报一边的错,另一边放进详情:对话接口也回
404、405、501(两条路都不在,多半地址填错),或两边都回401/403,报转写接口那次;其余(对话接口这条路在,回了密钥不对、限流、参数不对、服务出错等)报对话接口的错。 - 录音在手机上按停顿切成最长约 30 秒的小段,没人说话的部分不发,每段发一次(16kHz 单声道 WAV);一块 15 分钟要发三四十次。所有对话接口的请求任意一分钟最多约 60 次,多的排队等。每次最多等 300 秒。
- 鉴权:填了密钥同时带
Authorization: Bearer <密钥>和api-key: <密钥>;没填都不带。 - 请求正文是 JSON:
model填设置里的模型名;messages两条,system一条是英文转写指令(原文见下一条),user一条的content是一段音频加一句{"type": "text", "text": "Transcribe this audio verbatim."};temperature为0,stream为false,max_tokens为4096。 - 转写指令原文:
You are a speech-to-text transcriber. Transcribe the speech in the user's audio verbatim, word for word, in the language it is spoken, with natural punctuation. Do not translate, summarize, correct, or answer anything said in the audio. Output only the transcript text, with no explanations, labels, timestamps, or quotation marks. If no one speaks, output nothing. - 音频有两种写法,测试连接时按顺序试,哪种转出字就一直用哪种。
- 写法一(先试):音频放
{"type": "audio_url", "audio_url": {"url": "data:audio/wav;base64,…"}},正文里同时带"chat_template_kwargs": {"enable_thinking": false}关掉深度思考。小红书 dots 官方接口(2026-10-23 用真密钥测通)、vLLM、SGLang 收这种。 - 写法二(写法一不行再试):音频放
{"type": "input_audio", "input_audio": {"data": "不带前缀的 base64", "format": "wav"}},不带chat_template_kwargs。OpenAI 官方是这种,vLLM 也收;dots 官方接口不收(回 400)。 - 返回:HTTP 200,饭耳只读
choices[0].message.content(字符串,或[{"type": "text", "text": "…"}]拼起来)。<think>…</think>会去掉,reasoning_content不看。空文字当这一段没人说话。finish_reason是length(写到上限被截断)时这一段算失败,不存半截。 - 文字按句末标点分句、按字数估每句的时间,说话的人由手机按声音认(和「只回文字的服务」一样)。所以 system 提示里要求只出原话:模型加了说明或回答了音频里的问题,这些字会进转写。
- 出错时回非 200,带
{"error": {"message": "…", "code": "…"}}(code 是字符串或数字都行);饭耳把它放进出错详情。
出错时
- 回非 200 的状态码,最好带 OpenAI 格式的错误体
{"error":{"message":"…","type":"…","code":"…"}},饭耳把 code 和 message 放进出错详情。 - 不认要的
response_format时回 400 或 422,正文里写出response_format或格式名:饭耳会提示「关掉/打开『分说话人』再试」。 - 不收
prompt时最好回 400 或 422,错误体error.param写prompt(没有param时正文点名prompt,FastAPI 类 422 的detail[].loc含prompt也行)。「测试连接」带着prompt回 400、422 或 5xx(笼统的报错也算)时,不带prompt再测一次:还不通就报不带的那次;通了,点名prompt的记下不收,没点名的再带prompt测一次确认(防第一次碰上临时出错),还不通才记不收。记下不收以后都不带常用词。测试连接以后又不收了,饭耳这一块报PromptRejected,提示点「测试连接」重测,不会自动去掉重发(整块要再传一遍)。OpenAI 的gpt-4o-transcribe-diarize官方写明不支持prompt。 - 其他 4xx(录音太长、太大、你自己定的限制等):饭耳提示「你的服务拒收了这段录音」,卡片上带状态码和你的错误码、原话,详情可以整段交给帮你搭服务的 AI;这不算饭耳出错。没有自定义错误码的 401、403 仍按密钥不对提示。
- 没测过就只回整段文字(没有
segments,或segments空着却有text):饭耳提示「这个服务只回文字,没有每句时间」,点「测试连接」重测后改切小段送;这块不会当成没人说话。 - 「测试连接」发一句约 6 秒的合成语音(m4a,不是录音),带上
prompt(设置里的常用词,还没有常用词就带测试词「饭耳」):回了带时间的segments(或能拼成句子的words)就整块送;回了文字没有每句时间、或 400/422 不认这个格式,再用response_format=json发一次,回了文字就记成只回文字;转写接口不通(见「对话接口」)就改用同一句话的 WAV 试对话接口;最后不带密钥发一次,也回 200 会提示「服务没设密码」。
已核对的服务(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)。阿里云百炼、火山引擎、腾讯云饭耳已经单独接好,不走这里。