feat: add mmx speech transcribe for speech-to-text (asr-1.0)

ERRORS.md

@@ -119,6 +119,24 @@ This document lists all error scenarios and the messages users will see.
 | `--out` path no write permission | `Permission denied: cannot write to "${outPath}".` |
 | Disk full | `Disk full — cannot write audio file.` |
 
+### `mmx speech transcribe`
+
+| Scenario | Error Message |
+|---|---|
+| No `--file` (and no positional path) in non-interactive mode | `Missing required argument: --file` |
+| Audio file not found | `File not found: ${fullPath}` |
+| Invalid `--response-format` | `Invalid response format "${fmt}". Supported: json, verbose_json, srt, vtt` |
+| Audio file above 50 MB | `Audio file is ${size} MB; speech-to-text allows at most 50 MB: ${fullPath}` |
+| Server rejects the upload as too large (HTTP 413) | `Audio file exceeds the speech-to-text size limit (HTTP 413). ${message}` |
+| Audio flagged by the sensitivity filter (HTTP 422) | `Input audio flagged by sensitivity filter (${message})` |
+| `--stream` with a response format other than `json` | `response_format "${fmt}" cannot be combined with stream=true; streaming returns incremental json only.` |
+| `--stream` together with `--out` | `--stream and --out cannot be combined.` |
+| `--out` unwritable (permissions, missing directory) | `File system error: ${message}` |
+| Disk full | `Disk full — cannot write transcript file.` |
+
+Audio longer than 500 seconds and unsupported/corrupt audio are rejected by the API; the
+server message is surfaced verbatim (e.g. `API error: invalid params, ... (HTTP 400)`).
+
 ### `mmx speech voices`
 
 All errors fall under [Network Errors](#networkerrors).

README.md

@@ -20,7 +20,7 @@
 - **Text** — Multi-turn chat, streaming, system prompts, JSON output
 - **Image** — Text-to-image with aspect ratio and batch controls
 - **Video** — Async video generation with progress tracking
-- **Speech** — TTS with 30+ voices, speed control, streaming playback
+- **Speech** — TTS with 30+ voices, speed control, streaming playback; speech-to-text transcription (json, verbose_json, srt, vtt)
 - **Vision** — Image understanding and description
 - **Search** — Web search powered by MiniMax
 - **Dual Region** — Seamless Global (`api.minimax.io`) and CN (`api.minimaxi.com`) support
@@ -54,6 +54,7 @@ mmx auth login --api-key sk-xxxxx
 mmx text chat --message "What is MiniMax?"
 mmx image "A cat in a spacesuit"
 mmx speech synthesize --text "Hello!" --out hello.mp3
+mmx speech transcribe --file meeting.mp3
 mmx video generate --prompt "Ocean waves at sunset"
 mmx search "MiniMax AI latest news"
 mmx vision photo.jpg
@@ -116,6 +117,25 @@ echo "Breaking news" | mmx speech synthesize --text-file - --out news.mp3
 mmx speech voices
 ```
 
+```bash
+# Speech-to-text (asr-1.0)
+mmx speech transcribe --file meeting.mp3
+mmx speech transcribe --file call.mp3 --language zh
+mmx speech transcribe --file talk.mp3 --response-format verbose_json --output json
+mmx speech transcribe --file talk.mp3 --response-format srt --out talk.srt
+mmx speech transcribe --file long.mp3 --stream
+```
+
+`mmx speech transcribe` accepts wav, aiff, flac, m4a, mp3, aac, opus, and ogg files up to
+50 MB and 500 seconds. Audio above 50 MB is rejected locally before upload; the 500 second
+limit is enforced by the API. Omitting `--language` enables mixed-language recognition.
+`--response-format json` (default) prints the transcript, `verbose_json` adds speakers and
+per-segment timestamps, and `srt` / `vtt` return subtitle documents. `n_speakers` and
+`segments` are part of the response, so pass `--output json` to see them. `--stream` prints
+incremental text and requires `json`; when stdout is not a terminal it accumulates into a single
+JSON result unless `--output text` is passed. `mmx speech recognize` is an alias for
+`mmx speech transcribe`.
+
 ### `mmx vision`
 
 ```bash

README_CN.md

@@ -20,7 +20,7 @@
 - **文本对话** — 多轮对话、流式输出、系统提示词、JSON 格式输出
 - **图像生成** — 文生图，支持比例和批量控制
 - **视频生成** — 异步生成，进度追踪
-- **语音合成** — 30+ 音色、语速调节、流式播放
+- **语音** — 语音合成（30+ 音色、语速调节、流式播放）与语音识别（音频转文字，支持 json、verbose_json、srt、vtt）
 - **图像理解** — 图片描述与识别
 - **网络搜索** — MiniMax 搜索引擎
 - **双区域** — 国际版（`api.minimax.io`）和国内版（`api.minimaxi.com`）自动切换
@@ -54,6 +54,7 @@ mmx auth login --api-key sk-xxxxx
 mmx text chat --message "你好，MiniMax！"
 mmx image "一只穿宇航服的猫"
 mmx speech synthesize --text "你好！" --out hello.mp3
+mmx speech transcribe --file meeting.mp3
 mmx video generate --prompt "海浪拍打礁石"
 mmx search "MiniMax AI 最新动态"
 mmx vision photo.jpg
@@ -111,6 +112,23 @@ echo "头条新闻" | mmx speech synthesize --text-file - --out news.mp3
 mmx speech voices
 ```
 
+```bash
+# 语音识别（asr-1.0）
+mmx speech transcribe --file meeting.mp3
+mmx speech transcribe --file call.mp3 --language zh
+mmx speech transcribe --file talk.mp3 --response-format verbose_json --output json
+mmx speech transcribe --file talk.mp3 --response-format srt --out talk.srt
+mmx speech transcribe --file long.mp3 --stream
+```
+
+`mmx speech transcribe` 支持 wav、aiff、flac、m4a、mp3、aac、opus、ogg 格式，音频上限为
+50 MB / 500 秒。**超过 50 MB 会在上传前直接报错**；500 秒时长上限由服务端校验。
+不传 `--language` 时启用混合语言识别。`--response-format json`（默认）输出转写文本，
+`verbose_json` 附带说话人标识与分段 时间戳，`srt` / `vtt` 直接返回字幕文档；
+`n_speakers` 与 `segments` 属于响应字段，需加 `--output json` 才能看到。
+`--stream` 逐段输出文本，仅支持 `json`；当 stdout 不是终端时会汇总为单个 JSON 结果，
+除非显式传 `--output text`。`mmx speech recognize` 是 `mmx speech transcribe` 的别名。
+
 ### `mmx vision`
 
 ```bash

SDK.md

@@ -120,6 +120,24 @@ for await (const chunk of stream) {
 // List voices
 const voices = await sdk.speech.voices();
 const englishVoices = await sdk.speech.voices('en');
+
+// Speech-to-text
+const transcript = await sdk.speech.transcribe({
+  file: './meeting.mp3',
+  language: 'zh',
+});
+console.log(transcript.text, transcript.duration);
+
+// Speech-to-text, streamed
+const deltas = await sdk.speech.transcribe({ file: './meeting.mp3', stream: true });
+for await (const event of deltas) {
+  process.stdout.write(event.delta); // concatenate delta values in `index` order
+}
+// The generator ends at the API's final event (finish: true) and releases the
+// connection, so breaking out of the loop early is safe. Unlike the CLI, which
+// warns and continues, the SDK throws SDKError on a malformed stream chunk.
+// Non-SSE responses and streams ending without finish: true also throw SDKError
+// during iteration; text received before an error may be incomplete.
 ```
 
 ### Vision

docs/cli-design.md

@@ -20,7 +20,8 @@ mmx
 ├── text
 │   └── chat               Send a chat completion (M3)
 ├── speech
-│   └── synthesize         Synchronous TTS, ≤10k chars
+│   ├── synthesize         Synchronous TTS, ≤10k chars
+│   └── transcribe         Speech-to-text, ≤50 MB / ≤500 s (asr-1.0)
 ├── image
 │   └── generate           Generate images (image-01)
 ├── video

skill/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: mmx-cli
-description: Use mmx to generate text, images, video, and speech via the MiniMax AI platform. Use when the user wants to create media content, chat with MiniMax models, perform web search, or manage MiniMax API resources from the terminal.
+description: Use mmx to generate text, images, video, and speech, and to transcribe audio, via the MiniMax AI platform. Use when the user wants to create media content, chat with MiniMax models, transcribe audio to text, perform web search, or manage MiniMax API resources from the terminal.
 ---
 
 # MiniMax CLI — Agent Skill Guide
 
-Use `mmx` to generate text, images, video, speech, and perform web search via the MiniMax AI platform.
+Use `mmx` to generate text, images, video, speech, transcribe audio, and perform web search via the MiniMax AI platform.
 
 ## Prerequisites
 
@@ -205,6 +205,61 @@ echo "Breaking news." | mmx speech synthesize --text-file - --out news.mp3
 
 ---
 
+### speech transcribe
+
+Speech-to-text. Default model: `asr-1.0`. Accepts wav, aiff, flac, m4a, mp3, aac, opus, and
+ogg files up to 50 MB and 500 seconds.
+
+```bash
+mmx speech transcribe --file <path> [flags]
+```
+
+| Flag | Type | Description |
+|---|---|---|
+| `--file <path>` | string | Audio file to transcribe (required; also accepted as a positional argument) |
+| `--model <model>` | string | `asr-1.0` (default) |
+| `--response-format <fmt>` | string | `json` (default), `verbose_json`, `srt`, `vtt` |
+| `--language <code>` | string | BCP-47 language hint (`zh`, `en`, `ja`, ...). Omit for automatic/mixed-language detection |
+| `--timestamp-level <level>` | string | `sentence` (default) or `word`; applies to `verbose_json` / `srt` / `vtt` |
+| `--stream` | boolean | Stream incremental text to stdout. Requires `--response-format json` |
+| `--out <path>` | string | Write the result to a file instead of stdout |
+
+```bash
+mmx speech transcribe --file meeting.mp3
+# stdout: transcript text
+
+mmx speech transcribe --file call.mp3 --language zh --output json
+# stdout: {"text":"...","duration":12.3,"trace_id":"..."}
+
+mmx speech transcribe --file talk.mp3 --response-format verbose_json --timestamp-level word --output json
+# stdout: adds n_speakers and word-level segments
+
+mmx speech transcribe --file talk.mp3 --response-format srt --out talk.srt
+# saves talk.srt; stdout: {"saved":".../talk.srt"}
+
+mmx speech transcribe --file long.mp3 --stream
+# stdout: text as it is recognized (add --output text when piping)
+```
+
+Notes:
+- `mmx speech recognize` is an alias for `mmx speech transcribe`.
+- `--stream` cannot be combined with `--out`; redirect stdout instead.
+- `--stream` prints deltas only in text output mode. stdout that is not a terminal defaults to
+  `json` (as everywhere else in this CLI), which accumulates the streamed text into one JSON
+  result — pass `--output text` to pipe streamed text, e.g.
+  `mmx speech transcribe --file long.mp3 --stream --output text > transcript.txt`.
+- `srt` / `vtt` results are subtitle documents and are printed or saved verbatim.
+- Without `--out`, `--output json` prints the full API response for `json` / `verbose_json`.
+  Plain-text output prints the transcript only, so add `--output json` to read `n_speakers`
+  and `segments`.
+- A stream that ends without the API's final event raises a warning on stderr, since the
+  transcript may be truncated.
+- Input validation (missing file, unsupported format, over 50 MB, `--stream` with a non-json
+  format) fails before anything is uploaded; the API stays the authority for the 500 s duration
+  limit and codec support.
+
+---
+
 ### vision describe
 
 Image understanding via VLM. Provide either `--image` or `--file-id`, not both.

src/client/endpoints.ts

@@ -6,6 +6,10 @@ export function speechEndpoint(baseUrl: string): string {
   return `${baseUrl}/v1/t2a_v2`;
 }
 
+export function speechToTextEndpoint(baseUrl: string): string {
+  return `${baseUrl}/v1/speech_to_text`;
+}
+
 export function voicesEndpoint(baseUrl: string): string {
   return `${baseUrl}/v1/get_voice`;
 }

src/commands/help.ts

@@ -12,6 +12,7 @@ interface ApiRef {
 const API_REFS: ApiRef[] = [
   { command: 'mmx text chat',            title: 'Text Generation (Chat Completion)',    path: '/docs/api-reference/text-post' },
   { command: 'mmx speech synthesize',    title: 'Speech T2A (Text-to-Audio)',           path: '/docs/api-reference/speech-t2a-http' },
+  { command: 'mmx speech transcribe',    title: 'Speech STT (Speech-to-Text)',          path: '/docs/api-reference/speech-to-text' },
   { command: 'mmx image generate',       title: 'Image Generation (T2I / I2I)',         path: '/docs/api-reference/image-generation-t2i' },
   { command: 'mmx video generate',       title: 'Video Generation (T2V / I2V / S2V)',   path: '/docs/api-reference/video-generation' },
   { command: 'mmx search query',         title: 'Web Search',                           path: '/docs/api-reference/web-search' },