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(http): distinguish pinned JSON recipes from current plain-text responses
zhifu gao13520d656818
diff --git a/web-pages/product-site/legacy/blog/self-hosted-deepgram-assemblyai-alternative.html b/web-pages/product-site/legacy/blog/self-hosted-deepgram-assemblyai-alternative.htmlindex 631379ae9..a92b9e038 100644--- a/web-pages/product-site/legacy/blog/self-hosted-deepgram-assemblyai-alternative.html+++ b/web-pages/product-site/legacy/blog/self-hosted-deepgram-assemblyai-alternative.html@@ -5,7 +5,7 @@<link rel="canonical" href="https://www.funasr.com/blog/self-hosted-deepgram-assemblyai-alternative.html"><link rel="alternate" hreflang="en" href="https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"><link rel="alternate" hreflang="zh" href="https://www.funasr.com/blog/self-hosted-deepgram-assemblyai-alternative.html"><link rel="alternate" hreflang="x-default" href="https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet"><script type="application/ld+json">-{"@context":"https://schema.org","@type":"BlogPosting","headline":"从 Deepgram / AssemblyAI 迁移到自托管 FunASR:接入与验收 | FunASR Blog","description":"评估自托管转写迁移:映射请求和结果契约,检查鉴权、返回格式、模型质量与运维成本。提供 FunASR 本地 JSON 示例,不承诺厂商 API 或 SDK 直接替换。","datePublished":"2026-06-23","dateModified":"2026-09-09","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/blog/self-hosted-deepgram-assemblyai-alternative.html"},"image":"https://www.funasr.com/logo.png"}+{"@context":"https://schema.org","@type":"BlogPosting","headline":"从 Deepgram / AssemblyAI 迁移到自托管 FunASR:接入与验收 | FunASR Blog","description":"评估自托管转写迁移:映射请求和结果契约,检查鉴权、返回格式、模型质量与运维成本。提供 FunASR 本地 JSON 示例,不承诺厂商 API 或 SDK 直接替换。","datePublished":"2026-06-23","dateModified":"2026-11-12","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/blog/self-hosted-deepgram-assemblyai-alternative.html"},"image":"https://www.funasr.com/logo.png"}</script><style>:root{--primary:#2563eb;--primary-dark:#1d4ed8;--bg:#fff;--surface:#f8fafc;--border:#e2e8f0;--text:#0f172a;--text-soft:#475569;--text-muted:#94a3b8;--radius:12px}*{margin:0;padding:0;box-sizing:border-box}@@ -78,6 +78,7 @@ python -m pip check</code></pre>-F "response_format=json"</code></pre><p>预期结构是包含 <code>text</code> 的 JSON 对象,具体内容取决于音频与模型。120 秒是示例客户端超时,不是可处理音频时长或吞吐承诺。使用 OpenAI Python SDK 的基本调用可参考<a href="/blog/self-hosted-openai-whisper-api-alternative.html">本地转写接入指南</a>;这不意味着原厂商 SDK 可以原样使用。</p><h2>明确返回格式边界</h2>+<p data-http-contract="version-boundary"><strong>版本边界:</strong>本文固定的 1.4.15 安装示例中,<code>response_format=text</code> 返回 <code>application/json</code> 编码的字符串,下表描述该历史版本。当前 main 已通过 <a href="https://github.com/modelscope/FunASR/pull/3874">#3874</a> 改为 <code>text/plain</code> 纯文本(<a href="https://github.com/modelscope/FunASR/blob/be264e9382b4fef735536f3d278ee14514098a1a/funasr/bin/_server_app.py">已合并处理器源码</a>)。这不代表已安装服务自动升级;请核对实际安装版本和响应内容,再决定是否进行 JSON 解码。</p><table data-http-contract="formats"><thead><tr><th>response_format</th><th>包内处理器的行为</th></tr></thead><tbody><tr data-response-format="json"><td><code>json</code></td><td>返回含 <code>text</code> 的 JSON 对象。</td></tr><tr data-response-format="verbose_json"><td><code>verbose_json</code></td><td>返回结构化 JSON,包括 <code>segments</code>、<code>duration</code> 等字段;具体时间与说话人信息依赖模型和实际结果。</td></tr>diff --git a/web-pages/product-site/legacy/blog/self-hosted-openai-whisper-api-alternative.html b/web-pages/product-site/legacy/blog/self-hosted-openai-whisper-api-alternative.htmlindex bf980d6d8..77cb82c33 100644--- a/web-pages/product-site/legacy/blog/self-hosted-openai-whisper-api-alternative.html+++ b/web-pages/product-site/legacy/blog/self-hosted-openai-whisper-api-alternative.html@@ -5,7 +5,7 @@<meta property="og:type" content="article"><meta property="og:url" content="https://www.funasr.com/blog/self-hosted-openai-whisper-api-alternative.html"><meta property="og:image" content="https://www.funasr.com/logo.png"><link rel="canonical" href="https://www.funasr.com/blog/self-hosted-openai-whisper-api-alternative.html"><link rel="alternate" hreflang="en" href="https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"><link rel="alternate" hreflang="zh" href="https://www.funasr.com/blog/self-hosted-openai-whisper-api-alternative.html"><link rel="alternate" hreflang="x-default" href="https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">-<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","headline":"把语音转写接进自己的 API","description":"从上传一段录音、取回文本开始,走通本地应用调用,并在对外开放前检查认证、返回格式和部署边界。","datePublished":"2026-06-18","dateModified":"2026-09-09","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/blog/self-hosted-openai-whisper-api-alternative.html"},"image":"https://www.funasr.com/logo.png"}</script>+<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","headline":"把语音转写接进自己的 API","description":"从上传一段录音、取回文本开始,走通本地应用调用,并在对外开放前检查认证、返回格式和部署边界。","datePublished":"2026-06-18","dateModified":"2026-11-12","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/blog/self-hosted-openai-whisper-api-alternative.html"},"image":"https://www.funasr.com/logo.png"}</script><style>:root{--primary:#2563eb;--primary-dark:#1d4ed8;--bg:#fff;--surface:#f8fafc;--border:#e2e8f0;--text:#0f172a;--text-soft:#475569;--text-muted:#94a3b8;--radius:12px}*{margin:0;padding:0;box-sizing:border-box}body{font-family:'Inter',-apple-system,sans-serif;color:var(--text);line-height:1.7}@@ -98,6 +98,7 @@ print(result.text)</code></pre><p>根据语言、时延、硬件和说话人需求查看<a href="/docs/model-selection.html">模型选型</a>、<a href="/docs/moss-transcribe-diarize.html">MOSS 转写与说话人分离</a>和<a href="/deploy/">部署矩阵</a>。本文不提供新的准确率或性能排名;验收方法见<a href="/blog/meeting-transcript-acceptance.html">会议录音验收清单</a>。</p><section data-editorial="appendix"><h2>附录:核对返回契约</h2><h2>包内服务的兼容范围</h2>+<p data-http-contract="version-boundary"><strong>版本边界:</strong>本文固定的 1.4.15 安装示例中,<code>response_format=text</code> 返回 <code>application/json</code> 编码的字符串,下表描述该历史版本。当前 main 已通过 <a href="https://github.com/modelscope/FunASR/pull/3874">#3874</a> 改为 <code>text/plain</code> 纯文本(<a href="https://github.com/modelscope/FunASR/blob/be264e9382b4fef735536f3d278ee14514098a1a/funasr/bin/_server_app.py">已合并处理器源码</a>)。这不代表已安装服务自动升级;请核对实际安装版本和响应内容,再决定是否进行 JSON 解码。</p><table id="api-contract" data-http-contract="formats"><thead><tr><th>项目</th><th>当前行为与接入要求</th></tr></thead><tbody><tr><td>请求</td><td>multipart 文件上传;路由声明 <code>file</code>、<code>model</code>、<code>language</code>、<code>response_format</code> 和 FunASR 扩展 <code>spk</code>。语言和说话人能力仍受所选模型限制。</td></tr><tr data-response-format="json"><td><code>json</code></td><td>返回带 <code>text</code> 的 JSON 对象,适合先验证基本文本转写。</td></tr>diff --git a/web-pages/product-site/legacy/en/blog/self-hosted-deepgram-assemblyai-alternative.html b/web-pages/product-site/legacy/en/blog/self-hosted-deepgram-assemblyai-alternative.htmlindex dd3682ddf..4cff1795b 100644--- a/web-pages/product-site/legacy/en/blog/self-hosted-deepgram-assemblyai-alternative.html+++ b/web-pages/product-site/legacy/en/blog/self-hosted-deepgram-assemblyai-alternative.html@@ -5,7 +5,7 @@<link rel="canonical" href="https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"><link rel="alternate" hreflang="en" href="https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"><link rel="alternate" hreflang="zh" href="https://www.funasr.com/blog/self-hosted-deepgram-assemblyai-alternative.html"><link rel="alternate" hreflang="x-default" href="https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet"><script type="application/ld+json">-{"@context":"https://schema.org","@type":"BlogPosting","headline":"Migrating from Deepgram / AssemblyAI to Self-Hosted FunASR | FunASR Blog","description":"Plan a self-hosted transcription migration: map request and response contracts, authentication, formats, model quality and operating costs. Includes a local FunASR JSON recipe, not a drop-in vendor SDK replacement.","datePublished":"2026-06-23","dateModified":"2026-09-09","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"},"image":"https://www.funasr.com/logo.png"}+{"@context":"https://schema.org","@type":"BlogPosting","headline":"Migrating from Deepgram / AssemblyAI to Self-Hosted FunASR | FunASR Blog","description":"Plan a self-hosted transcription migration: map request and response contracts, authentication, formats, model quality and operating costs. Includes a local FunASR JSON recipe, not a drop-in vendor SDK replacement.","datePublished":"2026-06-23","dateModified":"2026-11-12","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/en/blog/self-hosted-deepgram-assemblyai-alternative.html"},"image":"https://www.funasr.com/logo.png"}</script><style>:root{--primary:#2563eb;--primary-dark:#1d4ed8;--bg:#fff;--surface:#f8fafc;--border:#e2e8f0;--text:#0f172a;--text-soft:#475569;--text-muted:#94a3b8;--radius:12px}*{margin:0;padding:0;box-sizing:border-box}@@ -78,6 +78,7 @@ python -m pip check</code></pre>-F "response_format=json"</code></pre><p>The expected structure is a JSON object containing <code>text</code>; its content depends on the audio and model. The 120-second client timeout is an example, not an audio-duration or throughput guarantee. For a basic OpenAI Python SDK call, see the <a href="/en/blog/self-hosted-openai-whisper-api-alternative.html">local transcription integration guide</a>. This does not make the original vendor SDK reusable unchanged.</p><h2>Make response-format limits explicit</h2>+<p data-http-contract="version-boundary"><strong>Version boundary:</strong> The pinned 1.4.15 recipe returns an <code>application/json</code> encoded string for <code>response_format=text</code>; the table below describes that historical version. Current main returns a bare <code>text/plain</code> transcript after <a href="https://github.com/modelscope/FunASR/pull/3874">#3874</a> (<a href="https://github.com/modelscope/FunASR/blob/be264e9382b4fef735536f3d278ee14514098a1a/funasr/bin/_server_app.py">merged handler source</a>). This does not automatically upgrade an installed service: check its installed version and response bytes before choosing JSON decoding.</p><table data-http-contract="formats"><thead><tr><th>response_format</th><th>Packaged handler behavior</th></tr></thead><tbody><tr data-response-format="json"><td><code>json</code></td><td>Returns a JSON object containing <code>text</code>.</td></tr><tr data-response-format="verbose_json"><td><code>verbose_json</code></td><td>Returns structured JSON with fields including <code>segments</code> and <code>duration</code>. Actual timing and speaker information depend on the model and result.</td></tr>diff --git a/web-pages/product-site/legacy/en/blog/self-hosted-openai-whisper-api-alternative.html b/web-pages/product-site/legacy/en/blog/self-hosted-openai-whisper-api-alternative.htmlindex 03a230117..8209261ec 100644--- a/web-pages/product-site/legacy/en/blog/self-hosted-openai-whisper-api-alternative.html+++ b/web-pages/product-site/legacy/en/blog/self-hosted-openai-whisper-api-alternative.html@@ -5,7 +5,7 @@<meta property="og:type" content="article"><meta property="og:url" content="https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"><meta property="og:image" content="https://www.funasr.com/logo.png"><link rel="canonical" href="https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"><link rel="alternate" hreflang="en" href="https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"><link rel="alternate" hreflang="zh" href="https://www.funasr.com/blog/self-hosted-openai-whisper-api-alternative.html"><link rel="alternate" hreflang="x-default" href="https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"><link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">-<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","headline":"Add transcription to your own API","description":"Start with one recording and a text response. Connect a local application, then check authentication, response formats and deployment boundaries.","datePublished":"2026-06-18","dateModified":"2026-09-09","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"},"image":"https://www.funasr.com/logo.png"}</script>+<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","headline":"Add transcription to your own API","description":"Start with one recording and a text response. Connect a local application, then check authentication, response formats and deployment boundaries.","datePublished":"2026-06-18","dateModified":"2026-11-12","author":{"@type":"Organization","name":"FunASR / Tongyi Lab"},"publisher":{"@type":"Organization","name":"FunASR","logo":{"@type":"ImageObject","url":"https://www.funasr.com/logo.png"}},"mainEntityOfPage":{"@type":"WebPage","@id":"https://www.funasr.com/en/blog/self-hosted-openai-whisper-api-alternative.html"},"image":"https://www.funasr.com/logo.png"}</script><style>:root{--primary:#2563eb;--primary-dark:#1d4ed8;--bg:#fff;--surface:#f8fafc;--border:#e2e8f0;--text:#0f172a;--text-soft:#475569;--text-muted:#94a3b8;--radius:12px}*{margin:0;padding:0;box-sizing:border-box}body{font-family:'Inter',-apple-system,sans-serif;color:var(--text);line-height:1.7}@@ -98,6 +98,7 @@ print(result.text)</code></pre><p>Choose by language, latency, hardware and speaker requirements using <a href="/en/docs/model-selection.html">model selection</a>, <a href="/en/docs/moss-transcribe-diarize.html">MOSS transcription and diarization</a> and the <a href="/en/deploy/">deployment matrix</a>. This article supplies no new accuracy or performance ranking. For acceptance criteria, see the <a href="/en/blog/meeting-transcript-acceptance.html">meeting-audio checklist</a>.</p><section data-editorial="appendix"><h2>Appendix: verify the response contract</h2><h2>Compatibility of the packaged handler</h2>+<p data-http-contract="version-boundary"><strong>Version boundary:</strong> The pinned 1.4.15 recipe returns an <code>application/json</code> encoded string for <code>response_format=text</code>; the table below describes that historical version. Current main returns a bare <code>text/plain</code> transcript after <a href="https://github.com/modelscope/FunASR/pull/3874">#3874</a> (<a href="https://github.com/modelscope/FunASR/blob/be264e9382b4fef735536f3d278ee14514098a1a/funasr/bin/_server_app.py">merged handler source</a>). This does not automatically upgrade an installed service: check its installed version and response bytes before choosing JSON decoding.</p><table id="api-contract" data-http-contract="formats"><thead><tr><th>Item</th><th>Current behavior and integration requirement</th></tr></thead><tbody><tr><td>Request</td><td>Multipart upload. The route declares <code>file</code>, <code>model</code>, <code>language</code>, <code>response_format</code> and the FunASR extension <code>spk</code>. Language and speaker capabilities depend on the selected model.</td></tr><tr data-response-format="json"><td><code>json</code></td><td>A JSON object with <code>text</code>, suitable for a first basic transcription check.</td></tr>diff --git a/web-pages/product-site/tests/test_http_blog_contracts.py b/web-pages/product-site/tests/test_http_blog_contracts.pyindex 8167766a4..4876fb3fe 100644--- a/web-pages/product-site/tests/test_http_blog_contracts.py+++ b/web-pages/product-site/tests/test_http_blog_contracts.py@@ -325,7 +325,20 @@ def test_example_links_do_not_own_packaged_installation_or_schema(site_tree, previsible_text(link)-def test_packaged_format_implementation_still_matches_documented_boundary():[email protected]("prefix,slug", PAGES)+def test_visible_version_boundary_separates_pinned_recipe_from_current_main(site_tree, prefix, slug):+ soup = read_page(site_tree, prefix, slug)+ notice = soup.select_one('article [data-http-contract="version-boundary"]')+ text = visible_text(notice)+ for value in ("1.4.15", "response_format=text", "application/json", "text/plain", "main"):+ assert value in text, (value, text)+ assert notice.select_one('a[href="https://github.com/modelscope/FunASR/pull/3874"]')+ source = "https://github.com/modelscope/FunASR/blob/be264e9382b4fef735536f3d278ee14514098a1a/funasr/bin/_server_app.py"+ assert notice.select_one(f'a[href="{source}"]')+ assert notice.find_next("table") == soup.select_one('[data-http-contract="formats"]')+++def test_current_packaged_text_format_returns_plain_text():tree = ast.parse((REPO / "funasr/bin/_server_app.py").read_text())handler = next(node for node in ast.walk(tree)if isinstance(node, ast.AsyncFunctionDef) and node.name == "transcribe")@@ -338,7 +351,7 @@ def test_packaged_format_implementation_still_matches_documented_boundary():and node.test.left.id == "response_format"and node.test.comparators[0].value == "text")returned = text_branch.body[0].value- assert isinstance(returned, ast.Call) and returned.func.id == "JSONResponse"+ assert isinstance(returned, ast.Call) and returned.func.id == "PlainTextResponse"assert ast.dump(returned.args[0]) == ast.dump(ast.parse('result["text"]', mode="eval").body)