hermes-minimax-media 0.2.0

MiniMax (海螺 / minimax) image + video + music generation backends for Hermes Agent. Image: image-01 T2I+I2I. Video: Hailuo-2.3 / Hailuo-02 / S2V-01 T2V+I2V (async). Music: music-2.6 / music-cover / music-cover-free lyrics+prompt -> MP3 (sync). CN endpoint first, global fallback.

Hermes MiniMax Media

MiniMax (海螺 / minimax) image + video + music generation backends for Hermes Agent.

|| Surface | Model | Modes | ||---|---|---| || image_gen/minimax | image-01 | Text-to-Image, Image-to-Image (subject reference) | || video_gen/minimax | MiniMax-Hailuo-2.3 | T2V, I2V, 6/10s @ 768P/1080P | || video_gen/minimax | MiniMax-Hailuo-02 | T2V, I2V with start-end frames | || video_gen/minimax | S2V-01 | Subject-reference T2V (face consistency) | || music_gen/minimax | music-2.6 | Lyrics + prompt -> MP3 (sync); instrumental & cover modes |

CN endpoint (api.minimaxi.com) is used by default when MINIMAX_CN_API_KEY is set; global (api.minimax.io) is the automatic fallback when only MINIMAX_API_KEY is set.

Demo

Image (image-01)

Apple on plate	Cat astronaut	Cyberpunk city
a tiny red apple on a white plate, studio lighting, photorealistic	a cute cat astronaut floating in a colorful nebula, digital art, vibrant	futuristic tokyo cityscape at night, neon lights, rain reflections, cyberpunk

Video (Hailuo-2.3, 6s @ 768P)

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

MP4 source (608KB)

Music (music-2.6)

Both demos are real MiniMax Music API outputs (music-2.6, 256 kbps MP3 @ 44.1 kHz stereo), generated by the plugin's live smoke tests:

Instrumental (2:05)	Vocals (1:41)
Cheerful acoustic guitar, warm strumming, sunny afternoon vibe	Soulful Blues, Slow Tempo, Electric Guitar, Male Vocal, Rainy Night, Melancholy + custom lyrics
▶ Play MP3 (3.8 MB)	▶ Play MP3 (3.9 MB)

Lyrics used for the vocal demo:

[Verse]
Rain on the windowpane, soft and slow
Coffee steam rising, the room aglow
...

[Chorus]
Midnight rain, fallin down on me
Like tears I cannot cry for all to see
Just the rhythm of the rain
And the blues deep in my soul

... (full lyrics in tests/test_music_gen_minimax.py)

Installation

From PyPI

pip install hermes-minimax-media

The package registers two entry points with the hermes_agent.plugins group (minimax-imggen and minimax-vidgen). Hermes auto-discovers them on next gateway start; you still need to enable the plugins in config.yaml (see Configuration below).

From source

git clone https://github.com/lora-sys/hermes-minimax-media.git
cd hermes-minimax-media
pip install -e .

Manual install (no pip)

mkdir -p ~/.hermes/plugins/{image_gen,video_gen,music_gen}
cp -r src/hermes_minimax_media/plugins/image_gen/minimax \
      ~/.hermes/plugins/image_gen/minimax
cp -r src/hermes_minimax_media/plugins/video_gen/minimax \
      ~/.hermes/plugins/video_gen/minimax
cp -r src/hermes_minimax_media/plugins/music_gen/minimax \
      ~/.hermes/plugins/music_gen/minimax

Configuration

1. Set your MiniMax API key

Add to ~/.hermes/.env:

# CN endpoint (api.minimaxi.com) — used by default
MINIMAX_CN_API_KEY=eyJ...

# Optional: global endpoint (api.minimax.io) — fallback
MINIMAX_API_KEY=eyJ...

Get a key at https://api.minimaxi.com/user-center/basic-information/interface-key (or https://www.minimax.io for the global endpoint).

2. Enable the plugins in ~/.hermes/config.yaml

plugins:
  enabled:
    - image_gen/minimax
    - video_gen/minimax
    - music_gen/minimax
    # ... other plugins

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

video_gen:
  provider: minimax
  minimax:
    model: MiniMax-Hailuo-2.3   # or Hailuo-02, S2V-01

music_gen:
  provider: minimax   # when a music_gen provider surface lands in hermes-agent;
                      # currently the plugin registers the music_generate tool directly.
  minimax:
    model: music-2.6   # or music-cover, music-cover-free

3. Restart Hermes

hermes gateway restart

Usage

Once configured, ask Hermes naturally — the model picks the right tool:

Text-to-image:

画一只戴墨镜的猫

Image-to-image (subject reference):

把这张自拍转成吉卜力风格 (pass an image_url)

Text-to-video:

做一个 6 秒的延时摄影：城市黄昏的车流

Image-to-video (animate a still):

让这张海浪照片动起来 (Hailuo-2.3, pass image_url)

Subject-reference video (face-consistent character):

让视频里这个角色挥手 (S2V-01, pass image_url of a face)

Text-to-music (lyrics + style):

写一首蓝调，主题是雨夜 (the agent will fill in lyrics with lyrics_optimizer=true, then call music_generate)

Instrumental music (no vocals):

做一个 60 秒的欢快尤克里里纯音乐 (is_instrumental=true)

Custom lyrics + style:

用我写的歌词 [Verse]\n... 做一首电子流行歌

Models

Image

|| Model | Modes | Aspect ratios | Notes | ||---|---|---|---| || image-01 | T2I, I2I | 16:9, 9:16, 1:1 | Built-in prompt optimizer on; seed supported |

Video

|| Model | Duration | Resolution | T2V | I2V | Subject ref | Start-end frames | ||---|---|---|---|---|---|---| || MiniMax-Hailuo-2.3 | 6 / 10 s | 768P, 1080P | ✅ | ✅ | ❌ | ❌ | || MiniMax-Hailuo-02 | 6 / 10 s | 768P, 1080P | ✅ | ✅ | ❌ | ✅ | || S2V-01 | 6 s | 1080P | ❌ | ❌ | ✅ (face) | ❌ |

Note: 720P is not a valid MiniMax resolution. The plugin auto-coerces 720P -> 768P to avoid API errors. Don't rely on 720P working.

Music

|| Model | Modes | Output | Notes | ||---|---|---|---| || music-2.6 | T2M (lyrics + prompt), instrumental | MP3 / WAV / PCM | Default. Supports lyrics_optimizer=true to auto-write lyrics from prompt. | || music-cover | Cover song (needs cover_feature_id) | MP3 / WAV / PCM | Two-step workflow via the Music Cover Preprocess API. | || music-cover-free | Cover song (free tier) | MP3 / WAV / PCM | Same as music-cover, free quota. |

The music_generate tool runs synchronously (unlike video): one POST to /v1/music_generation, no task polling. Typical latency is 30-90s. Output audio is cached at ~/.hermes/audio_cache/minimax_music-2.6_<ts>.mp3.

Endpoint resolution

Env state	Endpoint used
MINIMAX_CN_API_KEY set	https://api.minimaxi.com (CN, default)
Only MINIMAX_API_KEY set	https://api.minimax.io (global)
MINIMAX_CN_BASE_URL / MINIMAX_BASE_URL set	Override host only; paths are always /v1/...

Troubleshooting

MiniMax image API error 401

Wrong key or the wrong region. Verify the key is valid at the relevant user center (CN: https://api.minimaxi.com ; global: https://www.minimax.io). The plugin auto-picks the right endpoint based on which env var is set, but if both are set, CN wins.

MiniMax submit returned no task_id: ... does not support resolution 720P

720P was a wrong assumption from older docs. The plugin normalizes it to 768P. If you see this error from a hand-rolled request, switch to 768P.

Video generation times out (>5 min)

The plugin polls every 10s for up to 5 minutes. Hailuo-2.3 typically returns in 30-90s for a 6s/768P clip; 10s/1080P can stretch to 3-4 minutes. If you hit the 5-min cap repeatedly, switch to a shorter duration or lower resolution.

MiniMax submit error 429: ... balance not enough

Out of credits. Top up at https://api.minimaxi.com/user-center/payment (or the global user center).

Plugin not loading

Verify the path matches what config.yaml says:

ls ~/.hermes/plugins/image_gen/minimax/
ls ~/.hermes/plugins/video_gen/minimax/

Each directory should contain both __init__.py and plugin.yaml. If you installed via pip install hermes-minimax-media, the entry points minimax-imggen and minimax-vidgen are auto-registered; the image_gen/minimax and video_gen/minimax names still need to be added to plugins.enabled.

Development

# Clone
git clone https://github.com/lora-sys/hermes-minimax-media
cd hermes-minimax-media

# Editable install
pip install -e .

# Run tests (no API key needed)
pytest tests/ -v

# Run live smoke (requires MINIMAX_CN_API_KEY)
MINIMAX_CN_API_KEY=... pytest tests/ -v -m requires_live

# Lint
ruff check src/ tests/

# Build
python -m build

License

MIT