---
name: mimo-capabilities
description: MiMo 模型原生能力配置指南 - 图像理解、音频理解、视频理解、TTS 语音合成、网络搜索。当主模型为 MiMo 时使用这些方法。
tags: [mimo, xiaomi, vision, audio, video, tts, search, multimodal]
---

# MiMo 模型原生能力配置指南

## 概述

MiMo 是小米研发的 AI 大模型，支持多种原生能力。当主模型为 MiMo 时，应使用 MiMo 的原生 API 而非第三方工具。

## 模型感知路由规则

**关键原则：根据当前主模型选择对应的方法**

| 功能 | MiMo 模型 | MiniMax 模型 (mmx-cli) |
|------|-----------|--------------|
| 图像理解 | MiMo Vision API | `mmx vision describe` |
| 音频理解 | MiMo Audio API | 不支持 |
| 视频理解 | MiMo Video API | 不支持 |
| TTS | MiMo TTS API | `mmx speech synthesize` |
| 网络搜索 | MiMo Web Search API | `mmx search query` |
| 图像生成 | 不支持 | `mmx image generate` |
| 视频生成 | 不支持 | `mmx video generate` |
| 音乐生成 | 不支持 | `mmx music generate` |

## 1. 图像理解

### 支持的模型
- mimo-v2.5
- mimo-v2-omni

### 使用方法

```bash
python3 ~/.hermes/scripts/mimo_vision.py "https://example.com/image.jpg" "描述这张图片"
python3 ~/.hermes/scripts/mimo_vision.py /path/to/image.png "这张图片里有什么？"
```

### 图片限制
- 格式：JPEG, PNG, GIF, WebP, BMP
- 大小：单张不超过 50MB

## 2. 音频理解

### 支持的模型
- mimo-v2.5
- mimo-v2-omni

### 使用方法

```bash
python3 ~/.hermes/scripts/mimo_audio.py "https://example.com/audio.wav" "这段音频说了什么？"
python3 ~/.hermes/scripts/mimo_audio.py /path/to/audio.mp3 "转录这段音频"
```

### 音频限制
- 格式：MP3, WAV, FLAC, M4A, OGG
- 大小：URL 不超过 100MB，Base64 不超过 50MB

## 3. 视频理解

### 支持的模型
- mimo-v2.5
- mimo-v2-omni

### 使用方法

```bash
python3 ~/.hermes/scripts/mimo_video.py "https://example.com/video.mp4" "描述视频内容"
python3 ~/.hermes/scripts/mimo_video.py /path/to/video.mp4 "视频里发生了什么？" --fps 2
```

### 参数说明
- --fps: 每秒提取帧数，范围 0.1-10，默认 2
- --resolution: default（默认）或 max（最高分辨率）

### 视频限制
- 格式：MP4, MOV, AVI, WMV
- 大小：URL 不超过 300MB，Base64 不超过 50MB

## 4. TTS 语音合成

### 支持的模型

| 模型 | 功能 |
|------|------|
| mimo-v2.5-tts | 内置音色，支持唱歌 |
| mimo-v2.5-tts-voicedesign | 音色设计 |
| mimo-v2.5-tts-voiceclone | 音色克隆 |

### 内置音色列表
- 中文：冰糖（默认）, 茉莉, 苏打, 白桦
- 英文：Mia, Chloe, Milo, Dean

### 使用方法

```bash
# 内置音色
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --voice 冰糖 --output output.wav

# 音色设计（VoiceDesign）
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --design "年轻女性，温柔甜美" --output output.wav

# 音色克隆（VoiceClone）
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --clone voice_sample.mp3 --output output.wav

# 带风格指令
python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --voice 冰糖 --style "用欢快活泼的语气" --output output.wav
```

### VoiceDesign 音色设计详解

通过自然语言描述从零生成全新音色，无需参考音频。

**描述维度**（可自由组合）：
- 性别年龄：年轻女性、中年男性、小女孩、年迈老先生
- 口音语言：标准普通话、带北方口音、说英语
- 音色特征：低沉有磁性、清脆明亮、温柔甜美、略带沙哑
- 发声方式：像纪录片旁白、像新闻主播、声音位置靠后
- 性格气质：沉稳而有感染力、元气满满、饱经风霜

**高级特性**：
- 对复杂、模糊、甚至相互矛盾的描述也能合理解读
- 不局限于"男/女/青年/老年"粗粒度标签
- 适合游戏NPC、动画角色、虚拟主播、品牌IP、有声剧

**示例**：
```
--design "一位年迈的老先生，说带北方口音的普通话，语速缓慢而沉稳，嗓音略带沙哑和沧桑感，仿佛一位饱经风霜的老爷爷在讲故事，充满岁月的智慧。"
```

### VoiceClone 音色克隆详解

只需短至数秒的参考音频，无需训练/标注/微调，直接复刻音色。

**保留的特征**：
- 原始说话人的音色身份
- 气息、节奏、习惯性停顿等个人特征

**复用能力**：克隆后的音色可叠加使用全部控制能力（自然语言指令、音频标签、导演剧本）

**示例**：
```
# 提供参考音频 + 风格指令
--clone reference.mp3 --style "用尖锐刻薄的嗓音，带着狐假虎威的得意感"
```

### 风格控制标签（行内音频标签）

在文本中用括号插入标签，精准控制情绪/状态/风格：

**标签类型**：
- 基础情感：开心、悲伤、生气、害怕、惊讶、兴奋
- 复杂情感：忧郁、释然、无奈、内疚、嫉妒、疲惫
- 整体语调：温柔、冷淡、活泼、严肃、慵懒、俏皮
- 音色定位：磁性、醇厚、清亮、空灵、天真、甜美
- 方言：东北话、四川话、河南话、粤语
- 唱歌：唱歌（必须放在最开头）

**高级用法**：
- 支持中英双语标签
- 支持多标签叠加（用 `｜` 分隔）
- 支持开放文本描述

**示例**：
```
(调侃) 老张你当时不是说这条航线稳得很吗……
(模仿自信，提高音量) "系统全绿，放心走。"
(突然停顿) ……现在呢？
(爆发，愤怒压不住) 现在整艘船都在报警！
(低声｜情绪塌陷般平静) ……算了。
(轻笑｜带点释然) 也挺好，至少是一起看的。
```

### 导演剧本级结构化输入

对于一致性要求高的场景（有声剧、游戏NPC、角色化对话），支持分层描述：

```bash
python3 ~/.hermes/scripts/mimo_tts.py \
  --text "你们求我垂怜..." \
  --voice 白桦 \
  --style "CHARACTER: 曾是守护九天的神祇，见证了凡人的无药可救后，决定以灭世来完成最终的净化。
SCENE: 悬浮于崩塌的祭坛之上，俯视下方在火海中哀嚎的信徒。
DIRECTION: 充分打开胸腔共鸣，声音位置靠后，音色如古钟般低沉且带有金属质感的磁性。" \
  --output output.wav
```

**分层说明**：
- CHARACTER：人物身份、背景、性格
- SCENE：场景环境、情境
- DIRECTION：详细的发声指导（共鸣、语调、气声、咬字等）

### TTS API 要点
1. 合成文本必须放在 assistant 角色的 content 中
2. user 角色消息可选，用于传递风格指令
3. 流式调用时输出格式指定为 pcm16

## 5. 网络搜索

### 支持的模型
- mimo-v2.5-pro, mimo-v2.5, mimo-v2-pro, mimo-v2-omni, mimo-v2-flash

### 前置条件
在 MiMo Console 启用 Web Search 插件。

### 使用方法

```bash
python3 ~/.hermes/scripts/mimo_search.py "武汉明天天气"
python3 ~/.hermes/scripts/mimo_search.py "附近美食" --city 武汉 --region 湖北
```

### 参数说明
- --max-keywords: 每轮搜索最大关键词数，默认 3
- --force/--no-force: 是否强制搜索，默认强制
- --limit: 搜索结果数量，默认 1
- --country/--region/--city: 本地化搜索位置

## 环境变量

```bash
XIAOMI_API_KEY=tp-xxxxx
XIAOMI_BASE_URL=https://token-plan-sgp.xiaomimimo.com/v1
```

**注意**：环境变量需持久化到 `~/.bashrc`，否则新 terminal session 会丢失。

## ⚠️ 图片输入配置（关键）

MiMo chat API **不支持图片输入**。用户发图片时，如果 Hermes 把图片直接塞进 chat completions 请求，会返回 `404: No endpoints found that support image input`。

### 必须设置 `image_input_mode: tool`

```bash
hermes config set agent.image_input_mode tool
```

- `auto`（默认）= 尝试直接把图片发给主模型 → MiMo 会 404
- `tool` = 强制图片走 vision 工具 → 正确路由到 MiMo Vision API

### Vision API Key 必须显式写入 config

`XIAOMI_API_KEY` 环境变量**不会**自动传给 Hermes vision 工具。必须手动填入 config。

**有两个 vision section 都需要 API key：**

| 路径 | 用途 |
|------|------|
| `auxiliary.vision.api_key` | 主 vision 工具配置（含 provider/model/base_url） |
| `tools.vision.api_key` | 工具层 vision 配置 |

```bash
# 方法：从 .bashrc 提取 key 并写入（hermes config set 无法展开未 source 的环境变量）
python3 << 'EOF'
import yaml
key = open('/home/ubuntu/.bashrc').read().split('XIAOMI_API_KEY=')[1].split('\n')[0].strip().strip('"').strip("'")
with open('/home/ubuntu/.hermes/config.yaml') as f:
    config = yaml.safe_load(f)
config['auxiliary']['vision']['api_key'] = key
config['tools']['vision']['api_key'] = key
with open('/home/ubuntu/.hermes/config.yaml', 'w') as f:
    yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
print(f'Done. Key set: {key[:10]}...')
EOF
```

## ⚠️ 常见问题排查

### 401 Unauthorized / Invalid API Key
1. **检查 base URL**：脚本默认值可能过时。正确 URL 是 `https://token-plan-sgp.xiaomimimo.com/v1`，不是 `https://api.xiaomimimo.com/v1`。
2. **检查 header 格式**：MiMo API 使用 `Authorization: Bearer <key>`，而非 `api-key` header。
3. **验证方式**：
   ```bash
   curl -s https://token-plan-sgp.xiaomimimo.com/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $XIAOMI_API_KEY" \
     -d '{"model":"mimo-v2.5-tts","messages":[{"role":"assistant","content":"你好"}],"audio":{"format":"wav","voice":"冰糖"}}'
   ```

### 404: No endpoints found that support image input
MiMo chat API 不支持图片输入。用户发图片时 Hermes 尝试直接塞进请求导致。
**修复**：`hermes config set agent.image_input_mode tool`，并确保 vision API key 已配置（见上方"图片输入配置"章节）。

### 脚本报 "No API key found"
确认环境变量已 export：`echo $XIAOMI_API_KEY`。如果为空，添加到 `~/.bashrc` 并 `source ~/.bashrc`。

**注意**：Hermes 的 config.yaml 中可能已配置了 API key（`auxiliary.vision.api_key` 或 provider 的 `api_key`），但这个 key 不会自动 export 到 shell 环境变量。脚本依赖 `XIAOMI_API_KEY` 环境变量，二者是独立的。

**快速恢复方法**：从 config.yaml 提取 key 并 export：
```bash
export XIAOMI_API_KEY=$(python3 -c "import yaml; c=yaml.safe_load(open('/home/ubuntu/.hermes/config.yaml')); print(c.get('auxiliary',{}).get('vision',{}).get('api_key',''))")
```

### 网络搜索 400 Bad Request
`mimo_search.py` 可能因 API 端点变更或参数格式问题返回 400。排查步骤：
1. 先用 curl 直接测试 API 是否可达：`curl -s -o /dev/null -w "%{http_code}" https://token-plan-sgp.xiaomimimo.com/v1/models -H "Authorization: Bearer $XIAOMI_API_KEY"`
2. 如果网络不通（`Network is unreachable`），是服务器出站网络问题，不是 API 问题
3. 如果网络通但 400，检查请求体格式是否与最新 API 兼容

### mmx search 不可用
`mmx search query` 需要 MiniMax Token Plan 支持 `coding-plan-search` 模型。如果报错 "your current token plan not support model, coding-plan-search"，说明当前 plan 不包含搜索能力。替代方案：
- 使用 MiMo 网络搜索（如果可用）
- 使用 Playwright 浏览器抓取
- 使用 `curl` 直接请求搜索引擎（注意服务器出站网络限制）

## References

- `references/sensenova-api.md` — SenseNova API 配置、模型列表、限流策略、已安装 skills 绑定情况
- `references/mimo-v2.5-tts-official-doc.md` — MiMo-V2.5-TTS Series 官方文档摘要（VoiceDesign/VoiceClone/导演剧本详解）

## 脚本位置

所有 MiMo 辅助脚本位于 ~/.hermes/scripts/：
- mimo_vision.py - 图像理解
- mimo_audio.py - 音频理解
- mimo_video.py - 视频理解
- mimo_tts.py - TTS 语音合成
- mimo_search.py - 网络搜索