|
| 1 | +# JavaScript and TypeScript Recipes for the FunASR OpenAI-Compatible API |
| 2 | + |
| 3 | +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. |
| 4 | + |
| 5 | +## Preflight |
| 6 | + |
| 7 | +Start the API server first: |
| 8 | + |
| 9 | +```bash |
| 10 | +cd examples/openai_api |
| 11 | +python server.py --model sensevoice --device cuda --port 8000 |
| 12 | +``` |
| 13 | + |
| 14 | +Then verify the service from another terminal: |
| 15 | + |
| 16 | +```bash |
| 17 | +python smoke_test.py --base-url http://localhost:8000 |
| 18 | +``` |
| 19 | + |
| 20 | +SDK base URLs include `/v1`; direct health checks do not: |
| 21 | + |
| 22 | +```text |
| 23 | +OpenAI SDK baseURL: http://localhost:8000/v1 |
| 24 | +Health endpoint: http://localhost:8000/health |
| 25 | +Transcription URL: http://localhost:8000/v1/audio/transcriptions |
| 26 | +``` |
| 27 | + |
| 28 | +## OpenAI JavaScript SDK |
| 29 | + |
| 30 | +Install the official JavaScript SDK: |
| 31 | + |
| 32 | +```bash |
| 33 | +npm install openai |
| 34 | +``` |
| 35 | + |
| 36 | +Create `transcribe.mjs`: |
| 37 | + |
| 38 | +```javascript |
| 39 | +import OpenAI from "openai"; |
| 40 | +import { createReadStream } from "node:fs"; |
| 41 | + |
| 42 | +const audioPath = process.argv[2] ?? "sample.wav"; |
| 43 | + |
| 44 | +const client = new OpenAI({ |
| 45 | + baseURL: process.env.FUNASR_OPENAI_BASE_URL ?? "http://localhost:8000/v1", |
| 46 | + apiKey: process.env.OPENAI_API_KEY ?? "local-development", |
| 47 | +}); |
| 48 | + |
| 49 | +const result = await client.audio.transcriptions.create({ |
| 50 | + model: process.env.FUNASR_MODEL ?? "sensevoice", |
| 51 | + file: createReadStream(audioPath), |
| 52 | + response_format: "verbose_json", |
| 53 | +}); |
| 54 | + |
| 55 | +console.log(result.text); |
| 56 | +for (const segment of result.segments ?? []) { |
| 57 | + console.log(`${segment.start}s-${segment.end}s`, segment.text); |
| 58 | +} |
| 59 | +``` |
| 60 | +
|
| 61 | +Run it: |
| 62 | +
|
| 63 | +```bash |
| 64 | +node transcribe.mjs meeting.wav |
| 65 | +``` |
| 66 | +
|
| 67 | +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. |
| 68 | +
|
| 69 | +## Built-in fetch without an SDK |
| 70 | +
|
| 71 | +Node.js 18+ includes `fetch`, `FormData`, and `Blob`, so you can call the API without third-party dependencies: |
| 72 | +
|
| 73 | +```javascript |
| 74 | +import { readFile } from "node:fs/promises"; |
| 75 | +import { basename } from "node:path"; |
| 76 | + |
| 77 | +const baseUrl = process.env.FUNASR_BASE_URL ?? "http://localhost:8000"; |
| 78 | +const audioPath = process.argv[2] ?? "sample.wav"; |
| 79 | +const audio = await readFile(audioPath); |
| 80 | + |
| 81 | +const form = new FormData(); |
| 82 | +form.append("file", new Blob([audio], { type: "audio/wav" }), basename(audioPath)); |
| 83 | +form.append("model", process.env.FUNASR_MODEL ?? "sensevoice"); |
| 84 | +form.append("response_format", "verbose_json"); |
| 85 | + |
| 86 | +const response = await fetch(`${baseUrl}/v1/audio/transcriptions`, { |
| 87 | + method: "POST", |
| 88 | + body: form, |
| 89 | +}); |
| 90 | + |
| 91 | +if (!response.ok) { |
| 92 | + throw new Error(`FunASR request failed: ${response.status} ${await response.text()}`); |
| 93 | +} |
| 94 | + |
| 95 | +const result = await response.json(); |
| 96 | +console.log(result.text); |
| 97 | +``` |
| 98 | +
|
| 99 | +Use this pattern for queue workers, webhook workers, scheduled jobs, and small internal services. |
| 100 | +
|
| 101 | +## TypeScript helper |
| 102 | +
|
| 103 | +```typescript |
| 104 | +import OpenAI from "openai"; |
| 105 | +import { createReadStream } from "node:fs"; |
| 106 | + |
| 107 | +export interface FunASRTranscript { |
| 108 | + text: string; |
| 109 | + segments?: Array<{ start: number; end: number; text: string; speaker?: number }>; |
| 110 | + language?: string; |
| 111 | + duration?: number; |
| 112 | + model?: string; |
| 113 | +} |
| 114 | + |
| 115 | +const client = new OpenAI({ |
| 116 | + baseURL: process.env.FUNASR_OPENAI_BASE_URL ?? "http://localhost:8000/v1", |
| 117 | + apiKey: process.env.OPENAI_API_KEY ?? "local-development", |
| 118 | +}); |
| 119 | + |
| 120 | +export async function transcribeWithFunASR(audioPath: string): Promise<FunASRTranscript> { |
| 121 | + const result = await client.audio.transcriptions.create({ |
| 122 | + model: process.env.FUNASR_MODEL ?? "sensevoice", |
| 123 | + file: createReadStream(audioPath), |
| 124 | + response_format: "verbose_json", |
| 125 | + }); |
| 126 | + |
| 127 | + return result as FunASRTranscript; |
| 128 | +} |
| 129 | +``` |
| 130 | +
|
| 131 | +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. |
| 132 | +
|
| 133 | +## Next.js route handler |
| 134 | +
|
| 135 | +Proxy browser uploads through your backend so you can enforce authentication, file-size limits, and audit logs before audio reaches FunASR. |
| 136 | +
|
| 137 | +```typescript |
| 138 | +export async function POST(request: Request) { |
| 139 | + const incoming = await request.formData(); |
| 140 | + const file = incoming.get("file"); |
| 141 | + |
| 142 | + if (!(file instanceof File)) { |
| 143 | + return Response.json({ error: "missing file" }, { status: 400 }); |
| 144 | + } |
| 145 | + |
| 146 | + const upstream = new FormData(); |
| 147 | + upstream.append("file", file, file.name || "audio.wav"); |
| 148 | + upstream.append("model", "sensevoice"); |
| 149 | + upstream.append("response_format", "verbose_json"); |
| 150 | + |
| 151 | + const response = await fetch("http://funasr-api:8000/v1/audio/transcriptions", { |
| 152 | + method: "POST", |
| 153 | + body: upstream, |
| 154 | + }); |
| 155 | + |
| 156 | + const body = await response.json(); |
| 157 | + return Response.json(body, { status: response.status }); |
| 158 | +} |
| 159 | +``` |
| 160 | +
|
| 161 | +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. |
| 162 | +
|
| 163 | +## Production checklist |
| 164 | +
|
| 165 | +- Put TLS, authentication, upload-size limits, and rate limits in front of the API. |
| 166 | +- Set request timeouts based on maximum audio duration; long recordings need longer HTTP timeouts. |
| 167 | +- Log audio duration, model alias, response format, latency, and upstream error text. |
| 168 | +- Run `GET /health` and `GET /v1/models` during readiness checks before accepting user uploads. |
| 169 | +- Keep audio upload handling on the server side for browser applications. |
| 170 | +- Pin `openai` package versions in production services and retest after SDK upgrades. |
| 171 | +
|
| 172 | +## Troubleshooting |
| 173 | +
|
| 174 | +| Symptom | Fix | |
| 175 | +|---|---| |
| 176 | +| SDK reports a missing API key | Pass any placeholder `apiKey` for local development. | |
| 177 | +| 404 from SDK calls | Use `baseURL=http://localhost:8000/v1`; direct endpoint calls use `http://localhost:8000`. | |
| 178 | +| `unknown model` | Call `/v1/models` and use one of the returned aliases. | |
| 179 | +| Browser upload fails with CORS or auth errors | Send uploads to your backend first, then proxy to FunASR. | |
| 180 | +| Request times out | Increase SDK or fetch timeouts, or split very long audio. | |
0 commit comments