mirror of
https://github.com/modelscope/FunASR.git
synced 2026-10-12 02:19:18 +00:00
58 lines
2.7 KiB
Markdown
58 lines
2.7 KiB
Markdown
# FunASR OpenAI 兼容 API OpenAPI 规范
|
||
|
||
[English](OPENAPI.md)
|
||
|
||
当你希望在接入应用、API 网关、开发者门户、工作流引擎或 SDK 生成器之前，先查看、mock、导入或发布 FunASR 语音 API 时，可以使用 [`openapi.json`](openapi.json)。
|
||
|
||
运行中的 FastAPI 服务也会在 `/docs` 暴露 Swagger UI，并在 `/openapi.json` 暴露实时 schema。仓库里的 `openapi.json` 是这个示例服务的便携参考规范，便于在服务启动前完成评估和导入。
|
||
|
||
## 导入方式
|
||
|
||
| 工具 | 使用方式 |
|
||
|---|---|
|
||
| Swagger Editor 或 Redoc | 导入 `openapi.json`，查看 `/health`、`/v1/models` 和 `/v1/audio/transcriptions`。 |
|
||
| Postman | 如果偏好 schema 驱动集合，可导入 `openapi.json`；如果想直接 smoke test，可使用现成的 [Postman 集合](POSTMAN_zh.md)。 |
|
||
| Dify、n8n 或内部工作流工具 | 结合规范中的 multipart 请求结构和 [工作流配方](WORKFLOWS_zh.md) 配置 HTTP 节点。 |
|
||
| API 网关或内部开发者门户 | 发布该规范，并把 server URL 改成你的 FunASR API 可访问地址。 |
|
||
| 客户端生成 | 生成内部小客户端，并确保 multipart `file` 字段映射为二进制上传。 |
|
||
|
||
## Server URL
|
||
|
||
规范内置了两个示例地址：
|
||
|
||
- `http://localhost:8000`
|
||
- `http://funasr-api:8000`
|
||
|
||
请替换为你的应用、容器或工作流运行环境能访问到的地址。
|
||
|
||
## 端点
|
||
|
||
| Endpoint | Method | 用途 |
|
||
|---|---|---|
|
||
| `/health` | `GET` | 健康检查、设备、已加载模型和可用别名。 |
|
||
| `/v1/models` | `GET` | OpenAI 风格模型列表，包含 `ready` 状态。 |
|
||
| `/v1/audio/transcriptions` | `POST` | multipart 音频转写；使用 `response_format=verbose_json` 返回 segments。 |
|
||
|
||
## Multipart 转写字段
|
||
|
||
| Field | Type | Required | 说明 |
|
||
|---|---|---|---|
|
||
| `file` | binary | yes | 音频文件，例如 wav、mp3、flac、m4a、ogg 或 webm。 |
|
||
| `model` | string | no | 默认 `sensevoice`；`/v1/models` 也会列出用于离线长音频与原生匿名说话人标签的 `moss-transcribe-diarize`。 |
|
||
| `language` | string | no | 可选语言提示。 |
|
||
| `response_format` | string | no | 使用 `json` 或 `verbose_json`。 |
|
||
|
||
## 对照运行中的服务验证
|
||
|
||
```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
|
||
```
|
||
|
||
实时 FastAPI schema 可能包含框架级校验细节；仓库中的静态规范保留更小、更稳定的公开集成面。
|
||
|
||
MOSS 需要独立 Transformers 环境。使用
|
||
`funasr-server --model moss-transcribe-diarize --device cuda:0` 启动，并请求
|
||
`response_format=verbose_json`；详见 [部署指南](../../docs/moss_transcribe_diarize_zh.md)。
|