FunASR OpenAI 兼容 API 的 OpenAPI 规范详解从 schema 导入到客户端生成与工作流接入【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASRFunASR 在 examples/openai_api 目录下提供了一套 OpenAI 兼容的语音转写服务/v1/audio/transcriptions并配套一份静态 OpenAPI 规范openapi.json用于在真正接入应用、API 网关、工作流引擎或 SDK 生成器之前先查看、mock、文档化甚至直接导入这套语音 API。本文以这份规范文档为骨架结合仓库中的服务端源码与测试脚本逐层拆解其端点契约、请求/响应字段语义、模型别名体系、与打包版funasr-server的边界差异并给出可复制运行的验证命令与工作流接入方案。读完本文你将能够基于 OpenAPI schema 生成客户端、在 Swagger/Redoc/Postman 中导入调试、把 FunASR 转写能力接入 Dify/n8n/Agent 框架并正确理解verbose_json中各字段的真实语义。一、这份规范是什么静态 spec 与运行时 schema 的关系规范文档开宗明义当你希望在接入应用、API 网关、开发者门户、工作流引擎或 SDK 生成器之前先查看、mock、导入或发布 FunASR 语音 API 时直接使用仓库内的openapi.json即可。与之并存的是运行时动态产物运行中的 FastAPI 服务会在/docs暴露 Swagger UI同一服务在/openapi.json暴露实时生成的 schema。而仓库内 checked-in 的openapi.json是一份便携参考规范它描述的是该目录下示例服务server.py的公开集成面。文档特别强调了两者的取舍运行时 FastAPI schema 可能包含框架级的校验细节例如字段校验报错结构而这份静态规范刻意保留了更小、更稳定的公共集成面便于在服务尚未启动时就完成评估、mock 与导入。从源码看server.py 中app FastAPI(titleFunASR OpenAI-Compatible API, version1.0.0)定义了与静态规范一致的标题与版本号三个端点/v1/audio/transcriptions、/v1/models、/health的实现与规范中的 paths 一一对应这保证了「规范先行、代码落地」的一致性。二、五种导入与消费方式原文档以表格形式给出了规范的五种典型消费路径这里完整保留并补充落点工具使用方式Swagger Editor 或 Redoc导入openapi.json查看/health、/v1/models和/v1/audio/transcriptions三个端点Postman偏好 schema 驱动集合时可导入openapi.json想直接 smoke test 可使用现成的 Postman 集合仓库内另有funasr-openai-api.postman_collection.json可一键导入Dify、n8n 或内部工作流工具结合规范中的 multipart 请求结构与 workflow recipes 配置 HTTP 节点API 网关或内部开发者门户发布该规范并把 server URL 改为你的 FunASR API 可访问地址客户端生成生成内部小客户端并确保 multipartfile字段映射为二进制上传值得注意的是规范中的file字段类型为string, format: binary见 openapi.json这意味着由 schema 自动生成的客户端必须把文件上传映射为 multipart 二进制体而不是普通字符串参数——这是自动生成代码时最容易被忽略的一环。三、Server URL 与端点一览规范内置了两个示例服务器地址http://localhost:8000本地开发http://funasr-api:8000示例 Docker Compose 或内部服务名对应 docker-compose.yml 中的服务名funasr-api实际使用时替换为你的应用、容器或工作流运行环境能够访问到的地址即可。规范定义的三个核心端点端点方法用途/healthGET就绪检查、所选设备、已加载模型与可用别名/v1/modelsGETOpenAI 风格模型列表包含ready标志/v1/audio/transcriptionsPOSTmultipart 音频转写使用response_formatverbose_json返回 segments对照 server.py 的/health实现其返回体包含status、device、models_loaded当前已加载进内存的模型、models_available配置中可用的全部模型别名与规范中HealthResponseschema 完全一致。/v1/models则遍历MODEL_CONFIGS为每个别名返回id、object、created、owned_by、ready五个字段server.py其中ready表示该别名是否已加载进内存——这是区分「可用」与「已就绪」的关键字段。四、Multipart 转写请求字段详解原文档给出了四个请求字段的概览表这里结合 openapi.json 中的TranscriptionRequestschema 与源码实现逐字段展开字段类型必填说明filebinary是音频文件如 wav、mp3、flac、m4a、ogg 或 webmmodelstring否默认sensevoice/v1/models也会列出用于离线长音频与原生匿名说话人标签的moss-transcribe-diarizelanguagestring否可选语言提示response_formatstring否使用json或verbose_json在源码层面server.py 的transcribe处理器对这四个字段做了如下处理fileUploadFile File(...)接收上传按原始文件名后缀无后缀则回退为.wav写入临时文件转写完成后在finally中清理删除model先经过resolve_openai_transcription_model解析见下文「兼容别名」小节再校验是否在MODEL_CONFIGS中未知别名直接返回400detail中列出可用别名language可选传入后作为generate_kwargs[language]透传给底层模型未传时在响应中以auto回显response_formatjson时只返回{text: ...}verbose_json时返回带segments的扩展结构。需要特别强调这也是规范文档反复警示的语义边界response_formatverbose_json只是选择响应格式它并不会开启说话人分离diarization也不会强制生成时间戳。示例服务仅在模型返回sentence_info时才将其转换为segments否则返回segments[]speaker标签可能缺失或为null。五、响应结构json 与 verbose_json 的 schema 语义规范中的响应通过oneOf引用两种 schemajson模式TranscriptionTextResponse仅含必填的text字段值为清洗后的转写文本。规范中的示例值为{text: Welcome to FunASR.}。verbose_json模式VerboseTranscriptionResponse必填字段为text、segments、language、duration、model。规范给出的完整示例{ text: Welcome to FunASR., segments: [ { start: 0.0, end: 1.6, text: Welcome to FunASR., speaker: null } ], language: auto, duration: 0.843, model: sensevoice }其中segments数组的每个元素TranscriptionSegment包含start、end、text与可空的speaker。对照 server.pyverbose 响应的构造逻辑如下text来自clean_text(result[0][text])即用正则re.sub(r\|[^|]*\|, , text)剥离 SenseVoice 输出的|...|富标签如情感、事件标签后取纯文本segments仅在sentence_info in result[0]时生成且将 SDK 返回的毫秒级start/end除以 1000 转换为秒speaker取自seg.get(spk, None)duration是generate()调用前后的墙钟耗时排除首轮模型加载不是音频时长——规范文档与源码 docstring 均对此有明确界定。六、模型别名体系MODEL_CONFIGS 与 /v1/models规范文档指出model字段默认值为sensevoice并提示/v1/models会列出moss-transcribe-diarize。这背后对应 server.py 中的MODEL_CONFIGS字典其定义的五个别名及组合如下别名模型组合说明sensevoiceSenseVoiceSmall FSMN-VADmax_single_segment_time30000示例服务的启动默认与请求默认paraformerparaformer-zh FSMN-VAD CT 标点中文转写内置标点模型paraformer-enparaformer-en FSMN-VAD英文转写仅示例服务注册打包版funasr-server没有该内置别名fun-asr-nanoFun-ASR-NanoHF hub trust_remote_code FSMN-VADLLM 类 ASR 实验本示例走AutoModel而非 vLLM 路由moss-transcribe-diarizeOpenMOSS 第三方模型HF trust_remote_code锁定 revision离线多说话人转写分离原生返回时间戳与匿名说话人标签需要厘清的两点契约边界启动预加载与请求默认是两个独立设置示例服务中--model启动参数与请求中省略的 multipartmodel都默认sensevoice而打包版funasr-server启动--model auto时设备串以cuda开头选fun-asr-nano否则选sensevoice请求默认值则独立地是fun-asr-nano。因此规范文档建议请求中显式指定model并以部署实例实际的/v1/models返回为准。MOSS 的独立环境要求MOSS 需要隔离的 Transformers 环境使用funasr-server --model moss-transcribe-diarize --device cuda:0启动并请求response_formatverbose_json详见 MOSS 部署指南。其说话人标签仅在同一录音内匿名有效不是跨录音的身份识别。七、对照运行中的服务验证规范原文档给出的验证流程如下这里补充完整的环境准备与冒烟测试cd examples/openai_api python server.py --model sensevoice --device cuda --port 8000 curl -fsS http://localhost:8000/openapi.json /tmp/funasr-openapi-live.json在无 GPU 环境下可将--device替换为cpu速度较慢但路径完整。启动后可用三个 GET 端点做快速检查curl http://localhost:8000/health curl http://localhost:8000/v1/models curl http://localhost:8000/openapi.json仓库还提供了两条冒烟测试路径可直接验证「健康检查 模型列表 转写」全链路bash smoke_test.sh # 跨平台替代不依赖 curl/bash python smoke_test.pysmoke_test.py 是纯标准库实现它会按需下载公开中文样例音频BAC009S0764W0121.wav手工构造 multipart 请求体--boundaryfile/model/response_format字段依次打印/health、/v1/models与转写结果 JSON。其命令行参数--base-url、--model、--response-format、--timeout均支持环境变量覆盖非常适合 CI 与跨平台脚本调用。八、API 契约边界示例 server.py 与打包 funasr-server 的差异规范文档多次强调本规范描述的是示例服务与仓库打包的funasr-server实现见funasr/bin/_server_app.py并非同一实现。理解这份边界对避免误用至关重要维度示例server.py打包funasr-server请求表单字段仅file、model、language、response_format额外支持spktrue为非常规原生分离模型开启外部说话人流水线默认Falseduration语义generate()墙钟耗时排除首轮加载非音频时长音频时长秒音频元数据不可读时回退为 0segments来源模型返回的sentence_info转换否则[]可用段或基于文本/音频时长的粗粒度合成段非词级强制对齐verbose 附加字段顶层含model含task及段级id/words无顶层model兼容别名whisper-1映射到启动所选模型不运行 OpenAI Whisper同左SDK 选项use_itn、热词、timestamp/ctc_timestamps、原始数组等不暴露为表单字段同左规范文档还警示SDK 输出中的timestamp、Nano 的timestamps/ctc_timestamps不会被自动转换为 HTTP 段language在示例服务中只是提交的提示或auto并非检测到的语言。因此消费端必须以运行实例的/openapi.json为准而不是仅依赖这份静态示例 schema。更完整的字段对照表见 CLIENTS.md 的 Response formats 小节。九、客户端与工作流接入模式基于这份规范可以衍生出多种实际接入形态完整配方见 CLIENTS.md 与 WORKFLOWS.mdOpenAI Python SDK注意这是独立的 HTTP 客户端包openai不是 FunASR 的进程内 SDK本地开发时api_key用占位符即可服务端并不校验from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keynot-needed) with open(meeting.wav, rb) as audio: result client.audio.transcriptions.create( modelsensevoice, fileaudio, response_formatverbose_json, ) print(result.text) for segment in getattr(result, segments, []): print(segment)Agent 工具函数模式LangChain、LlamaIndex、AutoGen、CrewAI 等均可注册为普通工具from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyx) def transcribe_for_agent(audio_path: str) - str: with open(audio_path, rb) as audio: result client.audio.transcriptions.create(modelsensevoice, fileaudio) return result.textDify / n8n 低代码工作流multipart HTTP 节点设置项值方法POSTURLhttp://funasr-host:8000/v1/audio/transcriptionsBody 类型multipart/form-data文件字段file文本字段modelsensevoice、response_formatverbose_json结果路径text作为转写文本segments可能为空说话人标签是条件性的n8n 的 OpenAI Audio 节点若固定发送modelwhisper-1FunASR 会将该兼容别名映射到启动所选模型——这只代表别名映射不会加载任何 Whisper 权重。工作流容器内的localhost指向容器自身跨容器访问需使用宿主/Compose 服务名/Kubernetes Service 地址。Postman可导入 funasr-openai-api.postman_collection.json设置集合变量FUNASR_BASE_URL与MODEL_ALIASsensevoice后即可运行健康检查、模型列表、verbose 转写与纯文本转写四个请求详见 POSTMAN.md。十、安全与部署注意规范文档与配套 SECURITY.md 反复强调示例服务没有任何内置认证或上传大小限制api_keynot-needed并不构成认证服务默认监听0.0.0.0本地联调请保持在 loopback--host 127.0.0.1。在对外共享之前必须通过反向代理/API 网关补上 TLS、认证、上传大小/超时/速率限制、音频与转写文本留存策略并限制/health、/v1/models、/openapi.json、/docs等元数据路由的公开访问。Docker 部署详见 README.md 与 Dockerfile默认以 CPU 模式启动便于在无 NVIDIA Container Toolkit 的机器上直接运行cd examples/openai_api cp .env.example .env FUNASR_HOST_PORT127.0.0.1:8000 docker compose up --build等效的一次性docker rundocker run --rm -p 127.0.0.1:8000:8000 \ -e FUNASR_DEVICEcpu \ -e FUNASR_MODELsensevoice \ funasr-api相关环境变量FUNASR_PORT默认 8000、FUNASR_DEVICE默认 cpu镜像具备 CUDA 依赖时才设为 cuda、FUNASR_MODEL默认 sensevoice。Kubernetes 场景可参考 kubernetes/README.md 的保守模板ClusterIP 持久化模型缓存 /health探针 /dev/shm内存卷并通过kubectl port-forward做私有验证。十一、常见问题排查SDK 报认证缺失本地开发传任意占位api_key即可服务端不校验400 unknown model调用/v1/models使用返回列表中的别名响应无segments确认response_formatverbose_json并检查模型是否返回sentence_infoverbose_json本身不会凭空生成时间戳或说话人标签首次请求很慢模型可能正在加载用--model sensevoice预加载并以/health作为就绪探针CUDA 不可用先用--device cpu验证 API 链路再排查驱动/运行时端口冲突改用--port 9000启动并以BASE_URLhttp://localhost:9000运行冒烟测试smoke_test.sh与smoke_test.py均支持该环境变量模型下载缓慢稳定网络重试或提前从 ModelScope/Hugging Face 预下载模型。最后回到本规范的定位openapi.json是一份面向集成者的稳定契约它刻意不随 FastAPI 框架细节漂移。以它为起点完成 mock、导入与客户端生成之后请务必以部署实例的实时/openapi.json与/v1/models做最终校验——静态规范保证的是「集成面稳定」运行时 schema 保证的是「与真实行为一致」两者结合才是正确的消费姿势。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 3:19:40 · 阅读 1.2k FunASR OpenAI 兼容 API 的 OpenAPI 规范详解：从 schema 导入到客户端生成与工作流接入
FunASR OpenAI 兼容 API 的 OpenAPI 规范详解从 schema 导入到客户端生成与工作流接入【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASRFunASR 在 examples/openai_api 目录下提供了一套 OpenAI 兼容的语音转写服务/v1/audio/transcriptions并配套一份静态 OpenAPI 规范openapi.json用于在真正接入应用、API 网关、工作流引擎或 SDK 生成器之前先查看、mock、文档化甚至直接导入这套语音 API。本文以这份规范文档为骨架结合仓库中的服务端源码与测试脚本逐层拆解其端点契约、请求/响应字段语义、模型别名体系、与打包版funasr-server的边界差异并给出可复制运行的验证命令与工作流接入方案。读完本文你将能够基于 OpenAPI schema 生成客户端、在 Swagger/Redoc/Postman 中导入调试、把 FunASR 转写能力接入 Dify/n8n/Agent 框架并正确理解verbose_json中各字段的真实语义。一、这份规范是什么静态 spec 与运行时 schema 的关系规范文档开宗明义当你希望在接入应用、API 网关、开发者门户、工作流引擎或 SDK 生成器之前先查看、mock、导入或发布 FunASR 语音 API 时直接使用仓库内的openapi.json即可。与之并存的是运行时动态产物运行中的 FastAPI 服务会在/docs暴露 Swagger UI同一服务在/openapi.json暴露实时生成的 schema。而仓库内 checked-in 的openapi.json是一份便携参考规范它描述的是该目录下示例服务server.py的公开集成面。文档特别强调了两者的取舍运行时 FastAPI schema 可能包含框架级的校验细节例如字段校验报错结构而这份静态规范刻意保留了更小、更稳定的公共集成面便于在服务尚未启动时就完成评估、mock 与导入。从源码看server.py 中app FastAPI(titleFunASR OpenAI-Compatible API, version1.0.0)定义了与静态规范一致的标题与版本号三个端点/v1/audio/transcriptions、/v1/models、/health的实现与规范中的 paths 一一对应这保证了「规范先行、代码落地」的一致性。二、五种导入与消费方式原文档以表格形式给出了规范的五种典型消费路径这里完整保留并补充落点工具使用方式Swagger Editor 或 Redoc导入openapi.json查看/health、/v1/models和/v1/audio/transcriptions三个端点Postman偏好 schema 驱动集合时可导入openapi.json想直接 smoke test 可使用现成的 Postman 集合仓库内另有funasr-openai-api.postman_collection.json可一键导入Dify、n8n 或内部工作流工具结合规范中的 multipart 请求结构与 workflow recipes 配置 HTTP 节点API 网关或内部开发者门户发布该规范并把 server URL 改为你的 FunASR API 可访问地址客户端生成生成内部小客户端并确保 multipartfile字段映射为二进制上传值得注意的是规范中的file字段类型为string, format: binary见 openapi.json这意味着由 schema 自动生成的客户端必须把文件上传映射为 multipart 二进制体而不是普通字符串参数——这是自动生成代码时最容易被忽略的一环。三、Server URL 与端点一览规范内置了两个示例服务器地址http://localhost:8000本地开发http://funasr-api:8000示例 Docker Compose 或内部服务名对应 docker-compose.yml 中的服务名funasr-api实际使用时替换为你的应用、容器或工作流运行环境能够访问到的地址即可。规范定义的三个核心端点端点方法用途/healthGET就绪检查、所选设备、已加载模型与可用别名/v1/modelsGETOpenAI 风格模型列表包含ready标志/v1/audio/transcriptionsPOSTmultipart 音频转写使用response_formatverbose_json返回 segments对照 server.py 的/health实现其返回体包含status、device、models_loaded当前已加载进内存的模型、models_available配置中可用的全部模型别名与规范中HealthResponseschema 完全一致。/v1/models则遍历MODEL_CONFIGS为每个别名返回id、object、created、owned_by、ready五个字段server.py其中ready表示该别名是否已加载进内存——这是区分「可用」与「已就绪」的关键字段。四、Multipart 转写请求字段详解原文档给出了四个请求字段的概览表这里结合 openapi.json 中的TranscriptionRequestschema 与源码实现逐字段展开字段类型必填说明filebinary是音频文件如 wav、mp3、flac、m4a、ogg 或 webmmodelstring否默认sensevoice/v1/models也会列出用于离线长音频与原生匿名说话人标签的moss-transcribe-diarizelanguagestring否可选语言提示response_formatstring否使用json或verbose_json在源码层面server.py 的transcribe处理器对这四个字段做了如下处理fileUploadFile File(...)接收上传按原始文件名后缀无后缀则回退为.wav写入临时文件转写完成后在finally中清理删除model先经过resolve_openai_transcription_model解析见下文「兼容别名」小节再校验是否在MODEL_CONFIGS中未知别名直接返回400detail中列出可用别名language可选传入后作为generate_kwargs[language]透传给底层模型未传时在响应中以auto回显response_formatjson时只返回{text: ...}verbose_json时返回带segments的扩展结构。需要特别强调这也是规范文档反复警示的语义边界response_formatverbose_json只是选择响应格式它并不会开启说话人分离diarization也不会强制生成时间戳。示例服务仅在模型返回sentence_info时才将其转换为segments否则返回segments[]speaker标签可能缺失或为null。五、响应结构json 与 verbose_json 的 schema 语义规范中的响应通过oneOf引用两种 schemajson模式TranscriptionTextResponse仅含必填的text字段值为清洗后的转写文本。规范中的示例值为{text: Welcome to FunASR.}。verbose_json模式VerboseTranscriptionResponse必填字段为text、segments、language、duration、model。规范给出的完整示例{ text: Welcome to FunASR., segments: [ { start: 0.0, end: 1.6, text: Welcome to FunASR., speaker: null } ], language: auto, duration: 0.843, model: sensevoice }其中segments数组的每个元素TranscriptionSegment包含start、end、text与可空的speaker。对照 server.pyverbose 响应的构造逻辑如下text来自clean_text(result[0][text])即用正则re.sub(r\|[^|]*\|, , text)剥离 SenseVoice 输出的|...|富标签如情感、事件标签后取纯文本segments仅在sentence_info in result[0]时生成且将 SDK 返回的毫秒级start/end除以 1000 转换为秒speaker取自seg.get(spk, None)duration是generate()调用前后的墙钟耗时排除首轮模型加载不是音频时长——规范文档与源码 docstring 均对此有明确界定。六、模型别名体系MODEL_CONFIGS 与 /v1/models规范文档指出model字段默认值为sensevoice并提示/v1/models会列出moss-transcribe-diarize。这背后对应 server.py 中的MODEL_CONFIGS字典其定义的五个别名及组合如下别名模型组合说明sensevoiceSenseVoiceSmall FSMN-VADmax_single_segment_time30000示例服务的启动默认与请求默认paraformerparaformer-zh FSMN-VAD CT 标点中文转写内置标点模型paraformer-enparaformer-en FSMN-VAD英文转写仅示例服务注册打包版funasr-server没有该内置别名fun-asr-nanoFun-ASR-NanoHF hub trust_remote_code FSMN-VADLLM 类 ASR 实验本示例走AutoModel而非 vLLM 路由moss-transcribe-diarizeOpenMOSS 第三方模型HF trust_remote_code锁定 revision离线多说话人转写分离原生返回时间戳与匿名说话人标签需要厘清的两点契约边界启动预加载与请求默认是两个独立设置示例服务中--model启动参数与请求中省略的 multipartmodel都默认sensevoice而打包版funasr-server启动--model auto时设备串以cuda开头选fun-asr-nano否则选sensevoice请求默认值则独立地是fun-asr-nano。因此规范文档建议请求中显式指定model并以部署实例实际的/v1/models返回为准。MOSS 的独立环境要求MOSS 需要隔离的 Transformers 环境使用funasr-server --model moss-transcribe-diarize --device cuda:0启动并请求response_formatverbose_json详见 MOSS 部署指南。其说话人标签仅在同一录音内匿名有效不是跨录音的身份识别。七、对照运行中的服务验证规范原文档给出的验证流程如下这里补充完整的环境准备与冒烟测试cd examples/openai_api python server.py --model sensevoice --device cuda --port 8000 curl -fsS http://localhost:8000/openapi.json /tmp/funasr-openapi-live.json在无 GPU 环境下可将--device替换为cpu速度较慢但路径完整。启动后可用三个 GET 端点做快速检查curl http://localhost:8000/health curl http://localhost:8000/v1/models curl http://localhost:8000/openapi.json仓库还提供了两条冒烟测试路径可直接验证「健康检查 模型列表 转写」全链路bash smoke_test.sh # 跨平台替代不依赖 curl/bash python smoke_test.pysmoke_test.py 是纯标准库实现它会按需下载公开中文样例音频BAC009S0764W0121.wav手工构造 multipart 请求体--boundaryfile/model/response_format字段依次打印/health、/v1/models与转写结果 JSON。其命令行参数--base-url、--model、--response-format、--timeout均支持环境变量覆盖非常适合 CI 与跨平台脚本调用。八、API 契约边界示例 server.py 与打包 funasr-server 的差异规范文档多次强调本规范描述的是示例服务与仓库打包的funasr-server实现见funasr/bin/_server_app.py并非同一实现。理解这份边界对避免误用至关重要维度示例server.py打包funasr-server请求表单字段仅file、model、language、response_format额外支持spktrue为非常规原生分离模型开启外部说话人流水线默认Falseduration语义generate()墙钟耗时排除首轮加载非音频时长音频时长秒音频元数据不可读时回退为 0segments来源模型返回的sentence_info转换否则[]可用段或基于文本/音频时长的粗粒度合成段非词级强制对齐verbose 附加字段顶层含model含task及段级id/words无顶层model兼容别名whisper-1映射到启动所选模型不运行 OpenAI Whisper同左SDK 选项use_itn、热词、timestamp/ctc_timestamps、原始数组等不暴露为表单字段同左规范文档还警示SDK 输出中的timestamp、Nano 的timestamps/ctc_timestamps不会被自动转换为 HTTP 段language在示例服务中只是提交的提示或auto并非检测到的语言。因此消费端必须以运行实例的/openapi.json为准而不是仅依赖这份静态示例 schema。更完整的字段对照表见 CLIENTS.md 的 Response formats 小节。九、客户端与工作流接入模式基于这份规范可以衍生出多种实际接入形态完整配方见 CLIENTS.md 与 WORKFLOWS.mdOpenAI Python SDK注意这是独立的 HTTP 客户端包openai不是 FunASR 的进程内 SDK本地开发时api_key用占位符即可服务端并不校验from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keynot-needed) with open(meeting.wav, rb) as audio: result client.audio.transcriptions.create( modelsensevoice, fileaudio, response_formatverbose_json, ) print(result.text) for segment in getattr(result, segments, []): print(segment)Agent 工具函数模式LangChain、LlamaIndex、AutoGen、CrewAI 等均可注册为普通工具from openai import OpenAI client OpenAI(base_urlhttp://localhost:8000/v1, api_keyx) def transcribe_for_agent(audio_path: str) - str: with open(audio_path, rb) as audio: result client.audio.transcriptions.create(modelsensevoice, fileaudio) return result.textDify / n8n 低代码工作流multipart HTTP 节点设置项值方法POSTURLhttp://funasr-host:8000/v1/audio/transcriptionsBody 类型multipart/form-data文件字段file文本字段modelsensevoice、response_formatverbose_json结果路径text作为转写文本segments可能为空说话人标签是条件性的n8n 的 OpenAI Audio 节点若固定发送modelwhisper-1FunASR 会将该兼容别名映射到启动所选模型——这只代表别名映射不会加载任何 Whisper 权重。工作流容器内的localhost指向容器自身跨容器访问需使用宿主/Compose 服务名/Kubernetes Service 地址。Postman可导入 funasr-openai-api.postman_collection.json设置集合变量FUNASR_BASE_URL与MODEL_ALIASsensevoice后即可运行健康检查、模型列表、verbose 转写与纯文本转写四个请求详见 POSTMAN.md。十、安全与部署注意规范文档与配套 SECURITY.md 反复强调示例服务没有任何内置认证或上传大小限制api_keynot-needed并不构成认证服务默认监听0.0.0.0本地联调请保持在 loopback--host 127.0.0.1。在对外共享之前必须通过反向代理/API 网关补上 TLS、认证、上传大小/超时/速率限制、音频与转写文本留存策略并限制/health、/v1/models、/openapi.json、/docs等元数据路由的公开访问。Docker 部署详见 README.md 与 Dockerfile默认以 CPU 模式启动便于在无 NVIDIA Container Toolkit 的机器上直接运行cd examples/openai_api cp .env.example .env FUNASR_HOST_PORT127.0.0.1:8000 docker compose up --build等效的一次性docker rundocker run --rm -p 127.0.0.1:8000:8000 \ -e FUNASR_DEVICEcpu \ -e FUNASR_MODELsensevoice \ funasr-api相关环境变量FUNASR_PORT默认 8000、FUNASR_DEVICE默认 cpu镜像具备 CUDA 依赖时才设为 cuda、FUNASR_MODEL默认 sensevoice。Kubernetes 场景可参考 kubernetes/README.md 的保守模板ClusterIP 持久化模型缓存 /health探针 /dev/shm内存卷并通过kubectl port-forward做私有验证。十一、常见问题排查SDK 报认证缺失本地开发传任意占位api_key即可服务端不校验400 unknown model调用/v1/models使用返回列表中的别名响应无segments确认response_formatverbose_json并检查模型是否返回sentence_infoverbose_json本身不会凭空生成时间戳或说话人标签首次请求很慢模型可能正在加载用--model sensevoice预加载并以/health作为就绪探针CUDA 不可用先用--device cpu验证 API 链路再排查驱动/运行时端口冲突改用--port 9000启动并以BASE_URLhttp://localhost:9000运行冒烟测试smoke_test.sh与smoke_test.py均支持该环境变量模型下载缓慢稳定网络重试或提前从 ModelScope/Hugging Face 预下载模型。最后回到本规范的定位openapi.json是一份面向集成者的稳定契约它刻意不随 FastAPI 框架细节漂移。以它为起点完成 mock、导入与客户端生成之后请务必以部署实例的实时/openapi.json与/v1/models做最终校验——静态规范保证的是「集成面稳定」运行时 schema 保证的是「与真实行为一致」两者结合才是正确的消费姿势。【免费下载链接】FunASROpen-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.项目地址: https://gitcode.com/GitHub_Trending/fun/FunASR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考