# MiniMax TTS → 飞书语音气泡 完整方案

## 踩过的坑（必看）

1. **MiniMax TTS API 参数必须完整**，不能只传 text 和 model
   - ❌ 错误：`{"model": "speech-2.8-hd", "text": "你好"}`
   - ✅ 正确：必须包含 voice_setting 和 audio_setting

2. MiniMax 返回的是 hex 编码的音频，需要 xxd 转换

3. 飞书语音气泡只支持 **OPUS 格式**，不是 MP3，需要 ffmpeg 转换

4. 飞书上传文件必须传 **duration 参数**（毫秒），否则显示 0 秒

5. 飞书上传用 `file_type=opus`，不是 mp3

---

## 完整流程

### Step 1: 调用 MiniMax TTS

```bash
curl -s -X POST "https://api.minimaxi.com/v1/t2a_v2" \
  -H "Authorization: Bearer {MINIMAX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "speech-2.8-hd",
    "text": "要转换的文本",
    "stream": false,
    "voice_setting": {
      "voice_id": "female-tianmei",
      "speed": 1,
      "vol": 1,
      "pitch": 0,
      "emotion": "happy"
    },
    "audio_setting": {
      "sample_rate": 32000,
      "bitrate": 128000,
      "format": "mp3",
      "channel": 1
    }
  }'
```

返回: `{"data": {"audio": "hex..."}, "extra_info": {"audio_length": 3222}}`

### Step 2: 转换格式

```bash
# hex → MP3
echo $HEX_AUDIO | xxd -r -p > voice.mp3

# MP3 → OPUS
ffmpeg -i voice.mp3 -acodec libopus -ac 1 -ar 16000 voice.opus -y

# 获取时长（毫秒）
ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 voice.opus
```

### Step 3: 获取飞书 Access Token

```bash
curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d '{"app_id":"{APP_ID}","app_secret":"{APP_SECRET}"}'
```

### Step 4: 上传文件到飞书

```bash
curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \
  -H "Authorization: Bearer {TOKEN}" \
  -F "file_type=opus" \
  -F "file_name=voice.opus" \
  -F "duration={DURATION_MS}" \
  -F "file=@voice.opus"
```

返回: `{"code": 0, "data": {"file_key": "file_v3_xxx"}}`

### Step 5: 发送语音消息

```bash
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "receive_id": "ou_ac5d6d23827df6ae9d63805be47b05eb",
    "msg_type": "audio",
    "content": "{\"file_key\":\"{FILE_KEY}\"}"
  }'
```

---

## 女声 voice_id 推荐

- `female-tianmei` — 推荐女声

---

## 环境要求

- `ffmpeg`（需要 libopus 支持）
- `xxd`（hex 解码）
- `ffprobe`（获取音频时长）