# yooztech_mcp_minimax_t2i —— MiniMax 图片生成 MCP 工具

基于 MCP (Model Context Protocol) 的 MiniMax 图片生成服务，提供文生图（text-to-image）与图生图（image-to-image）两种核心功能。

## 功能概述

- `text_to_image(prompt, ...)`: 根据文本描述生成图片，并在同一次调用内用 API Key 鉴权下载并保存到本地（接口返回的 URL 需 Bearer 鉴权，直接访问会 401，有效期 24 小时）
- `image_to_image(prompt, subject_reference, ...)`: 结合参考图生成图片，并在同一次调用内完成鉴权下载与本地保存

## 在 Cursor 中配置

需要在 MCP Server 配置中设置环境变量 `MINIMAX_API_KEY`：

```json
{
  "mcpServers": {
    "yooztech_mcp_minimax_t2i": {
      "command": "yooztech_mcp_minimax_t2i",
      "args": [],
      "env": {
        "MINIMAX_API_KEY": "your-api-key"
      }
    }
  }
}
```

或使用 `uvx` 方式：

```json
{
  "mcpServers": {
    "yooztech_mcp_minimax_t2i": {
      "command": "uvx",
      "args": ["yooztech_mcp_minimax_t2i"],
      "env": {
        "MINIMAX_API_KEY": "your-api-key"
      }
    }
  }
}
```

## API Key 获取

请访问 [MiniMax 开放平台](https://platform.minimaxi.com/) 注册账号并获取 API Key。

## 工具详解

### 1. text_to_image - 文生图

根据详尽的文本描述（prompt），直接生成与之匹配的图片。

**参数：**
- `prompt` (必填): 图片描述文本，建议详细描述场景、主体、风格等
- `model` (可选): 使用的模型，默认 "image-01"
- `aspect_ratio` (可选): 图片宽高比，默认 "16:9"
  - 可选值：1:1, 16:9, 4:3, 3:2, 2:3, 3:4, 9:16, 21:9（21:9 仅 image-01）
- `output_dir` (可选): 保存目录，默认当前目录
- `filename_prefix` (可选): 本地文件名前缀，默认 `output`，生成文件为 `{prefix}-0.jpeg` 等

**返回：**
- `success`: 生成与下载是否全部成功
- `saved_files`: 已保存的本地文件路径列表
- `download_errors`: 若有下载失败则列出原因
- `images`: 接口返回的图片 URL（需鉴权访问，日常以 `saved_files` 为准）
- `status_code` / `status_msg`: 接口状态
- `model` / `aspect_ratio`: 使用的模型与宽高比

**使用示例：**

```json
{
  "tool": "text_to_image",
  "args": {
    "prompt": "men Dressing in white t shirt, full-body stand front view image :25, outdoor, Venice beach sign, full-body image, Los Angeles, Fashion photography of 90s, documentary, Film grain, photorealistic",
    "aspect_ratio": "16:9"
  }
}
```

### 2. image_to_image - 图生图

此功能允许提供一张或多张包含清晰主体的参考图（支持网络图片链接），并结合 prompt 描述，生成一张保留了主体特征的新图片。

**参数：**
- `prompt` (必填): 图片描述文本，描述希望生成的场景
- `subject_reference` (必填): 参考图列表，每项包含：
  - `type`: 参考图类型，目前仅支持 "character"（角色）
  - `image_file`: 参考图 URL（支持网络图片链接）
- `model` (可选): 使用的模型，默认 "image-01"
- `aspect_ratio` (可选): 图片宽高比，默认 "16:9"
- `output_dir` / `filename_prefix` (可选): 同 `text_to_image`

**返回：**
- `success`: 生成与下载是否全部成功
- `saved_files`: 已保存的本地文件路径列表
- `images`: 生成的图片 URL 列表
- `model` / `aspect_ratio`: 使用的模型与宽高比

**使用示例：**

```json
{
  "tool": "image_to_image",
  "args": {
    "prompt": "女孩在图书馆的窗户前，看向远方",
    "subject_reference": [
      {
        "type": "character",
        "image_file": "https://cdn.hailuoai.com/prod/2025-08-12-17/video_cover/xxx.jpg"
      }
    ]
  }
}
```

## 完整使用流程

1. 在 Cursor 配置中设置 `MINIMAX_API_KEY` 环境变量
2. 调用 `text_to_image` 或 `image_to_image`；成功时在同一次响应中返回 `saved_files`（已带 Bearer 鉴权下载到本地）

MiniMax 返回的图片 URL 需要带 Bearer Token 才能访问；本工具在生成成功后立即用同一 API Key 下载并写入 `output_dir`，无需再分步调用。

## 错误处理

所有工具在失败时会返回包含错误信息的字典，包含以下字段：
- `success`: 是否成功
- `error`: 错误类型
- `message`: 错误详情

## 依赖

- Python >= 3.10
- mcp >= 1.2.0
- httpx >= 0.27.0

## 许可证

MIT (见 LICENSE)
