# minimax-omni

[![PyPI version](https://img.shields.io/pypi/v/minimax-omni.svg)](https://pypi.org/project/minimax-omni/)

English | [简体中文](README-CN.md)

`minimax-omni` is a comprehensive Python package that provides both a powerful Command Line Interface (CLI) and a Model Context Protocol (MCP) server for interacting with MiniMax's diverse multimodal generation models.

## Features

- **Text-to-Speech (TTS):** Generate high-quality speech with various voices, emotions, and speeds.
- **Voice Clone & Design:** Clone existing voices from audio files or design new voices using prompts.
- **Text-to-Image:** Generate high-resolution images from text prompts with customizable aspect ratios.
- **Video Generation (Hailuo):** Create videos from text, and optionally a first frame image.
- **Music Generation:** Create custom music tracks from text prompts and lyrics.
- **MCP Server Support:** Seamlessly integrate with any applications supporting the Model Context Protocol (MCP).

## Installation

Requires Python >= 3.10.

```bash
pip install minimax-omni
```

Or install with CLI dependencies:

```bash
pip install "minimax-omni[cli]"
```

## Configuration

Configuration is resolved in this priority order: **CLI flag > environment variable > `momni config set` file**.

### Option 1 — `momni config set` (recommended for local use)

```bash
momni config set --api-key YOUR_KEY --api-host https://api.minimax.chat
```

Settings are saved to `~/.config/minimax/config.json`. Run `momni config doctor` to verify.

### Option 2 — `.env` file

Copy `.env.example` to `.env` in your working directory and fill in the values:

```bash
MINIMAX_API_KEY=your_key
MINIMAX_API_HOST=https://api.minimax.chat
# MINIMAX_MCP_BASE_PATH=~/Desktop
# MINIMAX_API_RESOURCE_MODE=local
```

### Option 3 — Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `MINIMAX_API_KEY` | ✅ | — | Your MiniMax API key |
| `MINIMAX_API_HOST` | ✅ | — | `https://api.minimax.chat` (China) or `https://api.minimaxi.chat` (Global) |
| `MINIMAX_MCP_BASE_PATH` | — | `~/Desktop` | Output directory when using `local` mode |
| `MINIMAX_API_RESOURCE_MODE` | — | `url` | `url` returns a link; `local` saves to disk |

## CLI Usage

The package provides two CLI commands: `minimax-omni` and `momni` as a shortcut.

### Voice Generation

```bash
# Text-to-Speech
momni tts "Hello world!" --voice-id female-shaonv --model speech-2.6-hd

# List available voices
momni voice list

# Clone a voice
momni voice clone <voice_id> <path_to_audio_file> <text>

# Voice design
momni voice design "An enthusiastic female voice" "This is a preview text"
```

### Image and Video Generation

```bash
# Generate Image
momni image "A futuristic city under a starry night" --aspect-ratio 16:9

# Generate Video
momni video "A camera flying through a futuristic city"

# Check Video Status
momni video-status <task_id>
```

### Music Generation

```bash
momni music "lo-fi chill beats" "Soft wind blowing through the trees..."
```

## MCP Server Usage

You can use the built-in `serve` command to start the MCP server, which exposes these generation endpoints as tools via the standard MCP interface:

```bash
momni serve
```

### Example configuration for an MCP client:
```json
{
  "mcpServers": {
    "minimax-omni": {
      "command": "momni",
      "args": ["serve"],
      "env": {
        "MINIMAX_API_KEY": "your_api_key",
        "MINIMAX_API_HOST": "https://api.minimax.chat"
      }
    }
  }
}
```