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 OpenAPI spec
zhifu gao46bc2c77597e
diff --git a/README.md b/README.mdindex f4992be26..e80e10565 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) · [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)+[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) · [OpenAPI spec →](./examples/openai_api/OPENAPI.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 d63bf8cc6..a3234ebbb 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) · [Postman collection →](./examples/openai_api/POSTMAN.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) · [OpenAPI spec →](./examples/openai_api/OPENAPI.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 c4e00cda2..611fd782e 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) · [Postman collection →](./examples/openai_api/POSTMAN.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) · [OpenAPI spec →](./examples/openai_api/OPENAPI.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 b8394ea25..64ca96e1c 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) · [Postman 集合 →](./examples/openai_api/POSTMAN.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) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)---diff --git a/docs/deployment_matrix.md b/docs/deployment_matrix.mdindex 0074bc6fa..693fb80d7 100644--- a/docs/deployment_matrix.md+++ b/docs/deployment_matrix.md@@ -24,7 +24,7 @@ Use the Python API from the README. It is the shortest route for validating inst### I want a local replacement for cloud transcription-Use the OpenAI-compatible API. It exposes `/v1/audio/transcriptions`, `/v1/models`, `/health`, and Swagger docs. Start with `sensevoice`, run `examples/openai_api/smoke_test.sh`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md). For Dify, n8n, HTTP nodes, or webhook workers, follow the [workflow recipes](../examples/openai_api/WORKFLOWS.md).+Use the OpenAI-compatible API. It exposes `/v1/audio/transcriptions`, `/v1/models`, `/health`, and Swagger docs. Start with `sensevoice`, run `examples/openai_api/smoke_test.sh`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md). For Dify, n8n, HTTP nodes, or webhook workers, follow the [workflow recipes](../examples/openai_api/WORKFLOWS.md). For API gateways, developer portals, and schema-driven imports, use the [OpenAPI spec](../examples/openai_api/OPENAPI.md).### I want a repeatable container demodiff --git a/docs/deployment_matrix_zh.md b/docs/deployment_matrix_zh.mdindex e31243527..dd6ecd4a3 100644--- a/docs/deployment_matrix_zh.md+++ b/docs/deployment_matrix_zh.md@@ -24,7 +24,7 @@### 我想替代云端转写服务-使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh`,再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 接入 SDK 或 HTTP 客户端。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md)。+使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh`,再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 接入 SDK 或 HTTP 客户端。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md)。API 网关、开发者门户或按 schema 导入时可使用 [OpenAPI 规范](../examples/openai_api/OPENAPI.md)。### 我想要可复现的容器 demodiff --git a/examples/openai_api/CLIENTS.md b/examples/openai_api/CLIENTS.mdindex 6e92446b0..8520dd66c 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). For no-code API smoke tests, import the [Postman collection](POSTMAN.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). For schema-driven imports or client generation, use the [OpenAPI spec](OPENAPI.md).## Preflightdiff --git a/examples/openai_api/OPENAPI.md b/examples/openai_api/OPENAPI.mdnew file mode 100644index 000000000..168b3de13--- /dev/null+++ b/examples/openai_api/OPENAPI.md@@ -0,0 +1,51 @@+# OpenAPI Spec for the FunASR OpenAI-Compatible API++Use [`openapi.json`](openapi.json) when you want to inspect, mock, document, or import the FunASR speech API before wiring it into an application, API gateway, workflow engine, or SDK generator.++The running FastAPI server also exposes live docs at `/docs` and a generated schema at `/openapi.json`. This checked-in spec is a portable reference for the example server in this directory.++## Import options++| Tool | How to use it |+|---|---|+| Swagger Editor or Redoc | Import `openapi.json` to inspect `/health`, `/v1/models`, and `/v1/audio/transcriptions`. |+| Postman | Import `openapi.json` if you prefer schema-driven collections, or use the ready-made [Postman collection](POSTMAN.md). |+| Dify, n8n, or internal workflow tools | Use the multipart request shape in the spec together with the [workflow recipes](WORKFLOWS.md). |+| API gateway or internal developer portal | Publish the spec and point the server URL to your reachable FunASR API endpoint. |+| Client generation | Generate a small internal client, then keep the multipart `file` field mapped to a binary upload. |++## Server URL++The spec includes local examples:++- `http://localhost:8000`+- `http://funasr-api:8000`++Replace them with the URL reachable from your app, container, or workflow runtime.++## Endpoints++| Endpoint | Method | Purpose |+|---|---|---|+| `/health` | `GET` | Readiness check, selected device, loaded models, and available aliases. |+| `/v1/models` | `GET` | OpenAI-style model list with `ready` flags. |+| `/v1/audio/transcriptions` | `POST` | Multipart audio transcription. Use `response_format=verbose_json` for segments. |++## Multipart transcription fields++| Field | Type | Required | Notes |+|---|---|---|---|+| `file` | binary | yes | Audio file such as wav, mp3, flac, m4a, ogg, or webm. |+| `model` | string | no | Defaults to `sensevoice`; available aliases are listed by `/v1/models`. |+| `language` | string | no | Optional language hint. |+| `response_format` | string | no | Use `json` or `verbose_json`. |++## Validate against a running server++```bash+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+```++The live FastAPI schema may include framework-specific validation details; this checked-in spec keeps the public integration surface small and stable.diff --git a/examples/openai_api/POSTMAN.md b/examples/openai_api/POSTMAN.mdindex 0662fa699..729b66103 100644--- a/examples/openai_api/POSTMAN.md+++ b/examples/openai_api/POSTMAN.md@@ -1,6 +1,6 @@# 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.+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. If you prefer schema-driven imports, use the [OpenAPI spec](OPENAPI.md).## Importdiff --git a/examples/openai_api/README.md b/examples/openai_api/README.mdindex 34a58e6b8..fdd209f60 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, 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).+Need copy-paste integration snippets for Python SDK, HTTP clients, agent tools, Postman, OpenAPI imports, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [workflow recipes](WORKFLOWS.md), the [Chinese workflow recipes](WORKFLOWS_zh.md), the [Postman collection](POSTMAN.md), and the [OpenAPI spec](OPENAPI.md).### End-to-end smoke test@@ -87,7 +87,7 @@ 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.+Prefer no-code API checks? Import the [Postman collection](POSTMAN.md) and run health, model-list, and transcription requests from Postman. For API gateways, developer portals, or client generation, use the [OpenAPI spec](OPENAPI.md).## Agent Framework Integrationdiff --git a/examples/openai_api/WORKFLOWS.md b/examples/openai_api/WORKFLOWS.mdindex 33696595b..f50283a77 100644--- a/examples/openai_api/WORKFLOWS.md+++ b/examples/openai_api/WORKFLOWS.md@@ -23,7 +23,7 @@ If the workflow engine runs in Docker, `localhost` usually means the workflow co## 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.+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. For schema-driven imports, use the [OpenAPI spec](OPENAPI.md). 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 requestdiff --git a/examples/openai_api/WORKFLOWS_zh.md b/examples/openai_api/WORKFLOWS_zh.mdindex 6b3500e78..7800bcbc0 100644--- a/examples/openai_api/WORKFLOWS_zh.md+++ b/examples/openai_api/WORKFLOWS_zh.md@@ -23,7 +23,7 @@ curl -fsS "$FUNASR_BASE_URL/v1/models"## Postman smoke test-在配置低代码工具前,可以先导入 [Postman collection](POSTMAN.md),从图形界面跑通 health、模型列表和转写请求。设置 `FUNASR_BASE_URL`,在 multipart `file` 字段选择本地音频文件,第一次测试建议保持 `MODEL_ALIAS=sensevoice`。+在配置低代码工具前,可以先导入 [Postman collection](POSTMAN.md),从图形界面跑通 health、模型列表和转写请求;需要按 schema 导入时可使用 [OpenAPI spec](OPENAPI.md)。设置 `FUNASR_BASE_URL`,在 multipart `file` 字段选择本地音频文件,第一次测试建议保持 `MODEL_ALIAS=sensevoice`。## Multipart HTTP 请求diff --git a/examples/openai_api/openapi.json b/examples/openai_api/openapi.jsonnew file mode 100644index 000000000..bcc5c7b8d--- /dev/null+++ b/examples/openai_api/openapi.json@@ -0,0 +1,374 @@+{+ "openapi": "3.0.3",+ "info": {+ "title": "FunASR OpenAI-Compatible API",+ "version": "1.0.0",+ "description": "Static OpenAPI description for the FunASR OpenAI-compatible speech transcription server. The running FastAPI service also exposes Swagger UI at /docs and an OpenAPI document at /openapi.json."+ },+ "servers": [+ {+ "url": "http://localhost:8000",+ "description": "Local development server"+ },+ {+ "url": "http://funasr-api:8000",+ "description": "Example Docker Compose or internal service name"+ }+ ],+ "tags": [+ {+ "name": "Transcription",+ "description": "OpenAI-compatible speech transcription"+ },+ {+ "name": "Models",+ "description": "Model discovery"+ },+ {+ "name": "Health",+ "description": "Readiness and loaded model status"+ }+ ],+ "paths": {+ "/v1/audio/transcriptions": {+ "post": {+ "tags": [+ "Transcription"+ ],+ "summary": "Transcribe an audio file",+ "description": "Upload an audio file with multipart/form-data and receive an OpenAI-compatible transcript response. Set response_format=verbose_json to include segments and timing metadata.",+ "operationId": "createTranscription",+ "requestBody": {+ "required": true,+ "content": {+ "multipart/form-data": {+ "schema": {+ "$ref": "#/components/schemas/TranscriptionRequest"+ }+ }+ }+ },+ "responses": {+ "200": {+ "description": "Transcription result",+ "content": {+ "application/json": {+ "schema": {+ "oneOf": [+ {+ "$ref": "#/components/schemas/TranscriptionTextResponse"+ },+ {+ "$ref": "#/components/schemas/VerboseTranscriptionResponse"+ }+ ]+ },+ "examples": {+ "json": {+ "summary": "Default text response",+ "value": {+ "text": "Welcome to FunASR."+ }+ },+ "verbose_json": {+ "summary": "Verbose response",+ "value": {+ "text": "Welcome to FunASR.",+ "segments": [+ {+ "start": 0.0,+ "end": 1.6,+ "text": "Welcome to FunASR.",+ "speaker": null+ }+ ],+ "language": "auto",+ "duration": 0.843,+ "model": "sensevoice"+ }+ }+ }+ }+ }+ },+ "400": {+ "description": "Unknown model alias",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorResponse"+ }+ }+ }+ },+ "422": {+ "description": "Invalid multipart request"+ },+ "500": {+ "description": "Transcription runtime error",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ErrorResponse"+ }+ }+ }+ }+ }+ }+ },+ "/v1/models": {+ "get": {+ "tags": [+ "Models"+ ],+ "summary": "List model aliases",+ "description": "Return OpenAI-style model objects for the aliases configured by the FunASR server.",+ "operationId": "listModels",+ "responses": {+ "200": {+ "description": "Model list",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/ModelsResponse"+ }+ }+ }+ }+ }+ }+ },+ "/health": {+ "get": {+ "tags": [+ "Health"+ ],+ "summary": "Health check",+ "description": "Check server readiness, selected device, loaded models, and available model aliases.",+ "operationId": "getHealth",+ "responses": {+ "200": {+ "description": "Server health",+ "content": {+ "application/json": {+ "schema": {+ "$ref": "#/components/schemas/HealthResponse"+ }+ }+ }+ }+ }+ }+ }+ },+ "components": {+ "schemas": {+ "TranscriptionRequest": {+ "type": "object",+ "required": [+ "file"+ ],+ "properties": {+ "file": {+ "type": "string",+ "format": "binary",+ "description": "Audio file such as wav, mp3, flac, m4a, ogg, or webm."+ },+ "model": {+ "type": "string",+ "enum": [+ "sensevoice",+ "paraformer",+ "paraformer-en",+ "fun-asr-nano"+ ],+ "default": "sensevoice",+ "description": "FunASR model alias."+ },+ "language": {+ "type": "string",+ "nullable": true,+ "description": "Optional language hint passed to FunASR."+ },+ "response_format": {+ "type": "string",+ "enum": [+ "json",+ "verbose_json"+ ],+ "default": "json",+ "description": "Use verbose_json to include segments and timing metadata."+ }+ }+ },+ "TranscriptionTextResponse": {+ "type": "object",+ "required": [+ "text"+ ],+ "properties": {+ "text": {+ "type": "string",+ "description": "Cleaned transcript text."+ }+ }+ },+ "VerboseTranscriptionResponse": {+ "type": "object",+ "required": [+ "text",+ "segments",+ "language",+ "duration",+ "model"+ ],+ "properties": {+ "text": {+ "type": "string"+ },+ "segments": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/TranscriptionSegment"+ }+ },+ "language": {+ "type": "string",+ "example": "auto"+ },+ "duration": {+ "type": "number",+ "format": "float",+ "description": "Server-side transcription latency in seconds."+ },+ "model": {+ "type": "string",+ "example": "sensevoice"+ }+ }+ },+ "TranscriptionSegment": {+ "type": "object",+ "required": [+ "start",+ "end",+ "text"+ ],+ "properties": {+ "start": {+ "type": "number",+ "format": "float",+ "description": "Segment start time in seconds."+ },+ "end": {+ "type": "number",+ "format": "float",+ "description": "Segment end time in seconds."+ },+ "text": {+ "type": "string"+ },+ "speaker": {+ "type": "string",+ "nullable": true,+ "description": "Speaker label when available."+ }+ }+ },+ "ModelObject": {+ "type": "object",+ "required": [+ "id",+ "object",+ "created",+ "owned_by",+ "ready"+ ],+ "properties": {+ "id": {+ "type": "string",+ "example": "sensevoice"+ },+ "object": {+ "type": "string",+ "example": "model"+ },+ "created": {+ "type": "integer",+ "example": 1700000000+ },+ "owned_by": {+ "type": "string",+ "example": "funasr"+ },+ "ready": {+ "type": "boolean",+ "description": "Whether this alias is already loaded in memory."+ }+ }+ },+ "ModelsResponse": {+ "type": "object",+ "required": [+ "object",+ "data"+ ],+ "properties": {+ "object": {+ "type": "string",+ "example": "list"+ },+ "data": {+ "type": "array",+ "items": {+ "$ref": "#/components/schemas/ModelObject"+ }+ }+ }+ },+ "HealthResponse": {+ "type": "object",+ "required": [+ "status",+ "device",+ "models_loaded",+ "models_available"+ ],+ "properties": {+ "status": {+ "type": "string",+ "example": "ok"+ },+ "device": {+ "type": "string",+ "example": "cuda"+ },+ "models_loaded": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "models_available": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ }+ },+ "ErrorResponse": {+ "type": "object",+ "required": [+ "detail"+ ],+ "properties": {+ "detail": {+ "type": "string"+ }+ }+ }+ }+ }+}