用 MiniMax 为 Hermes Agent 接入图片与视频生成

这篇记录如何把 MiniMax 的图片和视频生成能力接入 Hermes，并在一个 pip 包中提供图片与视频两个后端。实现覆盖文生图、图生图、文生视频、图生视频和人物参考视频。

文中的返回时间、文件大小和分辨率来自当时的端到端测试记录。API 行为和模型限制会变化，实际接入时仍应以当前官方文档和接口返回为准。

为什么选 MiniMax#

Hermes Agent 内置的 image_generate 工具原本只支持少数几个海外后端（FAL、xAI、OpenAI、Krea、Replicate）。这次接入 MiniMax，主要为了补齐两个能力：

• image-01：单 API 同时支持文生图和图生图（subject_reference 单参考图），可以复用同一套 Hermes 图片后端接口
• Hailuo 系列视频模型：采用异步任务模式，覆盖文生视频、图生视频、首尾帧和人物参考等路径。本文实际跑通的是 Hailuo-2.3 的 6 秒 768P 文生视频

而且 MiniMax 有两个 endpoint：

插件会自动选：CN 优先（你用的是国内账户就走国内），global 作为兜底。

实现一个插件要做什么#

Hermes 的 ImageGenProvider 和 VideoGenProvider 已经封装环境变量加载、URL 缓存和错误格式化。这个插件主要补两个 provider 的请求与响应逻辑：

~/.hermes/plugins/image_gen/minimax/
├── __init__.py        # 业务逻辑
└── plugin.yaml        # 插件元数据

~/.hermes/plugins/video_gen/minimax/
├── __init__.py
└── plugin.yaml

plugin.yaml 极简：

name: minimax
version: 1.0.0
description: 'MiniMax image generation backend. ...'
author: NousResearch
kind: backend

image-01 后端实现要点#

主要工作是组装 HTTP 请求。文档里几个非显然的点：

1. 路径用 aspect_ratio 而不是 size（和 OpenAI、StepFun 不一样）：

   {
   	"model": "image-01",
   	"prompt": "a tiny red apple on a white plate, studio lighting",
   	"aspect_ratio": "1:1", // 不是 "1024x1024"
   	"response_format": "url", // 还可以是 "base64"
   	"n": 1,
   	"prompt_optimizer": true
   }

   json

2. 图生图用 subject_reference 包裹图片 URL：

   "subject_reference": [
     { "type": "character", "image_file": "https://..." }
   ]

   json

3. 返回结构是嵌套的：

   {
   	"data": { "image_urls": ["https://..."] },
   	"metadata": { "success_count": "1" },
   	"base_resp": { "status_code": 0, "status_msg": "success" }
   }

   json

把请求组装好、调用 _call_api、拿到 URL 后用 Hermes 自带的 save_url_image 落盘到 ~/.hermes/cache/images/，整个 generate 流程就完了。

Hailuo 视频后端实现要点#

视频生成和图片最大的区别是异步：

1. POST  /v1/video_generation          → task_id
2. GET   /v1/query/video_generation    (10s 轮询)  → file_id
3. GET   /v1/files/retrieve?file_id=…  → download_url
4. GET   <download_url>                → 字节流 → 本地缓存

超时策略：单次任务最长 5 分钟，10 秒轮询一次。Hailuo-2.3 6s 768P 实测 30-90 秒返回，10s 1080P 偶尔会 3-4 分钟。模型选择上要注意：

一个 API 参数兼容问题：官方文档示例里写的是 720P，但实际 API 不接受。提交 720P 会立刻报错 does not support resolution 720P, supported resolutions: 768P, 1080P。我的插件把 720P 自动 coerce 成 768P，调用方可以无感。

端到端测试效果#

image-01 文生图（1:1 方形）#

“

a tiny red apple on a white plate, studio lighting, photorealistic

单图 5 秒左右返回，~150KB。

image-01 文生图（16:9 横向）#

“

a cute cat astronaut floating in a colorful nebula, digital art, vibrant

“

futuristic tokyo cityscape at night, neon lights, rain reflections, cyberpunk

Hailuo-2.3 文生视频（6s @ 768P）#

“

a calico cat napping in a sunbeam, soft cinematic lighting, gentle breathing motion

“

视频演示 GIF 已从上游仓库移除；保留下方 MP4 原片链接作为可验证演示。

MP4 原片 (608KB) ↗

86 秒返回，输出 1366×768 h264 mp4，每帧都有微小变化（呼吸感）。

本地接入步骤#

1. 安装包#

pip install hermes-minimax-media

2. 配 key#

编辑 ~/.hermes/.env：

# CN endpoint（你目前在用的）
MINIMAX_CN_API_KEY=eyJ...

# 国际 endpoint（兜底）
MINIMAX_API_KEY=eyJ...

3. 启用插件#

编辑 ~/.hermes/config.yaml：

plugins:
  enabled:
    - image_gen/minimax
    - video_gen/minimax
    # ... 其他插件

image_gen:
  provider: minimax
  minimax:
    model: image-01

video_gen:
  provider: minimax
  minimax:
    model: MiniMax-Hailuo-2.3 # 或 Hailuo-02 / S2V-01

4. 重启 Hermes#

hermes gateway restart

之后直接对 Hermes 说：

• “画一只戴墨镜的猫” → 走 image-01
• “做一个 6 秒的城市黄昏延时摄影” → 走 Hailuo-2.3
• “让这张海浪照片动起来”（+ 传 image_url） → 走 Hailuo-2.3 I2V
• “让这个角色挥手”（+ 传人物照片） → 走 S2V-01

仓库里有什么#

整个项目都开源在 github.com/lora-sys/hermes-minimax-media ↗：

• src/hermes_minimax_media/plugins/image_gen/minimax/ — image-01 后端
• src/hermes_minimax_media/plugins/video_gen/minimax/ — Hailuo 视频后端
• tests/ — 20 个 pytest 用例（不需要 API key）
• .github/workflows/ci.yml — py3.11/3.12 测试 + ruff lint + tag 时自动发 PyPI
• docs/assets/ — README 用的 3 张示例图 + 1 个 demo.gif

端到端验证记录#

我跑过的真实结果（不靠模拟）：

和之前 StepFun 那篇的关系#

我之前写过一篇 用 StepFun 给 Hermes 接入图片生成，流程上是同构的（本地插件 → PyPI → CI → 博客），但这两个插件互补：

而且两个插件可以同时启用，在 config.yaml 里改 image_gen.provider 就能切换，不需要卸载任何一个。

下一步计划#

• 跑 image-01 的 i2i（subject_reference）真实样例
• 跑 S2V-01 人物参考视频的真实样例
• 适配 Hailuo-02 的 start-end frame 模式（传 first_frame_image + last_frame_image 两个 url）

项目包已发布为 hermes-minimax-media ↗。仓库保留安装方式、当前支持范围和后续适配项。