Skip to content

Open-source speech recognition toolkit for training, inference, streaming ASR, VAD, punctuation, speaker diarization pipelines, and OpenAI-compatible/MCP serving.

docs: add OpenAI API Postman collection

zhifu gao82ce34c6a9a8
diff --git a/README.md b/README.md
index 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.md
index ec7b690f7..d63bf8cc6 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -132,7 +132,7 @@ funasr-server --device cuda
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) · [デプロイドキュメント →](./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.md
index 5bb02fb92..c4e00cda2 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -132,7 +132,7 @@ funasr-server --device cuda
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) · [배포 문서 →](./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.md
index 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.md
index 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).
## Preflight
diff --git a/examples/openai_api/POSTMAN.md b/examples/openai_api/POSTMAN.md
new file mode 100644
index 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.md
index 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 8000
Server 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 Integration
Works 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.md
index 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 request
Every workflow engine eventually needs to send this request shape:
diff --git a/examples/openai_api/WORKFLOWS_zh.md b/examples/openai_api/WORKFLOWS_zh.md
index 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.json
new file mode 100644
index 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; });"
+ ]
+ }
+ }
+ ]
+ }
+ ]
+}