---
name: minimax-cli-wechat-media-workflow
description: MiniMax CLI 媒体生成与 WeChat 发送的完整工作流，包括图片分析、TTS、retry 模式
triggers:
  - "生成语音"
  - "发送图片到微信"
  - "MiniMax 音色"
  - "分析图片"
---

# MiniMax CLI + WeChat 媒体发送工作流

## 核心工具对比

| 工具 | 用途 | 音色数 | WeChat兼容 |
|------|------|--------|------------|
| `text_to_speech` | Edge TTS | 200+ | ❌ 语音泡有时不支持 |
| `mmx speech synthesize` | MiniMax TTS | 300+ | ✅ MP3直接发送 |
| `mmx vision` | 图片分析 | — | ✅ |
| `mmx image generate` | 图片生成 | — | ✅ |
| `mmx music generate` | 音乐生成 | — | ✅ |

## WeChat 发送媒体文件的 Retry 模式

WeChat CDN 上传经常返回 HTTP 500，第一次几乎必定失败。需要等待后重试。

```python
import time, subprocess

def send_wechat_media(file_path, chat_id="o9cq801Q4BDVa20m46H0KTKRUOjo@im.wechat", max_attempts=3):
    for attempt in range(max_attempts):
        result = subprocess.run([
            "python3", "-c",
            f"""
from tools.send_message_tool import send_message_tool
args = {{
    'action': 'send',
    'message': 'MEDIA:{file_path}',
    'target': 'weixin:{chat_id}'
}}
print(send_message_tool(args))
"""
        ], capture_output=True, text=True, cwd="/root/.hermes/hermes-agent")
        output = result.stdout + result.stderr
        if "success" in output and "HTTP 500" not in output:
            return output
        wait_time = 10 * (attempt + 1)
        print(f"Attempt {attempt+1} failed, retrying in {wait_time}s...")
        time.sleep(wait_time)
    return output
```

**经验规则：**
- 语音/MP3：等待 8-15 秒后重试
- 图片：等待 10-20 秒后重试
- 大文件（>5MB）：等待 15-30 秒后重试

## 图片分析的正确方法

`vision_analyze` 无法识别 URL 或本地路径图片。正确流程：

```bash
# 1. 先下载到本地
curl -s -o /root/.hermes/workspace/tmp.jpg "https://example.com/image.jpg"

# 2. 使用 mmx vision 分析
mmx vision /root/.hermes/workspace/tmp.jpg
```

**不要用：** `vision_analyze(image_url="https://...")` ❌
**要用：** `mmx vision /local/path.jpg` ✅

## MiniMax 音色选择

推荐中文音色：
- **甜美姐姐音**: `Chinese (Mandarin)_Sweet_Lady`
- **可爱女孩**: `lovely_girl`
- **柔和少女**: `Chinese (Mandarin)_Soft_Girl`
- **少女音**: `female-shaonv`

台湾腔调暂无专属音色。

## 快速命令参考

```bash
# 文字转语音（MiniMax音色）
mmx speech synthesize --text "文本内容" --voice "lovely_girl" --out output.mp3

# 查看所有音色
mmx speech voices | python3 -c "import sys,json; [print(v) for v in json.load(sys.stdin)]"

# 图片生成
mmx image generate --prompt "描述" --aspect-ratio 16:9 --out image.png

# 音乐生成（完整参数示例 - 古风诗词）
mmx music generate \
  --prompt "古风中国音乐，古典诗词吟诵风格，悲壮豪迈，古筝，琵琶，二胡，笛子，箫，编钟，大鼓，弦乐，交响乐团，慢板，深沉，英雄气概" \
  --lyrics "[Verse]
大江东去，浪淘尽，千古风流人物
..." \
  --vocals "深沉男声，古典诗词吟诵，豪迈悲壮" \
  --genre "古风，中国传统音乐，民族交响" \
  --mood "悲壮，豪迈，苍凉，壮阔" \
  --instruments "古筝，琵琶，二胡，笛子，箫，编钟，大鼓，弦乐" \
  --tempo "慢板" \
  --model "music-2.6" \
  --out "output.mp3"

# 查看配额
mmx quota

# 图片分析（本地文件）
mmx vision /path/to/image.jpg
```

## 图片分析的降级策略

`vision_analyze` 对本地 JPEG 文件（即使文件格式正确、尺寸正常）存在识别盲区。当 `vision_analyze` 失败时，按以下顺序降级：

1. **首选**：`mmx vision /local/path.jpg` — 直接分析本地文件，效果最佳
2. **备选**：通过 nginx/Python 临时 HTTP 服务暴露本地文件，再用 `browser_navigate` + `browser_vision`
3. **最后手段**：`tesseract` OCR（需安装语言包，且仅限文字识别）

典型失败表现：`vision_analyze` 返回"抱歉，我无法看到或访问您提到的图片"，但 `mmx vision` 能正常返回分析结果。

## 自定义音色克隆

MiniMax 支持通过 Web 平台克隆自定义人声音色：

**路径：https://minimax.chat/** → 音色克隆功能

1. 上传 10-60 秒清晰人声（无背景音乐/噪声）
2. 等待训练生成专属 `voice_id`
3. 调用时指定该音色：
   ```bash
   mmx speech synthesize --text "文本" --voice "your_custom_voice_id" --out output.mp3
   ```

**无 GPU 环境下的替代方案：**

- **GPT-SoVITS**（本地克隆）：需 NVIDIA GPU，无 GPU 时无法运行
- **云端 GPT-SoVITS**：可通过 Modal / Lambda Labs / 腾讯云 GPU 实例部署
- **MiniMax Web**（推荐）：无需任何配置，纯浏览器操作

当前服务器无 GPU，建议优先使用 MiniMax Web 音色克隆。

## 文件路径参考

- 工作目录: `/root/.hermes/workspace/`
- 音频缓存: `/root/.hermes/audio_cache/`
- WeChat Chat ID: `o9cq801Q4BDVa20m46H0KTKRUOjo@im.wechat`