mirror of
https://github.com/modelscope/FunASR.git
synced 2026-10-12 02:19:18 +00:00
docs: add OpenAI API Postman collection
Co-authored-by: xiaoyunchong.xyc <[email protected]>
This commit is contained in:
zhifu gao
co-authored by
xiaoyunchong.xyc
xiaoyunchong.xyc
parent
ac79b66362
commit
82ce34c6a9
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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`. |
|
||||
@@ -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)).
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 请求
|
||||
|
||||
所有工作流引擎最终都需要发出下面这种请求：
|
||||
|
||||
@@ -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; });"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user