deer-flow/docs/superpowers/specs/2026-06-08-minimax-generation-providers-design.md

MiniMax 接入生成类 Skill — 设计文档

• 日期：2026-06-08
• 分支：worktree-feat-minimax-generation
• 参考：MiniMax 开放平台 API（https://platform.minimaxi.com/docs/api-reference）

1. 目标

1. 在现有 image-generation、video-generation、podcast-generation 三个 skill 中接入 MiniMax 作为可选 provider（与现有 Gemini / Volcengine 并存）。
2. 用项目自带的 skill-creator skill 新建一个 music-generation skill，对接 MiniMax 音乐生成 API。

2. 背景与现状

三个生成 skill 均位于 skills/public/<name>/，是自包含目录：

• SKILL.md（frontmatter：name、description + 给 agent 的使用说明，运行时路径为 /mnt/skills/public/<name>/...、产物写到 /mnt/user-data/...）
• scripts/generate.py（纯 requests 调用外部 API 的 CLI，argparse）
• 可选 templates/

现状 provider：

Skill	现 provider	端点	凭证
image-generation	Gemini	generativelanguage.googleapis.com/.../gemini-3-pro-image-preview:generateContent	GEMINI_API_KEY
video-generation	Gemini Veo	.../veo-3.1-generate-preview:predictLongRunning（长任务轮询）	GEMINI_API_KEY
podcast-generation	Volcengine TTS	openspeech.bytedance.com/api/v1/tts（逐行多线程，base64 音频拼接）	VOLCENGINE_TTS_APPID + VOLCENGINE_TTS_ACCESS_TOKEN（+ 可选 VOLCENGINE_TTS_CLUSTER）

MiniMax 已作为 LLM chat provider 接入（config.example.yaml + patched_minimax.py），但未用于图像/视频/音频生成。仓库中无 music 生成功能。

沙箱中各 skill 目录隔离、互不 import → MiniMax 代码在每个 skill 内各自内联，不做跨 skill 共享模块（少量重复可接受）。

skill-creator 是仓库内真实公共 skill（skills/public/skill-creator/，含 scripts/init_skill.py 脚手架）。前端 frontend/src/app/mock/api/skills/route.ts 维护着 UI 展示用的 skill 列表（mock）。

3. Provider 选择机制（已和用户确认）

每个被改造的脚本新增 _resolve_provider()，判定顺序：

1. 显式覆盖：若环境变量 <SKILL>_PROVIDER 已设（如 IMAGE_GENERATION_PROVIDER、VIDEO_GENERATION_PROVIDER、PODCAST_GENERATION_PROVIDER，取值 gemini/volcengine/minimax），直接采用，覆盖自动判断。
2. 现有 provider 优先：现 provider 凭证齐全 → 用现有 provider（保持完全向后兼容）。
3. 回退 MiniMax：否则若 MINIMAX_API_KEY 已设 → 用 MiniMax。
4. 都不满足 → 抛出清晰错误，提示两套环境变量该如何配置。

设计含义：默认行为不变（已有用户配了 Gemini/Volcengine 的不受影响）；只配了 MiniMax 的用户自动走 MiniMax；两者都配又想用 MiniMax 的用户用 <SKILL>_PROVIDER 强制。

4. MiniMax 接口对接细节

通用：

• Base URL 默认 https://api.minimaxi.com，可用 MINIMAX_API_HOST 覆盖（备用 https://api-bj.minimaxi.com）。
• Header：Authorization: Bearer $MINIMAX_API_KEY、Content-Type: application/json。
• 统一错误处理：响应体 base_resp.status_code != 0 → 抛带 status_msg 的异常。

4.1 图像 POST /v1/image_generation（同步）

请求体：

{
  "model": "image-01",
  "prompt": "<文本>",
  "aspect_ratio": "16:9",
  "response_format": "base64",
  "n": 1,
  "prompt_optimizer": true
}

• 参考图：转成 Data URL（data:image/jpeg;base64,...），放入 subject_reference: [{"type": "character", "image_file": "<data url>"}]（仅 image-01 支持；用现有 --reference-images 的图片）。
• 响应：data.image_base64[0] → base64.b64decode 写出文件；response_format:url 时取 data.image_urls[0] 下载（实现选 base64，少一次下载）。
• 模型可用 MINIMAX_IMAGE_MODEL 覆盖（默认 image-01）。

4.2 视频（异步三步）

1. POST /v1/video_generation：

   { "model": "MiniMax-Hailuo-2.3", "prompt": "<文本>", "first_frame_image": "<data url，可选>" }
   

   → { "task_id": "...", "base_resp": {...} }
2. 轮询 GET /v1/query/video_generation?task_id=<id> → status ∈ {Preparing,Queueing,Processing,Success,Fail}；Success 时返回 file_id。
3. GET /v1/files/retrieve?file_id=<id> → file.download_url；下载 mp4 写出。

• 参考图：第一张转 Data URL 作 first_frame_image。
• 视频无 aspect_ratio 概念（用 resolution/duration），MiniMax 路径忽略 --aspect-ratio，用默认 resolution。
• 轮询间隔 3s，设最大次数上限（如 120 次≈6 分钟）防止无限循环；Fail/超时报错。
• 模型可用 MINIMAX_VIDEO_MODEL 覆盖（默认 MiniMax-Hailuo-2.3）。

4.3 播客 TTS POST /v1/t2a_v2（同步）

沿用现有"逐行 + ThreadPoolExecutor 多线程 + 拼接"结构，仅替换单行合成函数：

{
  "model": "speech-2.6-hd",
  "text": "<单行文本>",
  "voice_setting": { "voice_id": "<male/female 预设>", "speed": 1.0, "vol": 1.0, "pitch": 0 },
  "audio_setting": { "sample_rate": 32000, "bitrate": 128000, "format": "mp3", "channel": 1 },
  "output_format": "hex"
}

• 响应 data.audio 为 hex 编码 → bytes.fromhex(audio)（区别于 Volcengine 的 base64）。
• 角色映射：male/female → MiniMax voice_id 预设，默认值可用 MINIMAX_TTS_VOICE_MALE / MINIMAX_TTS_VOICE_FEMALE 覆盖。
• 模型可用 MINIMAX_TTS_MODEL 覆盖（默认 speech-2.6-hd）。

4.4 音乐 POST /v1/music_generation（同步，新 skill）

请求体：

{
  "model": "music-2.6-free",
  "prompt": "<风格/情绪/场景>",
  "lyrics": "[verse]\n...\n[chorus]\n...",
  "output_format": "hex",
  "audio_setting": { "sample_rate": 44100, "bitrate": 256000, "format": "mp3" }
}

• 响应 data.audio 为 hex → bytes.fromhex 写 mp3。
• 歌词规则：
  • 提供 lyrics：直接用（含 [Verse]/[Chorus] 等结构标签，\n 分行）。
  • 未提供且 is_instrumental 为真：is_instrumental:true（不需要 lyrics）。
  • 未提供且非纯音乐：lyrics_optimizer:true（系统据 prompt 自动写词）。
• 仅用 MINIMAX_API_KEY（音乐只有 MiniMax 提供，无 provider 判断）；模型可用 MINIMAX_MUSIC_MODEL 覆盖（默认 music-2.6-free，付费用户可设 music-2.6）。

5. 各组件改动清单

5.1 skills/public/image-generation/scripts/generate.py

• 抽出现有 Gemini 逻辑为 _generate_image_gemini(...)。
• 新增 _generate_image_minimax(...)、_resolve_provider("image_generation", ...)、_to_data_url(path)。
• generate_image(...) 顶层按 provider 路由；保留 CLI 与签名不变。
• SKILL.md：在说明里补充 MiniMax provider 与所需环境变量（不改变调用方式）。

5.2 skills/public/video-generation/scripts/generate.py

• 同上模式：_generate_video_gemini、_generate_video_minimax（三步轮询）、_resolve_provider("video_generation", ...)。
• SKILL.md 补充 MiniMax provider 说明。

5.3 skills/public/podcast-generation/scripts/generate.py

• text_to_speech_volcengine（现有改名）+ text_to_speech_minimax；_process_line/tts_node 内按 _resolve_provider("podcast_generation", ...) 选择合成函数与 voice 映射。
• 环境变量校验同时支持两套；SKILL.md 补充说明。

5.4 新增 skills/public/music-generation/（用 skill-creator）

• 用 skill-creator/scripts/init_skill.py 脚手架生成目录骨架，再填充：
  • SKILL.md：frontmatter name: music-generation + description；说明输入 JSON 结构、调用方式、环境变量、示例（按现有生成 skill 的风格与运行时路径 /mnt/skills/public/music-generation/...）。
  • scripts/generate.py：CLI --prompt-file <json> --output-file <mp3>；读 JSON {title, prompt, lyrics?, is_instrumental?}；调 /v1/music_generation；hex→mp3。
• frontend/src/app/mock/api/skills/route.ts：新增 music-generation 条目（按字母序，category:"public"、enabled:true），使其出现在 UI skill 列表。

6. 测试（TDD）

• 框架：pytest。测试目录：仓库根 tests/skills/（不放进会部署到沙箱的 skill 目录）。
• 用 importlib.util.spec_from_file_location 按路径加载各 generate.py。
• requests.post / requests.get 全部用 unittest.mock 打桩，不打真实 API。
• 覆盖点：
  • _resolve_provider：各环境变量组合（仅现有 key / 仅 MiniMax key / 两者 / 都无 / <SKILL>_PROVIDER 覆盖）→ 正确 provider 或正确报错。
  • 请求体构造：image/video/podcast/music 各自 payload 字段、模型默认与 env 覆盖、参考图 Data URL 转换。
  • 响应解析：image base64 解码写文件、music/podcast hex 解码、video 三步流转（mock task_id→Success→download_url→内容写出）。
  • 错误：base_resp.status_code != 0 抛异常；video Fail/超时分支。
• 先写失败测试，再实现到通过。

7. 向后兼容性

• 现有 CLI 参数与默认行为完全不变；仅当现 provider 凭证缺失（或显式 <SKILL>_PROVIDER）时才走 MiniMax。
• 不改 LLM 侧已有的 MiniMax 接入。

8. 新增环境变量汇总

变量	用途	默认
MINIMAX_API_KEY	复用现有 LLM 同名 key	必填（走 MiniMax 时）
MINIMAX_API_HOST	MiniMax base url	https://api.minimaxi.com
IMAGE_GENERATION_PROVIDER / VIDEO_GENERATION_PROVIDER / PODCAST_GENERATION_PROVIDER	强制 provider	不设（自动判断）
MINIMAX_IMAGE_MODEL	图像模型	image-01
MINIMAX_VIDEO_MODEL	视频模型	MiniMax-Hailuo-2.3
MINIMAX_TTS_MODEL	TTS 模型	speech-2.6-hd
MINIMAX_TTS_VOICE_MALE / MINIMAX_TTS_VOICE_FEMALE	播客音色	选定的男/女系统音色
MINIMAX_MUSIC_MODEL	音乐模型	music-2.6-free

9. 非目标（YAGNI）

• 不做翻唱（music-cover / music_cover_preprocess）、独立歌词生成接口（lyrics_generation，音乐内置 lyrics_optimizer 已覆盖"自动写词"）、音色复刻/设计、视频模板 Agent、流式合成。
• 不为各 skill 抽象统一 "GenerationProvider" 框架（沙箱隔离 + YAGNI）。