# MiniMax API 速查 (图生视频 / 图生图 / 文生图 / 文生文)

> 通用基础 URL: `https://api.minimaxi.com`,Bearer Auth,JSON request/response。
>
> 文档主页: https://platform.minimaxi.com/docs/guides/models-intro
>
> 完整 API 索引(可通过 llms.txt 抓): https://platform.minimaxi.com/docs/llms.txt

---

## 🔐 鉴权

```bash
export MINIMAX_API_KEY="sk-cp-..."
curl -sS https://api.minimaxi.com/v1/models \
  -H "Authorization: Bearer $MINIMAX_API_KEY"
# → 列出 5 个 LLM 模型 + 视频/语音/图像/音乐模型
```

支持的 LLM 模型 (`/v1/models` 实际返回):
- `MiniMax-M2.5`
- `MiniMax-M2.5-highspeed`
- `MiniMax-M2.7`
- `MiniMax-M2.7-highspeed`
- `MiniMax-M3`(原生多模态,1M context,支持 Coding Plan)

---

## 💬 文生文(LLM / Responses API)

**OpenAI 兼容** `/v1/responses` 与 Anthropic 兼容 `/anthropic/v1/messages` 都支持。

```bash
# OpenAI Responses 风格
curl -X POST https://api.minimaxi.com/v1/responses \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-M3",
    "input": [{"role":"user","content":"hi"}],
    "max_output_tokens": 200
  }'

# Anthropic SDK 风格
export ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
export ANTHROPIC_API_KEY=$MINIMAX_API_KEY
```

文本模型同时支持 **Coding Plan** (`/v1/coding_plan/remains`):

```bash
curl https://api.minimaxi.com/v1/coding_plan/remains \
  -H "Authorization: Bearer $MINIMAX_API_KEY"
# → 返回 model_remains: [{model_name: "general"/"video", current_interval_remaining_percent: 0–100, ...}]
```

注意:**`current_interval_usage_count` 字段语义反直觉** —— 实际是"剩余量"(以 `_remaining_percent` 为主)。

---

## 🖼️ 文生图 (`image-01`, `image-01-live`)

**端点**: `POST https://api.minimaxi.com/v1/image_generation`

```bash
curl -X POST https://api.minimaxi.com/v1/image_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image-01",
    "prompt": "A cat sleeping on a stack of books, anime style, soft lighting",
    "prompt_optimizer": true,
    "width": 1024,
    "height": 1024
  }'
# → {"images": [{"url": "https://..."}], "metadata": {...}}
```

| 字段 | 类型 | 必填 | 备注 |
|---|---|---|---|
| `model` | enum | ✅ | `image-01`(标准),`image-01-live`(手绘/卡通等画风) |
| `prompt` | str | ✅ | 描述文本 |
| `prompt_optimizer` | bool | ❌ | 自动 prompt 增强 |
| `width`, `height` | int | ❌ | 像素; 默认 1024×1024; 比例在 2:5~5:2 |

---

## 🖼️→ 🖼️ 图生图 (`image-01`)

**同一端点** `POST /v1/image_generation`,加 `image` 字段:

```bash
curl -X POST https://api.minimaxi.com/v1/image_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image-01",
    "prompt": "把背景改成太空,色调偏冷蓝",
    "image": "https://example.com/your-source.jpg",
    "prompt_optimizer": true
  }'
```

| 字段 | 类型 | 必填 | 备注 |
|---|---|---|---|
| `image` | str / array | ✅ | 公网 URL、Base64 (`data:image/jpeg;base64,...`)、或 [url, base64] |
| 其他 | 同文生图 | | |

---

## 🎬 文生视频 (`Hailuo-2.3` / `Hailuo-02` / `T2V-01-Director` / `T2V-01`)

**端点**: `POST https://api.minimaxi.com/v1/video_generation`(异步)

```bash
curl -X POST https://api.minimaxi.com/v1/video_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "A man picks up a book [Pedestal up], then reads [Static shot]",
    "prompt_optimizer": true
  }'
# → {"task_id": "...", "status": "submitted"}
```

然后轮询:
```bash
curl https://api.minimaxi.com/v1/video_generation/<task_id> \
  -H "Authorization: Bearer $MINIMAX_API_KEY"
# → {"status": "succeed"/"processing"/"failed", "file_id": "..."}
```

**15 种运镜指令**(在 prompt 的 `[...]` 内):
- 移:`[左移]`, `[右移]`
- 摇:`[左摇]`, `[右摇]`
- 推拉:`[推进]`, `[拉远]`
- 升降:`[上升]`, `[下降]`
- 俯仰:`[上摇]`, `[下摇]`
- 变焦:`[变焦推近]`, `[变焦拉远]`
- 其他:`[晃动]`, `[跟随]`, `[固定]`

组合:`[左摇,上升]` 同一组内同时生效。

---

## 🎬 图生视频 (`Hailuo-2.3` / `Hailuo-02` / `I2V-01-Director` / `I2V-01-live` / `I2V-01`)

**同一端点** `POST /v1/video_generation`,但加 `first_frame_image`:

```bash
curl -X POST https://api.minimaxi.com/v1/video_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "The mouse runs toward the camera, smiling and blinking.",
    "first_frame_image": "https://example.com/your-first-frame.jpg",
    "prompt_optimizer": true
  }'
```

`first_frame_image` 接受:
- 公网 URL
- Base64 `data:image/jpeg;base64,...`
- 要求: JPG/JPEG/PNG/WebP,< 20MB,短边 > 300px,长宽比在 2:5~5:2

---

## 🔁 通用 task 轮询模式

视频生成 + 语音异步合成 + 音乐生成 **都是异步**。返回 `task_id`,然后轮询:

```python
import httpx, time
API = "https://api.minimaxi.com"
H = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# 1. 提交
r = httpx.post(f"{API}/v1/video_generation", headers=H, json={...})
task_id = r.json()["task_id"]

# 2. 轮询
while True:
    r = httpx.get(f"{API}/v1/video_generation/{task_id}", headers=H)
    data = r.json()
    if data["status"] == "succeed":
        file_id = data["file_id"]
        break
    elif data["status"] == "failed":
        raise RuntimeError(data)
    time.sleep(10)

# 3. 下载
r = httpx.get(f"{API}/v1/files/{file_id}/content", headers=H)
open("out.mp4", "wb").write(r.content)
```

---

## 📁 文件 API

视频/图片/语音生成结果存在 MiniMax 文件系统中,5 个端点:

| 操作 | 端点 |
|---|---|
| 上传 | `POST /v1/files/upload` |
| 列出 | `POST /v1/files/list` |
| 检索元数据 | `POST /v1/files/retrieve` |
| 下载内容 | `GET /v1/files/{file_id}/content` |
| 删除 | `POST /v1/files/delete` |

---

## 💡 实际项目常用 skill 集成模式

```python
# 1. 文本对话 / Coding
from openai import OpenAI
client = OpenAI(base_url="https://api.minimaxi.com", api_key=API_KEY)
resp = client.responses.create(model="MiniMax-M3", input=[{"role":"user","content":"hi"}])

# 2. 文生图 + 异步下载
import httpx
r = httpx.post("https://api.minimaxi.com/v1/image_generation",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type":"application/json"},
    json={"model":"image-01","prompt":"a cat","width":1024,"height":1024})
img_url = r.json()["images"][0]["url"]
img = httpx.get(img_url)
open("cat.jpg","wb").write(img.content)

# 3. 文生视频 + 轮询
task = httpx.post("https://api.minimaxi.com/v1/video_generation",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type":"application/json"},
    json={"model":"MiniMax-Hailuo-2.3","prompt":"a mouse smiles"})
tid = task.json()["task_id"]
while True:
    status = httpx.get(f"https://api.minimaxi.com/v1/video_generation/{tid}",
                       headers={"Authorization": f"Bearer {API_KEY}"}).json()
    if status["status"] in ("succeed","failed"): break
    time.sleep(10)
mp4 = httpx.get(f"https://api.minimaxi.com/v1/files/{status['file_id']}/content",
                headers={"Authorization": f"Bearer {API_KEY}"})
open("clip.mp4","wb").write(mp4.content)
```

---

## ⚠️ 常见坑

| 坑 | 现象 | 修法 |
|---|---|---|
| `current_interval_usage_count` 字段是反的 | 看着像"已用数" | 用 `current_interval_remaining_percent`(权威) |
| 视频 API 返回 `task_id` 不直接出视频 | 你以为同步失败 | 其实异步, 轮询 `/v1/video_generation/<task_id>` |
| `prompt` > 2000 字被截断 | 视频效果随机 | 控制在 2000 字以内 |
| 图生图 first_frame 比例 5:1 或 1:5 | API 拒 | 2:5 ~ 5:2 之间 |

---

## 📜 文档来源(2026-07-05 抓)

- https://platform.minimaxi.com/docs/guides/models-intro
- https://platform.minimaxi.com/docs/api-reference/image-generation-t2i
- https://platform.minimaxi.com/docs/api-reference/image-generation-i2i
- https://platform.minimaxi.com/docs/api-reference/video-generation-t2v
- https://platform.minimaxi.com/docs/api-reference/video-generation-i2v
- https://platform.minimaxi.com/docs/api-reference/responses-create
- https://platform.minimaxi.com/docs/api-reference/text-anthropic-api