fix(speech): handle qwen3-filetrans singular result.transcription_url

Normalize async ASR transcription items so waiting mode downloads text and --out works without changing shared media task types.

Author: hopelynd

packages/commands/src/commands/speech/recognize.ts

@@ -15,6 +15,7 @@ import {
   resolveAsrApi,
   buildAsrFlashRequest,
   buildAsyncAsrLanguageFields,
+  collectAsrTranscriptionItems,
   extractAsrFlashText,
   type AsrApiRoute,
   type AsrFlashFamily,
@@ -79,7 +80,7 @@ function assertSyncFlashFlagsAllowed(
   const unsupported: string[] = [];
   if (flags.diarization === true) unsupported.push("--diarization");
   if (flags.speakerCount !== undefined) unsupported.push("--speaker-count");
-  // qwen3 sync Flash 不走 vocabulary_id；input-audio Flash（fun-asr-flash* / qwen-audio-*-asr-flash）官方支持
+  // qwen3 sync Flash does not use vocabulary_id; input-audio Flash (fun-asr-flash* / qwen-audio-*-asr-flash) does
   if (flashFamily === "qwen3" && flags.vocabularyId !== undefined) {
     unsupported.push("--vocabulary-id");
   }
@@ -308,7 +309,7 @@ async function handleAsyncMode(
     },
   });
 
-  const results = result.output.results ?? [];
+  const results = collectAsrTranscriptionItems(result.output);
 
   if (results.length === 0) {
     emitResult({ task_id: taskId, status: result.output.task_status }, format);

packages/commands/tests/e2e/speech-recognize.e2e.test.ts

@@ -97,7 +97,7 @@ describe("e2e: speech recognize", () => {
   });
 
   test("speech recognize realtime 模型报用法错误", async () => {
-    // 使用 --dry-run：跳过 auth，避免 CI 无密钥时先以 AUTH(3) 退出
+    // Use --dry-run to skip auth so CI without API keys still hits USAGE(2)
     const { stderr, exitCode } = await runCommandE2e(SPEECH_ROUTES, [
       "speech",
       "recognize",
@@ -188,6 +188,87 @@ describe("e2e: speech recognize", () => {
     expect(exitCode).toBe(2);
     expect(stderr).toMatch(/exactly one --url|sync Flash/i);
   });
+
+  test("speech recognize qwen3-filetrans 轮询成功后下载 result.transcription_url", async () => {
+    const server = http.createServer((request, response) => {
+      const url = request.url ?? "";
+      const chunks: Buffer[] = [];
+      request.on("data", (chunk: Buffer) => chunks.push(chunk));
+      request.on("end", () => {
+        response.writeHead(200, { "Content-Type": "application/json" });
+        if (url.startsWith("/api/v1/services/audio/asr/transcription")) {
+          response.end(
+            JSON.stringify({
+              output: { task_id: "task-qwen3", task_status: "PENDING" },
+              request_id: "req-submit",
+            }),
+          );
+          return;
+        }
+        if (url.startsWith("/api/v1/tasks/")) {
+          const address = server.address() as AddressInfo;
+          response.end(
+            JSON.stringify({
+              output: {
+                task_id: "task-qwen3",
+                task_status: "SUCCEEDED",
+                result: {
+                  transcription_url: `http://127.0.0.1:${address.port}/transcription.json`,
+                },
+              },
+              request_id: "req-poll",
+            }),
+          );
+          return;
+        }
+        if (url.startsWith("/transcription.json")) {
+          response.end(
+            JSON.stringify({
+              file_url: "https://example.com/a.wav",
+              transcripts: [{ text: "你好世界", sentences: [{ text: "你好世界" }] }],
+            }),
+          );
+          return;
+        }
+        response.writeHead(404);
+        response.end(JSON.stringify({ message: `unexpected path: ${url}` }));
+      });
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address() as AddressInfo;
+    const outDir = makeE2eOutputDir("speech-recognize-qwen3-filetrans");
+    const outPath = join(outDir, "result.json");
+
+    try {
+      const { stdout, stderr, exitCode } = await runCommandE2e(SPEECH_ROUTES, [
+        "speech",
+        "recognize",
+        "--model",
+        "qwen3-asr-flash-filetrans",
+        "--url",
+        "https://example.com/a.wav",
+        "--language",
+        "zh",
+        "--api-key",
+        "sk-e2e-placeholder",
+        "--base-url",
+        `http://127.0.0.1:${address.port}`,
+        "--poll-interval",
+        "1",
+        "--out",
+        outPath,
+        "--quiet",
+      ]);
+
+      expect(exitCode, stderr).toBe(0);
+      expect(stdout).toContain("你好世界");
+      expect(JSON.parse(readFileSync(outPath, "utf8"))).toMatchObject({
+        transcripts: [{ text: "你好世界" }],
+      });
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
 });
 
 describe.skipIf(!isBailianE2EMediaEnabled() || !isDashScopeE2EReady())(

packages/core/src/client/asr-routes.ts

@@ -136,7 +136,7 @@ export function resolveAsrApi(model: string): AsrApiRoute {
 
 /** Infer audio container hint for input-audio Flash `parameters.format`. */
 export function inferAudioFormatHint(audioUrl: string): string {
-  // data URI：data:audio/mpeg;base64,... → mp3；data:audio/x-wav;... → wav
+  // data URI: data:audio/mpeg;base64,... → mp3; data:audio/x-wav;... → wav
   const dataType = /^data:audio\/([^;,]+)/i.exec(audioUrl)?.[1]?.toLowerCase();
   if (dataType) {
     if (dataType === "mpeg") return "mp3";
@@ -156,14 +156,14 @@ export interface BuildAsrFlashRequestOpts {
   model: string;
   audioUrl: string;
   language?: string;
-  /** 预编译热词 ID；仅 input-audio Flash（fun-asr-flash* / qwen-audio-*-asr-flash）官方支持 */
+  /** Precompiled hotword vocabulary ID; supported for input-audio Flash (fun-asr-flash* / qwen-audio-*-asr-flash). */
   vocabularyId?: string;
   flashFamily: AsrFlashFamily;
 }
 
 /**
- * 按异步路由的 language 字段风格构造语种参数。
- * qwen3-asr-flash-filetrans* → `language`；其余异步模型 → `language_hints`。
+ * Build language fields for async ASR routes.
+ * qwen3-asr-flash-filetrans* → `language`; other async models → `language_hints`.
  */
 export function buildAsyncAsrLanguageFields(
   languageStyle: "language_hints" | "language",
@@ -181,7 +181,7 @@ export function buildAsrFlashRequest(opts: BuildAsrFlashRequestOpts): Record<str
   const { model, audioUrl, language, vocabularyId, flashFamily } = opts;
 
   if (flashFamily === "input-audio") {
-    // 与官方 Qwen-Audio / Fun-ASR-Flash 文档一致：语种走 language_hints，热词走 vocabulary_id
+    // Match official Qwen-Audio / Fun-ASR-Flash docs: language_hints + vocabulary_id
     const parameters: Record<string, unknown> = {
       format: inferAudioFormatHint(audioUrl),
       sample_rate: "16000",
@@ -294,3 +294,34 @@ export function extractAsrFlashText(
   }
   return texts.join("");
 }
+
+/**
+ * Normalize async ASR task transcription items:
+ * - classic models: `output.results[]`
+ * - qwen3-asr-flash-filetrans*: `output.result.transcription_url`
+ */
+export function collectAsrTranscriptionItems(output: {
+  results?: Array<{
+    file_url?: string;
+    transcription_url?: string;
+    subtask_status?: string;
+    code?: string;
+    message?: string;
+  }>;
+  result?: { transcription_url?: string };
+}): Array<{
+  file_url?: string;
+  transcription_url?: string;
+  subtask_status?: string;
+  code?: string;
+  message?: string;
+}> {
+  if (output.results && output.results.length > 0) {
+    return output.results;
+  }
+  const transcriptionUrl = output.result?.transcription_url;
+  if (typeof transcriptionUrl === "string" && transcriptionUrl.length > 0) {
+    return [{ transcription_url: transcriptionUrl, subtask_status: "SUCCEEDED" }];
+  }
+  return [];
+}

packages/core/src/client/index.ts

@@ -37,6 +37,7 @@ export {
 export {
   buildAsrFlashRequest,
   buildAsyncAsrLanguageFields,
+  collectAsrTranscriptionItems,
   extractAsrFlashText,
   inferAudioFormatHint,
   resolveAsrApi,

packages/core/src/types/api.ts

@@ -538,32 +538,41 @@ export interface DashScopeASRRequest {
   };
   parameters?: {
     channel_id?: number[];
-    /** fun-asr / paraformer / qwen-audio filetrans 等经典异步模型 */
+    /** Classic async models (fun-asr / paraformer / qwen-audio filetrans, etc.) */
     language_hints?: string[];
-    /** qwen3-asr-flash-filetrans* 使用单数字段 language */
+    /** qwen3-asr-flash-filetrans* uses singular `language` */
     language?: string;
     diarization_enabled?: boolean;
     speaker_count?: number;
     vocabulary_id?: string;
   };
 }
 
+export interface DashScopeASRTranscriptionItem {
+  file_url?: string;
+  transcription_url?: string;
+  subtask_status?: string;
+  code?: string;
+  message?: string;
+}
+
 export interface DashScopeASRTaskResult {
   output: {
     task_id: string;
     task_status: "PENDING" | "RUNNING" | "SUCCEEDED" | "FAILED" | "UNKNOWN";
-    results?: Array<{
-      file_url?: string;
+    /** Multi-file async results (fun-asr / paraformer / qwen-audio filetrans, etc.) */
+    results?: DashScopeASRTranscriptionItem[];
+    /** Singular result returned by qwen3-asr-flash-filetrans* on success */
+    result?: {
       transcription_url?: string;
-      subtask_status?: string;
-      code?: string;
-      message?: string;
-    }>;
+    };
     task_metrics?: {
       TOTAL: number;
       SUCCEEDED: number;
       FAILED: number;
     };
+    code?: string;
+    message?: string;
   };
   usage?: Record<string, unknown>;
   request_id: string;

packages/core/src/types/index.ts

@@ -48,6 +48,7 @@ export type {
   ChatTool,
   DashScopeASRRequest,
   DashScopeASRTaskResult,
+  DashScopeASRTranscriptionItem,
   DashScopeAsyncResponse,
   DashScopeImageRequest,
   DashScopeImageSyncResponse,

packages/core/tests/asr-routes.test.ts

@@ -2,6 +2,7 @@ import { expect, test } from "vite-plus/test";
 import {
   buildAsrFlashRequest,
   buildAsyncAsrLanguageFields,
+  collectAsrTranscriptionItems,
   extractAsrFlashText,
   inferAudioFormatHint,
   resolveAsrApi,
@@ -194,3 +195,19 @@ test("extractAsrFlashText reads qwen3 choices and input-audio text fields", () =
     ),
   ).toBe("nested sentence");
 });
+
+test("collectAsrTranscriptionItems prefers results[] then singular result", () => {
+  expect(
+    collectAsrTranscriptionItems({
+      results: [{ transcription_url: "https://example.com/a.json", file_url: "https://a.wav" }],
+    }),
+  ).toEqual([{ transcription_url: "https://example.com/a.json", file_url: "https://a.wav" }]);
+
+  expect(
+    collectAsrTranscriptionItems({
+      result: { transcription_url: "https://example.com/qwen3.json" },
+    }),
+  ).toEqual([{ transcription_url: "https://example.com/qwen3.json", subtask_status: "SUCCEEDED" }]);
+
+  expect(collectAsrTranscriptionItems({})).toEqual([]);
+});