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 JavaScript OpenAI API recipes
zhifu gao31119ec0e5f3
diff --git a/README.md b/README.mdindex e80e10565..e17a94c6a 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) · [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)+[OpenAI API example →](./examples/openai_api/) · [Client recipes →](./examples/openai_api/CLIENTS.md) · [JavaScript/TypeScript recipes →](./examples/openai_api/JAVASCRIPT.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_zh.md b/README_zh.mdindex 44981fcd4..edca4929e 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/README_zh.md) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN_zh.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI_zh.md) · [部署选型 →](./docs/deployment_matrix_zh.md) · [部署文档 →](./runtime/readme_cn.md) · [Agent 集成 →](https://modelscope.github.io/FunASR/agent.html)+[OpenAI API 示例 →](./examples/openai_api/README_zh.md) · [客户端配方 →](./examples/openai_api/CLIENTS.md) · [JavaScript/TypeScript 配方 →](./examples/openai_api/JAVASCRIPT_zh.md) · [工作流配方 →](./examples/openai_api/WORKFLOWS_zh.md) · [Postman 集合 →](./examples/openai_api/POSTMAN_zh.md) · [OpenAPI 规范 →](./examples/openai_api/OPENAPI_zh.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 a5af5b851..141e441c7 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` or `examples/openai_api/smoke_test.py`, 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).+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` or `examples/openai_api/smoke_test.py`, then connect existing SDK or HTTP clients using [client recipes](../examples/openai_api/CLIENTS.md) and [JavaScript/TypeScript recipes](../examples/openai_api/JAVASCRIPT.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 c75189ee0..aa644a072 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/smoke_test.py`,再根据 [客户端配方](../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_zh.md)。+使用 OpenAI 兼容 API。它提供 `/v1/audio/transcriptions`、`/v1/models`、`/health` 和 Swagger docs。先用 `sensevoice` 跑通 `examples/openai_api/smoke_test.sh` 或 `examples/openai_api/smoke_test.py`,再根据 [客户端配方](../examples/openai_api/CLIENTS.md) 和 [JavaScript/TypeScript 配方](../examples/openai_api/JAVASCRIPT_zh.md) 接入 SDK 或 HTTP 客户端。Dify、n8n、HTTP 节点或 webhook worker 可参考 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md)。API 网关、开发者门户或按 schema 导入时可使用 [OpenAPI 规范](../examples/openai_api/OPENAPI_zh.md)。### 我想要可复现的容器 demodiff --git a/docs/use_case_showcase.md b/docs/use_case_showcase.mdindex 029439b47..34aedcbe0 100644--- a/docs/use_case_showcase.md+++ b/docs/use_case_showcase.md@@ -9,7 +9,7 @@ FunASR is useful far beyond a single offline transcription command. This page co| Transcribe one file locally | [README quick start](../README.md#quick-start) | Verify install and model download in minutes. || Compare accuracy and speed | [Benchmark report](https://modelscope.github.io/FunASR/benchmark.html) | Reproduce the 184-file long-audio benchmark before choosing a model. || Migrate from Whisper/cloud ASR | [Migration guide](./migration_from_whisper.md) | Map existing pipelines to FunASR, benchmark representative audio, and plan a safe rollout. |-| Build a private speech API | [OpenAI-compatible API example](../examples/openai_api/), [client recipes](../examples/openai_api/CLIENTS.md), and [workflow recipes](../examples/openai_api/WORKFLOWS.md) | Reuse LangChain, Dify, n8n, AutoGen, and other OpenAI-style clients without sending audio to a cloud ASR provider. |+| Build a private speech API | [OpenAI-compatible API example](../examples/openai_api/), [client recipes](../examples/openai_api/CLIENTS.md), [JavaScript/TypeScript recipes](../examples/openai_api/JAVASCRIPT.md), and [workflow recipes](../examples/openai_api/WORKFLOWS.md) | Reuse LangChain, Dify, n8n, AutoGen, and other OpenAI-style clients without sending audio to a cloud ASR provider. || Add speech input to agents | [MCP server](../examples/mcp_server/) and [voice input](../examples/voice_input/) | Connect local ASR to Claude, Cursor, and desktop agent workflows. || Choose a deployment path | [Deployment matrix](./deployment_matrix.md) | Compare Python API, OpenAI API, Docker Compose, WebSocket, vLLM, MCP, batch, subtitles, and Triton. || Serve streaming ASR | [Runtime service docs](../runtime/readme.md) | Run WebSocket or service-mode ASR for live captioning and call-center style workloads. |@@ -37,7 +37,8 @@ curl http://localhost:8000/v1/audio/transcriptions \Recommended next steps:-- Run the [OpenAI-compatible API smoke test](../examples/openai_api/smoke_test.sh).+- Run the [OpenAI-compatible API smoke test](../examples/openai_api/smoke_test.sh) or the cross-platform [Python smoke test](../examples/openai_api/smoke_test.py).+- For Node.js or Next.js services, start from the [JavaScript/TypeScript recipes](../examples/openai_api/JAVASCRIPT.md).- Add authentication and network controls at your service boundary.- Record model name, device, driver, and audio duration in bug reports and benchmarks.diff --git a/docs/use_case_showcase_zh.md b/docs/use_case_showcase_zh.mdindex 972e2e3b4..ed2e1e508 100644--- a/docs/use_case_showcase_zh.md+++ b/docs/use_case_showcase_zh.md@@ -9,7 +9,7 @@ FunASR 不只是一个离线转写命令。这个页面把常见的评测、部| 本地转写一个文件 | [README 快速开始](../README_zh.md#快速开始) | 几分钟内验证安装、模型下载和首次推理。 || 对比准确率和速度 | [性能评测报告](https://modelscope.github.io/FunASR/zh/benchmark.html) | 选型前先查看 184 条长音频评测结果。 || 从 Whisper/云端 ASR 迁移 | [迁移指南](./migration_from_whisper_zh.md) | 将现有流水线映射到 FunASR,用代表性音频评测并规划安全上线。 |-| 搭建私有语音 API | [OpenAI 兼容 API 示例](../examples/openai_api/README_zh.md)、[客户端配方](../examples/openai_api/CLIENTS.md) 和 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md) | 复用 LangChain、Dify、n8n、AutoGen 等 OpenAI 风格客户端,音频不出内网。 |+| 搭建私有语音 API | [OpenAI 兼容 API 示例](../examples/openai_api/README_zh.md)、[客户端配方](../examples/openai_api/CLIENTS.md)、[JavaScript/TypeScript 配方](../examples/openai_api/JAVASCRIPT_zh.md) 和 [工作流配方](../examples/openai_api/WORKFLOWS_zh.md) | 复用 LangChain、Dify、n8n、AutoGen 等 OpenAI 风格客户端,音频不出内网。 || 给 Agent 增加语音输入 | [MCP 服务](../examples/mcp_server/) 和 [语音输入示例](../examples/voice_input/) | 将本地 ASR 接入 Claude、Cursor 和桌面 Agent 工作流。 || 选择部署路径 | [部署选型表](./deployment_matrix_zh.md) | 对比 Python API、OpenAI API、Docker Compose、WebSocket、vLLM、MCP、批处理、字幕和 Triton。 || 部署流式 ASR | [Runtime 服务文档](../runtime/readme_cn.md) | 面向实时字幕、客服、会议等低延迟场景。 |@@ -37,7 +37,8 @@ curl http://localhost:8000/v1/audio/transcriptions \建议下一步:-- 运行 [OpenAI 兼容 API smoke test](../examples/openai_api/smoke_test.sh)。+- 运行 [OpenAI 兼容 API smoke test](../examples/openai_api/smoke_test.sh) 或跨平台 [Python smoke test](../examples/openai_api/smoke_test.py)。+- Node.js 或 Next.js 服务可从 [JavaScript/TypeScript 配方](../examples/openai_api/JAVASCRIPT_zh.md) 开始。- 在服务边界增加鉴权、限流和网络访问控制。- 记录模型、设备、驱动、音频时长和处理耗时,便于复现问题和 benchmark。diff --git a/examples/openai_api/CLIENTS.md b/examples/openai_api/CLIENTS.mdindex 8520dd66c..24a21cbd2 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). For schema-driven imports or client generation, use the [OpenAPI spec](OPENAPI.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 JavaScript, TypeScript, and Next.js examples, see the [JavaScript/TypeScript recipes](JAVASCRIPT.md) or [Chinese JavaScript/TypeScript recipes](JAVASCRIPT_zh.md). 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).## Preflight@@ -42,6 +42,30 @@ for segment in getattr(result, "segments", []):Most OpenAI SDKs require an API key value even when the local FunASR server does not check it. Use any placeholder for local development, then add real authentication at your gateway if the service is shared.+## JavaScript and TypeScript++Use the [JavaScript/TypeScript recipes](JAVASCRIPT.md) for OpenAI JS SDK, built-in `fetch`, TypeScript helper functions, and Next.js route handlers. Minimal OpenAI SDK shape:++```javascript+import OpenAI from "openai";+import { createReadStream } from "node:fs";++const client = new OpenAI({+ baseURL: "http://localhost:8000/v1",+ apiKey: "local-development",+});++const result = await client.audio.transcriptions.create({+ model: "sensevoice",+ file: createReadStream("meeting.wav"),+ response_format: "verbose_json",+});++console.log(result.text);+```++For browser uploads, send audio to your backend first, then proxy to FunASR with authentication and upload limits. See the [Chinese JavaScript/TypeScript recipes](JAVASCRIPT_zh.md) for localized guidance.+## Plain Python requests```pythondiff --git a/examples/openai_api/JAVASCRIPT.md b/examples/openai_api/JAVASCRIPT.mdnew file mode 100644index 000000000..95c98af78--- /dev/null+++ b/examples/openai_api/JAVASCRIPT.md@@ -0,0 +1,180 @@+# JavaScript and TypeScript Recipes for the FunASR OpenAI-Compatible API++Use this guide when `funasr-server` is already running and you want to connect Node.js, TypeScript services, Next.js route handlers, or other JavaScript agent workflows to local speech recognition.++## Preflight++Start the API server first:++```bash+cd examples/openai_api+python server.py --model sensevoice --device cuda --port 8000+```++Then verify the service from another terminal:++```bash+python smoke_test.py --base-url http://localhost:8000+```++SDK base URLs include `/v1`; direct health checks do not:++```text+OpenAI SDK baseURL: http://localhost:8000/v1+Health endpoint: http://localhost:8000/health+Transcription URL: http://localhost:8000/v1/audio/transcriptions+```++## OpenAI JavaScript SDK++Install the official JavaScript SDK:++```bash+npm install openai+```++Create `transcribe.mjs`:++```javascript+import OpenAI from "openai";+import { createReadStream } from "node:fs";++const audioPath = process.argv[2] ?? "sample.wav";++const client = new OpenAI({+ baseURL: process.env.FUNASR_OPENAI_BASE_URL ?? "http://localhost:8000/v1",+ apiKey: process.env.OPENAI_API_KEY ?? "local-development",+});++const result = await client.audio.transcriptions.create({+ model: process.env.FUNASR_MODEL ?? "sensevoice",+ file: createReadStream(audioPath),+ response_format: "verbose_json",+});++console.log(result.text);+for (const segment of result.segments ?? []) {+ console.log(`${segment.start}s-${segment.end}s`, segment.text);+}+```++Run it:++```bash+node transcribe.mjs meeting.wav+```++Most OpenAI-compatible SDKs require an API key value even when the local FunASR server does not check it. Use any placeholder for local development, then add real authentication at your gateway if the service is shared.++## Built-in fetch without an SDK++Node.js 18+ includes `fetch`, `FormData`, and `Blob`, so you can call the API without third-party dependencies:++```javascript+import { readFile } from "node:fs/promises";+import { basename } from "node:path";++const baseUrl = process.env.FUNASR_BASE_URL ?? "http://localhost:8000";+const audioPath = process.argv[2] ?? "sample.wav";+const audio = await readFile(audioPath);++const form = new FormData();+form.append("file", new Blob([audio], { type: "audio/wav" }), basename(audioPath));+form.append("model", process.env.FUNASR_MODEL ?? "sensevoice");+form.append("response_format", "verbose_json");++const response = await fetch(`${baseUrl}/v1/audio/transcriptions`, {+ method: "POST",+ body: form,+});++if (!response.ok) {+ throw new Error(`FunASR request failed: ${response.status} ${await response.text()}`);+}++const result = await response.json();+console.log(result.text);+```++Use this pattern for queue workers, webhook workers, scheduled jobs, and small internal services.++## TypeScript helper++```typescript+import OpenAI from "openai";+import { createReadStream } from "node:fs";++export interface FunASRTranscript {+ text: string;+ segments?: Array<{ start: number; end: number; text: string; speaker?: number }>;+ language?: string;+ duration?: number;+ model?: string;+}++const client = new OpenAI({+ baseURL: process.env.FUNASR_OPENAI_BASE_URL ?? "http://localhost:8000/v1",+ apiKey: process.env.OPENAI_API_KEY ?? "local-development",+});++export async function transcribeWithFunASR(audioPath: string): Promise<FunASRTranscript> {+ const result = await client.audio.transcriptions.create({+ model: process.env.FUNASR_MODEL ?? "sensevoice",+ file: createReadStream(audioPath),+ response_format: "verbose_json",+ });++ return result as FunASRTranscript;+}+```++Keep the return type small and application-owned. FunASR can return richer metadata over time, and your application can opt into only the fields it needs.++## Next.js route handler++Proxy browser uploads through your backend so you can enforce authentication, file-size limits, and audit logs before audio reaches FunASR.++```typescript+export async function POST(request: Request) {+ const incoming = await request.formData();+ const file = incoming.get("file");++ if (!(file instanceof File)) {+ return Response.json({ error: "missing file" }, { status: 400 });+ }++ const upstream = new FormData();+ upstream.append("file", file, file.name || "audio.wav");+ upstream.append("model", "sensevoice");+ upstream.append("response_format", "verbose_json");++ const response = await fetch("http://funasr-api:8000/v1/audio/transcriptions", {+ method: "POST",+ body: upstream,+ });++ const body = await response.json();+ return Response.json(body, { status: response.status });+}+```++In Docker Compose or Kubernetes, replace `funasr-api` with the service name reachable from your web backend. Avoid sending browser traffic directly to an unauthenticated FunASR endpoint on a public network.++## Production checklist++- Put TLS, authentication, upload-size limits, and rate limits in front of the API.+- Set request timeouts based on maximum audio duration; long recordings need longer HTTP timeouts.+- Log audio duration, model alias, response format, latency, and upstream error text.+- Run `GET /health` and `GET /v1/models` during readiness checks before accepting user uploads.+- Keep audio upload handling on the server side for browser applications.+- Pin `openai` package versions in production services and retest after SDK upgrades.++## Troubleshooting++| Symptom | Fix |+|---|---|+| SDK reports a missing API key | Pass any placeholder `apiKey` for local development. |+| 404 from SDK calls | Use `baseURL=http://localhost:8000/v1`; direct endpoint calls use `http://localhost:8000`. |+| `unknown model` | Call `/v1/models` and use one of the returned aliases. |+| Browser upload fails with CORS or auth errors | Send uploads to your backend first, then proxy to FunASR. |+| Request times out | Increase SDK or fetch timeouts, or split very long audio. |diff --git a/examples/openai_api/JAVASCRIPT_zh.md b/examples/openai_api/JAVASCRIPT_zh.mdnew file mode 100644index 000000000..f85e1b78e--- /dev/null+++ b/examples/openai_api/JAVASCRIPT_zh.md@@ -0,0 +1,180 @@+# FunASR OpenAI 兼容 API JavaScript/TypeScript 接入配方++当 `funasr-server` 已经启动,而你希望把 Node.js、TypeScript 服务、Next.js route handler 或 JavaScript Agent 工作流接入本地语音识别时,可以按这份指南复制代码。++## 预检查++先启动 API 服务:++```bash+cd examples/openai_api+python server.py --model sensevoice --device cuda --port 8000+```++在另一个终端验证服务:++```bash+python smoke_test.py --base-url http://localhost:8000+```++SDK base URL 需要包含 `/v1`,直接健康检查不需要:++```text+OpenAI SDK baseURL: http://localhost:8000/v1+健康检查: http://localhost:8000/health+转写接口: http://localhost:8000/v1/audio/transcriptions+```++## OpenAI JavaScript SDK++安装官方 JavaScript SDK:++```bash+npm install openai+```++创建 `transcribe.mjs`:++```javascript+import OpenAI from "openai";+import { createReadStream } from "node:fs";++const audioPath = process.argv[2] ?? "sample.wav";++const client = new OpenAI({+ baseURL: process.env.FUNASR_OPENAI_BASE_URL ?? "http://localhost:8000/v1",+ apiKey: process.env.OPENAI_API_KEY ?? "local-development",+});++const result = await client.audio.transcriptions.create({+ model: process.env.FUNASR_MODEL ?? "sensevoice",+ file: createReadStream(audioPath),+ response_format: "verbose_json",+});++console.log(result.text);+for (const segment of result.segments ?? []) {+ console.log(`${segment.start}s-${segment.end}s`, segment.text);+}+```++运行:++```bash+node transcribe.mjs meeting.wav+```++多数 OpenAI 兼容 SDK 即使在本地服务不校验密钥时,也要求传入一个 API key。开发环境可以使用任意占位值;如果服务被多人共享,请在网关层增加真实鉴权。++## 不依赖 SDK 的内置 fetch 写法++Node.js 18+ 内置 `fetch`、`FormData` 和 `Blob`,可以不安装第三方依赖直接调用接口:++```javascript+import { readFile } from "node:fs/promises";+import { basename } from "node:path";++const baseUrl = process.env.FUNASR_BASE_URL ?? "http://localhost:8000";+const audioPath = process.argv[2] ?? "sample.wav";+const audio = await readFile(audioPath);++const form = new FormData();+form.append("file", new Blob([audio], { type: "audio/wav" }), basename(audioPath));+form.append("model", process.env.FUNASR_MODEL ?? "sensevoice");+form.append("response_format", "verbose_json");++const response = await fetch(`${baseUrl}/v1/audio/transcriptions`, {+ method: "POST",+ body: form,+});++if (!response.ok) {+ throw new Error(`FunASR request failed: ${response.status} ${await response.text()}`);+}++const result = await response.json();+console.log(result.text);+```++这个模式适合队列 worker、webhook worker、定时任务和小型内部服务。++## TypeScript helper++```typescript+import OpenAI from "openai";+import { createReadStream } from "node:fs";++export interface FunASRTranscript {+ text: string;+ segments?: Array<{ start: number; end: number; text: string; speaker?: number }>;+ language?: string;+ duration?: number;+ model?: string;+}++const client = new OpenAI({+ baseURL: process.env.FUNASR_OPENAI_BASE_URL ?? "http://localhost:8000/v1",+ apiKey: process.env.OPENAI_API_KEY ?? "local-development",+});++export async function transcribeWithFunASR(audioPath: string): Promise<FunASRTranscript> {+ const result = await client.audio.transcriptions.create({+ model: process.env.FUNASR_MODEL ?? "sensevoice",+ file: createReadStream(audioPath),+ response_format: "verbose_json",+ });++ return result as FunASRTranscript;+}+```++建议在应用侧维护一个小而稳定的返回类型。FunASR 后续可能返回更丰富的元数据,业务代码只需要消费自己关心的字段。++## Next.js route handler++浏览器上传建议先进入自己的后端,再由后端转发到 FunASR,这样可以统一做鉴权、文件大小限制和审计日志。++```typescript+export async function POST(request: Request) {+ const incoming = await request.formData();+ const file = incoming.get("file");++ if (!(file instanceof File)) {+ return Response.json({ error: "missing file" }, { status: 400 });+ }++ const upstream = new FormData();+ upstream.append("file", file, file.name || "audio.wav");+ upstream.append("model", "sensevoice");+ upstream.append("response_format", "verbose_json");++ const response = await fetch("http://funasr-api:8000/v1/audio/transcriptions", {+ method: "POST",+ body: upstream,+ });++ const body = await response.json();+ return Response.json(body, { status: response.status });+}+```++在 Docker Compose 或 Kubernetes 中,把 `funasr-api` 换成 Web 后端能访问到的 service name。不要把未鉴权的 FunASR 接口直接暴露给公网浏览器。++## 生产检查清单++- 在 API 前增加 TLS、鉴权、上传大小限制和限流。+- 根据最大音频时长设置请求超时;长录音需要更长的 HTTP timeout。+- 记录音频时长、模型别名、响应格式、延迟和上游错误文本。+- 接收用户上传前,先用 `GET /health` 和 `GET /v1/models` 做就绪检查。+- 浏览器应用应把音频上传处理留在服务端。+- 生产服务固定 `openai` 包版本,并在 SDK 升级后重新测试。++## 故障排查++| 现象 | 处理方式 |+|---|---|+| SDK 提示缺少 API key | 本地开发传入任意占位 `apiKey`。 |+| SDK 调用返回 404 | SDK 使用 `baseURL=http://localhost:8000/v1`;直接端点调用使用 `http://localhost:8000`。 |+| `unknown model` | 调用 `/v1/models`,使用返回的模型别名。 |+| 浏览器上传遇到 CORS 或鉴权错误 | 先上传到自己的后端,再由后端代理到 FunASR。 |+| 请求超时 | 增加 SDK 或 fetch 超时,或切分超长音频。 |diff --git a/examples/openai_api/README.md b/examples/openai_api/README.mdindex 2807bd52a..8af9622bf 100644--- a/examples/openai_api/README.md+++ b/examples/openai_api/README.md@@ -13,7 +13,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, 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).+Need copy-paste integration snippets for Python SDK, JavaScript/TypeScript, HTTP clients, agent tools, Postman, OpenAPI imports, or Dify/n8n-style workflows? See [Client recipes](CLIENTS.md), [JavaScript/TypeScript recipes](JAVASCRIPT.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@@ -95,7 +95,7 @@ Prefer no-code API checks? Import the [Postman collection](POSTMAN.md) and run h## 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)).+Works with: **LangChain**, **LlamaIndex**, **AutoGen**, **CrewAI**, **Semantic Kernel**, **Dify**, **n8n**, or any framework using OpenAI audio API. See [Client recipes](CLIENTS.md) and [JavaScript/TypeScript recipes](JAVASCRIPT.md) for SDK and agent-tool patterns, plus [workflow recipes](WORKFLOWS.md) for low-code HTTP nodes and webhook workers ([中文](WORKFLOWS_zh.md)).### LangChain Example```pythondiff --git a/examples/openai_api/README_zh.md b/examples/openai_api/README_zh.mdindex 26e9cc970..9a09f96fc 100644--- a/examples/openai_api/README_zh.md+++ b/examples/openai_api/README_zh.md@@ -13,7 +13,7 @@ python server.py --model sensevoice --device cuda --port 8000服务通常会在模型加载后启动。健康检查:`GET /health`。-需要直接复制的接入示例?可以继续查看 [客户端配方](CLIENTS.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN_zh.md) 和 [OpenAPI 规范](OPENAPI_zh.md)。+需要直接复制的接入示例?可以继续查看 [客户端配方](CLIENTS.md)、[JavaScript/TypeScript 配方](JAVASCRIPT_zh.md)、[工作流配方](WORKFLOWS_zh.md)、[Postman 集合](POSTMAN_zh.md) 和 [OpenAPI 规范](OPENAPI_zh.md)。### 端到端 smoke test@@ -94,7 +94,7 @@ curl http://localhost:8000/v1/audio/transcriptions \适用场景包括 **LangChain**、**LlamaIndex**、**AutoGen**、**CrewAI**、**Semantic Kernel**、**Dify**、**n8n** 和任何支持 OpenAI audio API 或 multipart HTTP 的系统。-- SDK 和 Agent tool 写法见 [客户端配方](CLIENTS.md)。+- SDK、JavaScript/TypeScript 和 Agent tool 写法见 [客户端配方](CLIENTS.md) 与 [JavaScript/TypeScript 配方](JAVASCRIPT_zh.md)。- Dify、n8n、HTTP 节点和 webhook worker 见 [工作流配方](WORKFLOWS_zh.md)。- 图形界面 smoke test 见 [Postman 集合](POSTMAN_zh.md)。- schema 驱动导入见 [OpenAPI 规范](OPENAPI_zh.md)。