mm-video-gen

MiniMax API queue manager with persistent job queue and quota window tracking. A host-resident daemon manages jobs; agents enqueue via CLI over a Unix socket.

Quick Start

# Build
make build

# Install binaries + systemd user unit
export MINIMAX_API_KEY='your_key_here'
make install

# Start daemon
mm-video-gen daemon start
systemctl --user enable mm-video-gen

# Queue a video
mm-video-gen queue "A man walks through a forest" ./output/scene.mp4

# Queue with image-to-video (first frame)
mm-video-gen queue --image ./frame.png "A man walks" ./output/scene.mp4
mm-video-gen queue --image https://example.com/frame.jpg "A man walks" ./output/scene.mp4

# Check status
mm-video-gen status <job_id>

# View dashboard
mm-video-gen dashboard

# List all jobs
mm-video-gen list [pending|completed|failed|all]

# Wait for completion
mm-video-gen wait <job_id>

# Defer a failed job to retry after quota window
mm-video-gen defer-failed <job_id>

Architecture

• Daemon (mm-video-gend): Runs on host, manages SQLite queue, polls MiniMax API, downloads/saves outputs, tracks quota per model per UTC day (01:05 Sydney time). Enforces quota cap of 2 successful submissions per window; jobs over quota go to waiting_for_quota and retry after window boundary. Output path converted to absolute in CLI; symlink points to caller's file.
• CLI (mm-video-gen): Thin JSON-over-Unix-socket client; responses streamed up to 32 MiB per line.
• Storage: ~/.local/share/mm-video-gen/
  • mm-video-gen.sock — Unix socket (newline-delimited JSON)
  • mm-video-gen.db — SQLite job queue
  • videos/ — Downloaded video files
  • api-log/ — MiniMax request/response logs

CLI Commands

mm-video-gen queue [--image path_or_URL] "prompt" ./output.mp4 [--model MODEL]
  Create a video generation job. Default model: MiniMax-Hailuo-2.3-Fast.
  Image formats: PNG, JPG, WebP (max 20 MiB).

mm-video-gen dashboard
  Show queue status (pending/waiting for quota) and quota usage per model.

mm-video-gen status <job_id>
  Show job details: status, model, output path, error message.

mm-video-gen list [pending|completed|failed|all]
  List jobs. "pending" includes waiting_for_quota jobs.

mm-video-gen wait <job_id>
  Block until job completes or fails.

mm-video-gen cancel <job_id>
  Cancel a pending job.

mm-video-gen defer-failed <job_id>
  Move a failed job to waiting_for_quota for retry after quota window.

mm-video-gen daemon start|stop|restart|status
  Manage systemd user unit (mm-video-gen.service).

mm-video-gen logs
  Tail daemon logs via journalctl.

Video Models

Model	Duration	Resolution	Speed
MiniMax-Hailuo-2.3-Fast	6s	768P	Fast (default)
MiniMax-Hailuo-2.3	6s or 10s	768P or 1080P	Standard
MiniMax-Hailuo-02	6s or 10s	768P or 1080P	High quality

Image-to-Video (--image)

• CLI loads local path or HTTPS URL, decodes and normalizes to lossy WebP (quality 80)
• Daemon stores WebP in SQLite; worker sends data:image/webp;base64,... to MiniMax
• On format rejection (status 2013), retries once with PNG fallback
• HTTP(S) downloads capped at 20 MiB before decode
• Works with all video models

Environment Variables

Variable	Default	Description
MINIMAX_API_KEY	required	MiniMax API key
MM_VIDEO_GEN_SOCKET	~/.local/share/mm-video-gen/mm-video-gen.sock	Unix socket path
MM_VIDEO_GEN_QUOTA_TZ	Australia/Sydney	IANA zone for daily quota window (01:05 UTC in that zone); resets globally at same instant

Quota Management

• Per-model cap: 2 successful submissions per UTC day (window boundary at 01:05 in MM_VIDEO_GEN_QUOTA_TZ)
• Waiting jobs: Jobs exceeding quota or hitting provider quota errors move to waiting_for_quota
• Retry: Automatic retry after next quota window; use defer-failed to move failed jobs into the retry queue

Docker Integration

# Host networking (socket auto-discoverable)
docker run --network=host -e MINIMAX_API_KEY your-image \
  mm-video-gen queue "A man walks" ./out/v.mp4

# With image-to-video (mount image file)
docker run --network=host -e MINIMAX_API_KEY -v /path/frame.png:/frame.png:ro your-image \
  mm-video-gen queue --image /frame.png "prompt" ./out/v.mp4

# Socket volume mount
docker run -v $HOME/.local/share/mm-video-gen:/sock \
  -e MM_VIDEO_GEN_SOCKET=/sock/mm-video-gen.sock \
  your-image mm-video-gen queue "A man walks" ./out/v.mp4

API Logging

MiniMax calls logged to ~/.local/share/mm-video-gen/api-log/:

• create/ — POST /v1/video_generation (image data redacted to placeholder)
• query/ — GET /v1/query/video_generation (polling)
• download/ — GET /v1/files/retrieve

Job Status Flow

pending → queueing → processing → completed
       ↓
    failed → (defer-failed) → waiting_for_quota
       
waiting_for_quota → (after quota window) → pending

• pending: Ready to submit to MiniMax
• queueing: Submitted, awaiting task acceptance
• processing: Task accepted, MiniMax generating
• completed: Video downloaded and symlink created
• failed: API error or network failure
• waiting_for_quota: Deferred due to quota cap; retries after window

Deferred

• Callback URL push (MiniMax supports; requires internet-reachable daemon)
• Quota reporting from api-log/
• Webhook notifications on completion