stock-assistant/notes/minimax-tts-feishu-voice.md

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

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: 转换格式

# 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

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: 上传文件到飞书

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: 发送语音消息

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（获取音频时长）