FunASR/examples/openai_api/POSTMAN_zh.md

FunASR OpenAI 兼容 API Postman 集合

English

当你希望先用图形界面验证私有 FunASR 语音 API，再接入 Dify、n8n、Agent 框架或内部服务时，可以导入 Postman collection。需要按 schema 导入时，可使用 OpenAPI 规范。

导入步骤

1. 启动服务：

   cd examples/openai_api
   python server.py --model sensevoice --device cuda --port 8000
   

2. 在 Postman 中导入 funasr-openai-api.postman_collection.json。

3. 将 collection 变量 FUNASR_BASE_URL 改成可访问的服务地址，例如 http://localhost:8000 或 http://funasr-api:8000。

4. 第一次 smoke test 建议保持 MODEL_ALIAS=sensevoice；也可以先运行 /v1/models，再复制返回的模型别名。

请求列表

Request	用途
Health check	确认服务可访问并返回 JSON。
List model aliases	查看服务暴露的 OpenAI 兼容模型别名。
Transcribe audio - verbose JSON	上传音频并返回 text、segments 和耗时信息。
Transcribe audio - text only	最小转写请求，适合验证 OpenAI 兼容客户端。

发送转写请求前，请打开 Body tab，在 file form-data 字段选择本地音频文件。

故障排查

现象	处理方式
ECONNREFUSED	确认服务已启动，并且 Postman 能访问 FUNASR_BASE_URL。
Docker 服务正常但 Postman 连不上	使用 Docker Compose 暴露到宿主机的端口，例如 http://localhost:8000。
422 或提示缺少文件	确认 file form-data 行已启用，并指向本地音频文件。
模型别名未知	先运行 List model aliases，再把返回的别名填入 MODEL_ALIAS。
响应中没有 segments	设置 RESPONSE_FORMAT=verbose_json。