Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.
Python asraudiochineseemotion-recognitionfunasrmcp-servermultilingual-asropenai-compatible-apiparaformerpunctuationpytorchreal-time-asrspeaker-diarizationspeech-recognitionspeech-to-textstreaming-asrtranscriptionvllmvoice-activity-detectionwhisper-alternative
docs: add OpenAI API Postman collection
zhifu gao82ce34c6a9a8
diff --git a/README.md b/README.mdindex 28f39eaae..f4992be26 100644--- a/README.md+++ b/README.md@@ -198,7 +198,7 @@ curl http://localhost:8000/v1/audio/transcriptions \docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12```-[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)+[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [Deployment docs →](./runtime/readme.md) · [Agent integration →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/README_ja.md b/README_ja.mdindex ec7b690f7..d63bf8cc6 100644--- a/README_ja.md+++ b/README_ja.md@@ -132,7 +132,7 @@ funasr-server --device cudadocker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12```-[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html)+[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [デプロイドキュメント →](./runtime/readme.md) · [Agent連携 →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/README_ko.md b/README_ko.mdindex 5bb02fb92..c4e00cda2 100644--- a/README_ko.md+++ b/README_ko.md@@ -132,7 +132,7 @@ funasr-server --device cudadocker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12```-[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html)+[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [Workflow recipes →](./examples/openai_api/WORKFLOWS.md) · [Postman collection →](./examples/openai_api/POSTMAN.md) · [Deployment matrix →](./docs/deployment_matrix.md) · [배포 문서 →](./runtime/readme.md) · [Agent 연동 →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/README_zh.md b/README_zh.mdindex 2e553c97c..b8394ea25 100644--- a/README_zh.md+++ b/README_zh.md@@ -197,7 +197,7 @@ curl http://localhost:8000/v1/audio/transcriptions \docker pull registry.cn-hangzhou.aliyuncs.com/funasr_repo/funasr:funasr-runtime-sdk-online-cpu-0.1.12```-[OpenAI API 示例 →](./examples/openai_api/) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)+[OpenAI API 示例 →](./examples/openai_api/) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/examples/openai_api/CLIENTS.md b/examples/openai_api/CLIENTS.mdindex adffb9ac7..6e92446b0 100644--- a/examples/openai_api/CLIENTS.md+++ b/examples/openai_api/CLIENTS.md@@ -1,6 +1,6 @@# Client Recipes for the FunASR OpenAI-Compatible API-Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md).+Use this page when `funasr-server` is already running and you want to connect an existing application, agent tool, or workflow engine to local speech recognition. For Dify, n8n, HTTP nodes, and webhook workers, see the [workflow recipes](WORKFLOWS.md) or [Chinese workflow recipes](WORKFLOWS_zh.md). For no-code API smoke tests, import the [Postman collection](POSTMAN.md).## Preflightdiff --git a/examples/openai_api/POSTMAN.md b/examples/openai_api/POSTMAN.mdnew file mode 100644index 000000000..0662fa699--- /dev/null+++ b/examples/openai_api/POSTMAN.md@@ -0,0 +1,37 @@+# Postman Collection for the FunASR OpenAI-Compatible API++Use the Postman collection when you want to verify a private FunASR speech API before wiring it into Dify, n8n, an agent framework, or an internal service.++## Import++1. Start the server:++ ```bash+ cd examples/openai_api+ python server.py --model sensevoice --device cuda --port 8000+ ```++2. Import [`funasr-openai-api.postman_collection.json`](funasr-openai-api.postman_collection.json) into Postman.+3. Set the collection variable `FUNASR_BASE_URL` to the reachable server URL, for example `http://localhost:8000` or `http://funasr-api:8000`.+4. Keep `MODEL_ALIAS=sensevoice` for the first smoke test, or switch it to one of the aliases returned by `/v1/models`.++## Requests++| Request | Purpose |+|---|---|+| `Health check` | Confirms the server is reachable and returns JSON. |+| `List model aliases` | Shows available OpenAI-compatible model aliases. |+| `Transcribe audio - verbose JSON` | Uploads an audio file and returns `text`, `segments`, and timing metadata. |+| `Transcribe audio - text only` | Minimal transcription request for OpenAI-compatible clients. |++For the transcription requests, open the `Body` tab and choose a local audio file for the `file` form-data field before sending.++## Troubleshooting++| Symptom | Fix |+|---|---|+| `ECONNREFUSED` | Confirm the server is running and that `FUNASR_BASE_URL` is reachable from Postman. |+| Docker service works but Postman cannot connect | Use the host port exposed by Docker Compose, for example `http://localhost:8000`. |+| `422` or missing file errors | Make sure the `file` form-data row is enabled and points to a local audio file. |+| Unknown model alias | Run `List model aliases` and copy one of the returned aliases into `MODEL_ALIAS`. |+| No `segments` in the response | Set `RESPONSE_FORMAT=verbose_json`. |diff --git a/examples/openai_api/README.md b/examples/openai_api/README.mdindex a7844a5d1..34a58e6b8 100644--- a/examples/openai_api/README.md+++ b/examples/openai_api/README.md@@ -11,7 +11,7 @@ python server.py --model sensevoice --device cuda --port 8000Server starts in ~20s (model loading). Health check: `GET /health`-Need copy-paste integration snippets for Python SDK, HTTP clients, agent tools, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [workflow recipes](WORKFLOWS.md), and the [Chinese workflow recipes](WORKFLOWS_zh.md).+Need copy-paste integration snippets for Python SDK, HTTP clients, agent tools, Postman, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [workflow recipes](WORKFLOWS.md), the [Chinese workflow recipes](WORKFLOWS_zh.md), and the [Postman collection](POSTMAN.md).### End-to-end smoke test@@ -87,6 +87,8 @@ curl http://localhost:8000/v1/audio/transcriptions \| `/health` | GET | Health check + loaded models || `/docs` | GET | Interactive API documentation (Swagger) |+Prefer no-code API checks? Import the [Postman collection](POSTMAN.md) and run health, model-list, and transcription requests from Postman.+## Agent Framework IntegrationWorks with: **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, **n8n**, or any framework using OpenAI audio API. See [Client recipes](CLIENTS.md) for SDK and agent-tool patterns, plus [workflow recipes](WORKFLOWS.md) for low-code HTTP nodes and webhook workers ([中文](WORKFLOWS_zh.md)).diff --git a/examples/openai_api/WORKFLOWS.md b/examples/openai_api/WORKFLOWS.mdindex 4a8941ff6..33696595b 100644--- a/examples/openai_api/WORKFLOWS.md+++ b/examples/openai_api/WORKFLOWS.md@@ -21,6 +21,10 @@ curl -fsS "$FUNASR_BASE_URL/v1/models"If the workflow engine runs in Docker, `localhost` usually means the workflow container itself. Use a Docker Compose service name, Kubernetes service name, or LAN host name instead.+## Postman smoke test++Before configuring a low-code tool, you can import the [Postman collection](POSTMAN.md) and run health, model-list, and transcription requests from a GUI. Set `FUNASR_BASE_URL`, choose a local audio file for the multipart `file` field, and keep `MODEL_ALIAS=sensevoice` for the first test.+## Multipart HTTP requestEvery workflow engine eventually needs to send this request shape:diff --git a/examples/openai_api/WORKFLOWS_zh.md b/examples/openai_api/WORKFLOWS_zh.mdindex edf48d8d3..6b3500e78 100644--- a/examples/openai_api/WORKFLOWS_zh.md+++ b/examples/openai_api/WORKFLOWS_zh.md@@ -21,6 +21,10 @@ curl -fsS "$FUNASR_BASE_URL/v1/models"如果工作流引擎运行在 Docker 中,`localhost` 通常指的是工作流容器自身。请改用 Docker Compose service name、Kubernetes service name 或内网主机名。+## Postman smoke test++在配置低代码工具前,可以先导入 [Postman collection](POSTMAN.md),从图形界面跑通 health、模型列表和转写请求。设置 `FUNASR_BASE_URL`,在 multipart `file` 字段选择本地音频文件,第一次测试建议保持 `MODEL_ALIAS=sensevoice`。+## Multipart HTTP 请求所有工作流引擎最终都需要发出下面这种请求:diff --git a/examples/openai_api/funasr-openai-api.postman_collection.json b/examples/openai_api/funasr-openai-api.postman_collection.jsonnew file mode 100644index 000000000..284b1ea62--- /dev/null+++ b/examples/openai_api/funasr-openai-api.postman_collection.json@@ -0,0 +1,185 @@+{+ "info": {+ "name": "FunASR OpenAI-Compatible API",+ "description": "Smoke-test the FunASR OpenAI-compatible speech API. Start the server, set FUNASR_BASE_URL, choose a local audio file for multipart requests, then run health, model list, and transcription checks.",+ "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"+ },+ "variable": [+ {+ "key": "FUNASR_BASE_URL",+ "value": "http://localhost:8000",+ "type": "string"+ },+ {+ "key": "MODEL_ALIAS",+ "value": "sensevoice",+ "type": "string"+ },+ {+ "key": "RESPONSE_FORMAT",+ "value": "verbose_json",+ "type": "string"+ }+ ],+ "item": [+ {+ "name": "Health check",+ "request": {+ "method": "GET",+ "header": [],+ "url": {+ "raw": "{{FUNASR_BASE_URL}}/health",+ "host": [+ "{{FUNASR_BASE_URL}}"+ ],+ "path": [+ "health"+ ]+ },+ "description": "Confirm the FunASR API server is reachable and ready."+ },+ "event": [+ {+ "listen": "test",+ "script": {+ "type": "text/javascript",+ "exec": [+ "pm.test('health returns 200', function () { pm.response.to.have.status(200); });",+ "pm.test('health response is JSON', function () { pm.response.to.be.json; });"+ ]+ }+ }+ ]+ },+ {+ "name": "List model aliases",+ "request": {+ "method": "GET",+ "header": [],+ "url": {+ "raw": "{{FUNASR_BASE_URL}}/v1/models",+ "host": [+ "{{FUNASR_BASE_URL}}"+ ],+ "path": [+ "v1",+ "models"+ ]+ },+ "description": "List OpenAI-compatible model aliases exposed by the server."+ },+ "event": [+ {+ "listen": "test",+ "script": {+ "type": "text/javascript",+ "exec": [+ "pm.test('models returns 200', function () { pm.response.to.have.status(200); });",+ "pm.test('models response is JSON', function () { pm.response.to.be.json; });"+ ]+ }+ }+ ]+ },+ {+ "name": "Transcribe audio - verbose JSON",+ "request": {+ "method": "POST",+ "header": [],+ "body": {+ "mode": "formdata",+ "formdata": [+ {+ "key": "file",+ "type": "file",+ "src": "sample.wav",+ "description": "Choose a local wav, mp3, m4a, or other supported audio file before sending."+ },+ {+ "key": "model",+ "value": "{{MODEL_ALIAS}}",+ "type": "text"+ },+ {+ "key": "response_format",+ "value": "{{RESPONSE_FORMAT}}",+ "type": "text"+ }+ ]+ },+ "url": {+ "raw": "{{FUNASR_BASE_URL}}/v1/audio/transcriptions",+ "host": [+ "{{FUNASR_BASE_URL}}"+ ],+ "path": [+ "v1",+ "audio",+ "transcriptions"+ ]+ },+ "description": "Upload an audio file with multipart/form-data and return transcript text plus segments when RESPONSE_FORMAT is verbose_json."+ },+ "event": [+ {+ "listen": "test",+ "script": {+ "type": "text/javascript",+ "exec": [+ "pm.test('transcription returns 200', function () { pm.response.to.have.status(200); });",+ "pm.test('transcription response is JSON', function () { pm.response.to.be.json; });",+ "pm.test('transcription has text', function () { var data = pm.response.json(); pm.expect(data.text).to.be.a('string'); });"+ ]+ }+ }+ ]+ },+ {+ "name": "Transcribe audio - text only",+ "request": {+ "method": "POST",+ "header": [],+ "body": {+ "mode": "formdata",+ "formdata": [+ {+ "key": "file",+ "type": "file",+ "src": "sample.wav",+ "description": "Choose a local audio file before sending."+ },+ {+ "key": "model",+ "value": "{{MODEL_ALIAS}}",+ "type": "text"+ }+ ]+ },+ "url": {+ "raw": "{{FUNASR_BASE_URL}}/v1/audio/transcriptions",+ "host": [+ "{{FUNASR_BASE_URL}}"+ ],+ "path": [+ "v1",+ "audio",+ "transcriptions"+ ]+ },+ "description": "Minimal OpenAI-compatible transcription request."+ },+ "event": [+ {+ "listen": "test",+ "script": {+ "type": "text/javascript",+ "exec": [+ "pm.test('transcription returns 200', function () { pm.response.to.have.status(200); });",+ "pm.test('transcription response is JSON', function () { pm.response.to.be.json; });"+ ]+ }+ }+ ]+ }+ ]+}