VitePress

Appearance

MiniMax 客户接入文档 ​

本文档面向 API 调用方，说明如何使用本站提供的 MiniMax 对外接口完成视频任务创建、查询与文件获取。

  • English version: ./MINIMAX-API-EN.md

基础信息 ​

  • Base URL（海外）：https://api.agentpivot.ai
  • 接口前缀：/v1
  • 鉴权方式（任选其一）：
    • x-api-key: <your-api-key>
    • Authorization: Bearer <your-jwt>
  • Content-Type: application/json

说明：本站对外保持 MiniMax 风格接口；网关会自动处理不同上游线路的适配与鉴权，调用方无需感知。

接口总览 ​

方法路径说明
POST/v1/video_generation创建视频生成任务
GET/v1/query/video_generation?task_id={task_id}查询任务状态与结果
GET/v1/files/retrieve?file_id={file_id}获取文件信息（下载地址等）
GET/v1/files/retrieve_content?file_id={file_id}直接下载二进制文件

模型与能力支持（当前版本） ​

模型文生视频图生视频首尾帧视频
MiniMax-Hailuo-2.3支持支持不支持
MiniMax-Hailuo-2.3-Fast暂不支持支持不支持
MiniMax-Hailuo-02支持支持支持

规则说明 ​

  • 当请求体包含 first_frame_image 时，按图生视频处理。
  • 当同时包含 first_frame_image + last_frame_image 时，按首尾帧视频处理。
  • 首尾帧视频当前仅支持 MiniMax-Hailuo-02。

1) 创建任务 ​

请求 ​

POST /v1/video_generation

请求体字段（常用） ​

字段类型必填说明
modelstring是模型名称，例如 MiniMax-Hailuo-2.3
promptstring建议视频描述词
durationnumber否视频时长（秒），常见 6 / 10
resolutionstring否分辨率，例如 768p / 1080p
first_frame_imagestring(URL)图生必填图生视频首帧图片地址
last_frame_imagestring(URL)首尾帧可填与 first_frame_image 同时存在时触发首尾帧模式（仅 MiniMax-Hailuo-02）
prompt_optimizerboolean否是否启用提示词优化
fast_pretreatmentboolean否是否启用快速预处理
aigc_watermarkboolean否是否添加 AIGC 水印
callback_urlstring(URL)否上游回调地址（如线路支持）
negative_promptstring否反向提示词

建议不要传 provider、upstream_provider 等内部调试字段。

请求示例（文生） ​

bash
curl -X POST "https://api.agentpivot.ai/v1/video_generation" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "model": "MiniMax-Hailuo-2.3",
    "prompt": "A cat runs toward the camera and smiles.",
    "duration": 6,
    "resolution": "768p",
    "prompt_optimizer": true,
    "fast_pretreatment": false,
    "aigc_watermark": false
  }'

请求示例（图生） ​

bash
curl -X POST "https://api.agentpivot.ai/v1/video_generation" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "model": "MiniMax-Hailuo-2.3-Fast",
    "prompt": "女孩轻轻转身并向前走，镜头稳定推进，画面过渡自然。",
    "duration": 6,
    "resolution": "768p",
    "first_frame_image": "https://example.com/head.png",
    "prompt_optimizer": true,
    "fast_pretreatment": false,
    "aigc_watermark": false
  }'

请求示例（首尾帧） ​

bash
curl -X POST "https://api.agentpivot.ai/v1/video_generation" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{
    "model": "MiniMax-Hailuo-02",
    "prompt": "镜头从首帧平滑过渡到尾帧，整体运动自然且连贯。",
    "duration": 6,
    "resolution": "768p",
    "first_frame_image": "https://example.com/head.png",
    "last_frame_image": "https://example.com/tail.png",
    "prompt_optimizer": true,
    "fast_pretreatment": false,
    "aigc_watermark": false
  }'

示例响应 ​

json
{
  "task_id": "176844028768320",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

不同线路返回字段可能有差异，建议按如下优先级提取任务 ID：
task_id -> taskId -> id -> task.id -> data.task_id -> result.task_id。

2) 查询任务 ​

请求 ​

GET /v1/query/video_generation?task_id={task_id}

请求示例 ​

bash
curl -X GET "https://api.agentpivot.ai/v1/query/video_generation?task_id=<task_id>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>"

示例响应 ​

json
{
  "task_id": "176844028768320",
  "status": "Success",
  "file_id": "mda-xxxx",
  "video_width": 720,
  "video_height": 1280,
  "download_url": "https://example.com/output.mp4",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

状态定义 ​

状态说明
Running / running处理中
Success / succeeded任务成功，可获取成片
Fail / failed任务失败

结果提取建议 ​

  • status 建议优先读取：status -> task.status -> data.status
  • file_id 建议优先读取：file_id -> fileId -> task.file_id -> data.file_id
  • download_url 建议优先读取：download_url -> url -> data.download_url

3) 文件信息与下载 ​

3.1 获取文件信息 ​

GET /v1/files/retrieve?file_id={file_id}

bash
curl -X GET "https://api.agentpivot.ai/v1/files/retrieve?file_id=<file_id>" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>"

示例返回：

json
{
  "file_id": "mda-xxxx",
  "download_url": "https://example.com/output.mp4",
  "url": "https://example.com/output.mp4"
}

3.2 下载二进制文件 ​

GET /v1/files/retrieve_content?file_id={file_id}

bash
curl -L "https://api.agentpivot.ai/v1/files/retrieve_content?file_id=<file_id>" \
  -H "x-api-key: <your-api-key>" \
  -o minimax-output.mp4

错误码与常见错误 ​

HTTP含义常见原因
200成功请求执行成功
400请求错误参数缺失、模型/能力不支持、task_id/file_id 非法等
401未授权缺失或错误的鉴权信息
403禁止访问账号或权限限制
429请求过快触发限流
5xx服务异常网关或上游暂时不可用

常见业务报错示例：

  • model is unsupported in this gateway release: ...
  • first_frame_image is required for ... image_to_video
  • baidu first_last_frame only supports MiniMax-Hailuo-02 (H20)
  • task_id is required
  • file_id is required

推荐接入流程 ​

  1. 调用创建接口，获取 task_id。
  2. 每 3~5 秒轮询查询接口。
  3. 状态为成功后读取 file_id 与 download_url。
  4. 调用文件下载接口获取二进制成片。
  5. 若状态失败，记录 base_resp.status_msg 并重试或更换参数。

附：联调脚本（可选） ​

仓库 packages/api/scripts 下可直接使用：

  • test-minimax-create-task.sh：通用创建
  • test-minimax-get-task.sh：查询 / 轮询
  • test-minimax-retrieve-file.sh：获取文件信息与下载
  • test-minimax-baidu-v2-h20-create-task.sh：MiniMax-Hailuo-02 创建
  • test-minimax-baidu-v2-h23f-create-task.sh：MiniMax-Hailuo-2.3-Fast 创建
  • test-minimax-baidu-v2-h23-image2video-create-task.sh：MiniMax-Hailuo-2.3 图生
  • test-minimax-baidu-v2-h20-image2video-create-task.sh：MiniMax-Hailuo-02 图生
  • test-minimax-baidu-v2-first-last-create-task.sh：首尾帧（H20）