OPENAPI_zh.md

FunASR OpenAI 兼容 API OpenAPI 规范

English

当你希望在接入应用、API 网关、开发者门户、工作流引擎或 SDK 生成器之前，先查看、mock、导入或发布 FunASR 语音 API 时，可以使用 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 集合。
Dify、n8n 或内部工作流工具	结合规范中的 multipart 请求结构和 工作流配方 配置 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 返回。
language	string	no	可选语言提示。
response_format	string	no	使用 json 或 verbose_json。

对照运行中的服务验证

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 可能包含框架级校验细节；仓库中的静态规范保留更小、更稳定的公开集成面。