minimax-av · diff
git:20260908.d9249a8 to git:20260908.5ebc0ca
32 added, 35 removed. Audit A to A.
---
name: minimax-av
description: MiniMax 全模态理解 CLI，双子命令。transcribe：音频转文本（asr-1.0，8 种格式 ≤50MB/≤500s，支持 SRT/VTT 字幕与说话人分离时间戳）；understand：视觉理解（MiniMax-M3 原生，视频 mp4/mov 等 + 图片 png/jpg/webp/gif，≤100MB 可混合多文件，问答/摘要/JSON 输出）。模型、端点、API Key 全部走 config.json 可换。用于录音转写、字幕生产、视频分析、图片理解、会议纪要。
---
# minimax-av — MiniMax 全模态理解（音频转写 + 视觉理解）
## 场景
- **transcribe**：录音/语音备忘录/访谈转文字（多格式、≤500 秒、可出 SRT/VTT 字幕与说话人分离时间戳）
- - **understand**：视频内容问答/摘要（M3 原生视频理解）+ **图片理解/对比/文字提取**（可混合多文件）
+ - **understand**：视频内容问答/摘要（M3 原生视频理解）+ 图片理解/对比/文字提取（可混合多文件）
## 触发条件
- 用户给出音频文件要求转写，或给出视频文件要求理解/描述/分析/问答时。MiniMax 生态（Token Plan key）的音视频需求。
+ 用户给出音频文件要求转写/出字幕，或给出视频/图片文件要求理解、描述、分析、问答时。
- ## 输入
+ ## 输入（硬限制）
- | 子命令 | 文件 | 限制（官方/实测） |
+ | 子命令 | 文件 | 限制 |
|---|---|---|
| `transcribe` | wav/aiff/flac/m4a/mp3/aac/opus/ogg | ≤**50MB**（413）、≤**500 秒**（400，超长不截断直接拒）；裸 PCM 不支持 |
| `understand` | 视频 mp4/mov/avi/mkv/webm/flv/wmv/mpeg；**图片 png/jpg/webp/gif** | 单文件 ≤100MB（config 可调）；**图片 >2MB 建议先缩放**（脚本会提示）；时长未标注 |
- 参数：`--out 文件`（落盘）、`--show-usage`（stderr 打印延迟/用量）；transcribe 另有 **`--format`**（输出格式，见下）；understand 另有 `--prompt`、`--json`、`--max-tokens`。
+ 参数：`--out 文件`（落盘）、`--show-usage`（stderr 打印延迟/用量）；transcribe 另有 **`--format`**；understand 另有 `--prompt`、`--json`、`--max-tokens`。
### 时间戳/字幕（transcribe 的 --format）
| format | 输出 | 适合 |
|---|---|---|
| `json`（默认） | 纯文本 + duration | 快速转写 |
| `verbose_json` | **句级时间戳 + 说话人分离**（[S1] 0.02s-5.32s 文本，含 n_speakers） | 会议纪要、访谈 |
| `srt` / `vtt` | **标准字幕格式**（00:00:00,020 --> 00:00:05,320） | 视频配字幕 |
- 注意：srt/vtt/verbose_json 启用说话人分离与时间戳对齐，**不能与流式同用**（本 skill 非流式，无此限制）。
+ 注意：这三种格式启用时间戳对齐与说话人分离，不能与流式同用（本 skill 非流式，无此限制）。
## 步骤
```bash
python3 scripts/minimax_av.py transcribe 录音.mp3
python3 scripts/minimax_av.py transcribe meeting.mp3 --format srt --out 字幕.srt
+ python3 scripts/minimax_av.py transcribe interview.wav --format verbose_json # 说话人+时间戳
python3 scripts/minimax_av.py understand video.mp4 --prompt "总结内容" --out result.txt
python3 scripts/minimax_av.py understand cover.png --prompt "提取图中所有文字"
- python3 scripts/minimax_av.py understand img1.png img2.jpg --prompt "对比这两张图"
+ python3 scripts/minimax_av.py understand img1.png img2.jpg video.mp4 --prompt "对比分析"
```
+ 超 500 秒的长音频先切分（ffmpeg，每段留余量）：
+
+ ```bash
+ ffmpeg -i long.mp3 -f segment -segment_time 480 -c copy part_%03d.mp3
+ ```
+
## 判断标准
- - understand 输出为空 → think 剥离后无正文 → 增大 --max-tokens（M3 推理占额）
- - transcribe 转录为空 → 检查音频是否有有效语音
+ - transcribe 空输出 → 检查音频是否有有效语音
+ - understand 空回答 → think 剥离后无正文 → 增大 --max-tokens（M3 推理占额）
+ - 专有名词识别错 → 换 wav 无损格式重试（有损压缩会降低识别质量），或转录后人工校对
## 输出
- stdout：转录文本 / 视频分析文本（已剥离 M3 的 `<think>` 推理段）。`--out` 同时落盘。错误写 stderr，退出码非 0。
+ stdout：转录文本 / 字幕 / 视觉分析文本（已剥离 `<think>` 推理段）。`--out` 同时落盘。错误写 stderr，退出码非 0。
## 异常处理
| 症状 | 处理 |
|---|---|
| 401 | key 无效 → 检查 config.json 或环境变量 MINIMAX_API_KEY |
| 429 | 限流（并发勿超 10；M3 官方 RPM：免费 20 / 充值 200）→ 退避重试 |
- | "需要audio文件，实际是 video" | 视频先抽音轨：`ffmpeg -i in.mp4 -vn -b:a 64k out.mp3` |
- | "需要video文件，实际是 audio" | 音频转写用 `transcribe` 子命令 |
- | understand 空回答 | max_tokens 被 M3 推理吃满 → 加大 --max-tokens（默认 4096） |
+ | 400 超长 | 音频超 500 秒 → 切分（命令见上） |
+ | 413 超大 | 超 50MB → `ffmpeg -i in -b:a 64k out.mp3` 压缩 |
+ | "需要media文件，实际是 audio" | 音频转写用 `transcribe` 子命令 |
+ | understand 空回答 | max_tokens 被 M3 推理吃满 → 加大 --max-tokens |
## 数据回流（2026-09-08 实测）
- - **正确的视频格式是 `video_url`**（`image_url` + video/mime 会被明确拒绝 2013"not supported"）；图片走 `image_url` + data URL（ec-xhs-cover-prompt-reverse 卡片 2026-07-31 实测的同款方案）
- - **图片 >2MB 建议先缩放**（卡片实测经验，脚本会 stderr 提示）
- - **M3 的推理藏在 content 的 `<think>` 标签里**（不是 reasoning_content 字段）——脚本已内置剥离；reasoning_content 兜底逻辑仍保留
- - **wav 识别质量优于 mp3**：同一段音频 mp3 转出"质谱"（错）、wav 转出"智谱"（对）；但同一文件多次请求结果也有波动（ASR 非确定性）——重要场景建议 wav + 人工抽查
- - MiniMax ASR **无热词参数**（智谱 GLM-ASR 有 hotwords）——专有名词场景识别差异靠 wav 格式补偿
- - 响应带 `duration`；srt/vtt/verbose_json 启用时间戳对齐与说话人分离（**不能与 stream=true 同用**，本 skill 非流式无此限制）
- - config 换 vision_model 后其他模型调用不报错但"看不到"视频（视频理解是 M3 原生能力）——换模型需理解能力差异
- - base_url 是中国站 `api.minimaxi.com`；国际站为 `api.minimax.io`（config 可换）
-
- ## 与 glm-asr（智谱）选型对照
-
- | 维度 | glm-asr | minimax-av transcribe |
- |---|---|---|
- | 时长 | ≤30s | **≤500s** |
- | 格式 | wav/mp3 | 8 种（wav/aiff/flac/m4a/mp3/aac/opus/ogg） |
- | 时间戳/字幕 | ❌ 无 | **✅ srt/vtt/verbose_json + 说话人分离** |
- | 热词 | ✅ hotwords | ❌（wav 补偿） |
- | 短语音+专有名词 | 首选 | 可用 |
- | 长音频/字幕/会议纪要 | 不适用 | **首选** |
- | 图片理解 | glm-vision（GLM 视觉） | ✅ M3 也能看（可混合视频） |
+ - **正确的视频格式是 `video_url`**（`image_url` + video/mime 会被明确拒绝 2013）；图片走 `image_url` + data URL，多文件可混合
+ - **M3 的推理藏在 content 的 `<think>` 标签里**（不是 reasoning_content 字段）——脚本已内置剥离
+ - **wav 识别质量优于有损压缩格式**；同一文件多次请求结果存在波动（ASR 非确定性）——重要场景建议 wav + 人工抽查
+ - MiniMax ASR **无热词参数**——专有名词识别建议 wav 无损格式补偿，或转录后人工校对
+ - 响应自带 `duration`；图片 >2MB 建议先缩放（脚本会 stderr 提示）
+ - config 换 vision_model 后其他模型调用不报错但"看不到"视频（视频理解是 M3 原生能力）
+ - base_url 中国站 `api.minimaxi.com`；国际站 `api.minimax.io`（config 可换）
## 版本
- v1.2 · 2026-09-08 · understand 泛化为视觉理解：图片识别（png/jpg/webp/gif）+ 多文件混合输入 + >2MB 缩放提示；修 WEBP 误判 AVI
+ v1.2.1 · 2026-09-08 · 清理内部引用（纯对外文档）+ 根 README 同步 v1.2
+ v1.2 · 2026-09-08 · understand 泛化：图片识别（png/jpg/webp/gif）+ 多文件混合输入 + >2MB 缩放提示；修 WEBP 误判 AVI
v1.1 · 2026-09-08 · 时间戳/字幕支持（--format srt/vtt/verbose_json+说话人分离）+ 官方规格修正（50MB/500s/8 格式）
- v1.0 · 2026-09-08 · 项项（冒烟先行→开发→11 项功能测试→安装）
+ v1.0 · 2026-09-08 · 首发（冒烟先行→开发→11 项功能测试→安装）