MiniMax-H3 接口文档

接口整体以 MiniMax 官方视频生成 V2 协议为主，请求体、响应体均对齐 MiniMax 官方原生结构，并在响应中追加平台请求 ID aiping_id。当前可用模型为 MiniMax-H3。

1. 接口列表

接口	方法	路径	说明
创建视频生成任务	`POST`	`/api/v1/multimodal/minimax/videos/video_generation`	通过多模态 content 数组输入（文本 / 图片 / 视频 / 音频），支持文生视频、图生视频（首尾帧）、多模态参考生视频，2K 直出。
创建 H3-Context-IR 任务	`POST`	`/api/v1/multimodal/minimax/videos/h3_context_ir`	H3 多模态分析，产出增强 prompt（不生成视频）
创建视频再生成任务	`POST`	`/api/v1/multimodal/minimax/videos/video_regeneration`	视频再生成（768P 超分到 2K）
查询任务	`GET`	`/api/v1/multimodal/minimax/videos/query/video_generation/{task_id}`	按 task_id 查询最近 7 天内单个视频生成、H3-Context-IR 或视频再生成任务的状态与结果。
查询任务列表	`GET`	`/api/v1/multimodal/minimax/videos/query/video_generation`	分页查询最近 7 天内的任务列表，支持按状态、任务 ID、模型和任务类型过滤。
取消或删除任务	`DELETE`	`/api/v1/multimodal/minimax/videos/video_generation/{task_id}`	按任务当前状态取消排队中的任务，或删除成功和失败的视频生成、H3-Context-IR 及视频再生成任务记录。

2. 鉴权与通用约定

请求头

字段	值	必填	说明
`Content-Type`	`application/json`	是	请求体格式
`Authorization`	`Bearer {api_key}`	是	AI Ping 平台 API Key

3. 创建视频任务

创建任务接口均为异步接口。创建成功后返回 task_id，通过任务查询接口获取最终结果。

创建成功响应示例：

json

{
  "task_id": "426000000000001",
  "aiping_id": "request-uuid"
}

当前可用模型为 MiniMax-H3。

3.1 创建视频生成任务

POST /api/v1/multimodal/minimax/videos/video_generation

根据文本提示词（可附首帧 / 尾帧 / 参考图）生成视频。

参数名	类型	必填	说明
`model`	string	是	模型名，当前可用 `MiniMax-H3`。
`content`	array[object]	是	多模态输入内容数组，描述用于生成视频的信息。每个元素通过 `type` 区分类型（`text` / `image_url` / `video_url` / `audio_url`），并可通过 `role` 标注用途。每次请求必须包含一个非空 `text` 项（prompt 必填）；缺失会返回参数错误。支持的输入组合（对应不同生成场景）： - 文生视频：仅一个 `text` 元素。 - 图生视频-首帧：`text` + 1 张 `image_url`（`role=first_frame` 或不填）。 - 图生视频-尾帧：`text` + 1 张 `image_url`（`role=last_frame`）。 - 图生视频-首尾帧：`text` + 2 张 `image_url`（`role` 分别为 `first_frame`、`last_frame`）。 - 多模态参考生视频：`text` + 参考图片（`role=reference_image`）+ 参考视频（`role=reference_video`）+ 参考音频（`role=reference_audio`）的组合。 > 图生视频与多模态参考生视频互斥：content 中出现 `reference_image` / `reference_video` / `reference_audio` 任一 role，就不能再出现 `first_frame` / `last_frame`（反之亦然），二者不可混用。 > >
`resolution`	string	是	分辨率，可选 `768P`、`2K`。
`duration`	int	是	视频时长，整数秒，范围 4-15。
`ratio`	string	否	画面比例，可选 `adaptive`(默认)、`21:9`、`16:9`、`4:3`、`1:1`、`3:4`、`9:16`；纯文生视频须给具体比例，不能用 `adaptive`。
`aigc_watermark`	bool	否	是否添加 AIGC 水印，默认 `false`。
`callback_url`	string	否	任务状态变化时该地址发送 `POST` 回调，回调体与查询任务返回体一致。

文生视频请求示例：

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。"
    }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "16:9"
}

图生视频（首帧图）请求示例：

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "镜头缓慢推近，画面中的主体开始自然运动"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/first_frame.png"
      },
      "role": "first_frame"
    }
  ],
  "resolution": "768P",
  "duration": 6
}

3.2 创建 H3-Context-IR 任务

POST /api/v1/multimodal/minimax/videos/h3_context_ir

对文本 / 图片 / 音视频做多模态深度分析，产出一段增强的结构化 prompt，不生成视频。查询任务成功后，从 task.content.prompt 取增强 prompt。

参数名	类型	必填	说明
`model`	string	是	模型名，当前可用 `MiniMax-H3`。
`content`	array[object]	是	多模态上下文输入数组，用于描述目标视频及各类素材之间的关系。每个元素通过 `type` 区分类型（`text` / `image_url` / `video_url` / `audio_url`），并可通过 `role` 标注用途。每次请求必须包含一个非空 `text` 项（prompt 必填）；缺失会返回参数错误。支持的输入组合（对应不同生成场景）： - 文生视频：仅一个 `text` 元素。 - 图生视频-首帧：`text` + 1 张 `image_url`（`role=first_frame` 或不填）。 - 图生视频-尾帧：`text` + 1 张 `image_url`（`role=last_frame`）。 - 图生视频-首尾帧：`text` + 2 张 `image_url`（`role` 分别为 `first_frame`、`last_frame`）。 - 多模态参考生视频：`text` + 参考图片（`role=reference_image`）+ 参考视频（`role=reference_video`）+ 参考音频（`role=reference_audio`）的组合。 > 图生视频与多模态参考生视频互斥：content 中出现 `reference_image` / `reference_video` / `reference_audio` 任一 role，就不能再出现 `first_frame` / `last_frame`（反之亦然），二者不可混用。 > >
`duration`	int	是	目标视频时长，整数秒，范围 4-15。
`ratio`	string	否	画面比例，取值同文生视频。
`callback_url`	string	否	回调地址，回调体与查询任务返回体一致。

请求示例：

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "史诗级太空歌剧院线预告：女舰长独自站在巨大观景窗前，最后一支舰队正在集结并跃迁离去，强光爆闪、舰桥震动，她被留在原地。"
    }
  ],
  "duration": 5,
  "ratio": "16:9"
}

3.3 创建视频再生成任务

POST /api/v1/multimodal/minimax/videos/video_regeneration

把 MiniMax-H3 生成的 768P 视频超分到 2K。

按任务 ID 再生成

参数名	类型	必填	说明
`model`	string	是	模型名，当前可用 `MiniMax-H3`。
`source_task_id`	string	是	已有 `/video_generation` 成功任务的 `task_id`，以其产物为源再生成。使用限制：源任务须属于当前账号、状态为 `succeeded`，且仍可通过 `/query/video_generation` 查到（创建于 7 天内）。
`resolution`	string	是	只能取 `2K`。
`aigc_watermark`	bool	否	是否添加 AIGC 水印，默认 `false`。
`callback_url`	string	否	回调地址，回调体与查询任务返回体一致。

请求示例：

json

{
  "model": "MiniMax-H3",
  "source_task_id": "424010985731000",
  "resolution": "2K"
}

按原视频再生成

参数名	类型	必填	说明
`model`	string	是	模型名，当前可用 `MiniMax-H3`。
`content`	array[object]	是	视频再生成输入内容数组。请在数组中包含： - 必须原样提交生成 768P 源视频时实际送入模型的全部输入。其中，`text` 必须使用当时实际送入模型的最终 prompt，不可使用 H3-Context-IR 处理前的原始 prompt；所有参考图片、视频和音频也必须与生成时一致。任何输入不一致，都可能无法达到预期的再生成效果 - 一个 768P 源视频项，`type=video_url` 且 `role=base_video`；该项必须且只能有一个
`resolution`	string	是	只能取 `2K`。
`aigc_watermark`	bool	否	是否添加 AIGC 水印，默认 `false`。
`callback_url`	string	否	回调地址，回调体与查询任务返回体一致。

base_video（768P 源视频）规格：带音轨、24fps、边长可被 32 整除、最大面积 768×1344、时长 4-15s。

请求示例：

json

{
  "model": "MiniMax-H3",
  "content": [
    {
      "type": "text",
      "text": "镜头缓慢推近，画面中的主体开始自然运动"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/base-video-768p.mp4"
      },
      "role": "base_video"
    }
  ],
  "resolution": "2K"
}

4. 任务管理

4.1 查询任务

GET /api/v1/multimodal/minimax/videos/query/video_generation/{task_id}

task_id 为创建响应返回的 task_id。三种任务类型都走这个查询端点。仅支持查询近 7 天创建的任务。

文生 / 图生视频成功响应示例：

json

{
  "task": {
    "id": "426000000000001",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1785728639,
    "updated_at": 1785728784,
    "content": {
      "url": "https://example.com/output.mp4"
    },
    "resolution": "768P",
    "duration": 6,
    "ratio": "16:9",
    "task_type": "generation",
    "usage": {
      "total_seconds": 6,
      "input_seconds": 0,
      "output_seconds": 6,
      "input_image_count": 0
    }
  },
  "aiping_id": "request-uuid"
}

H3-Context-IR 成功响应（结果在 content.prompt，无视频）：

json

{
  "task": {
    "id": "426000000000003",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "task_type": "h3_context_ir",
    "modality": "text",
    "duration": 6,
    "ratio": "16:9",
    "content": {
      "prompt": "integrated_multimodal_description: [Shot 1] ..."
    },
    "usage": {
      "prompt_tokens": 5641,
      "completion_tokens": 1529,
      "total_tokens": 7170
    }
  },
  "aiping_id": "request-uuid"
}

响应字段：

字段	类型	说明
`task.id`	string	任务 ID。
`task.model`	string	模型名。平台会归一化为平台标准模型名返回。
`task.status`	string	任务状态，可能为 `queued`、`running`、`succeeded`、`failed`、`cancelled`。
`task.task_type`	string	任务类型，`generation` / `h3_context_ir` / `regeneration`。
`task.created_at`	int	创建时间，Unix 秒。
`task.updated_at`	int	更新时间，Unix 秒。
`task.resolution`	string	分辨率。
`task.duration`	int	时长（秒）。
`task.ratio`	string	画面比例；图生视频未显式指定时可能为空串 `""`。
`task.content.url`	string	生成视频的下载链接（`generation` / `regeneration`）。限时链接，请及时归档。
`task.content.prompt`	string	增强 prompt（`h3_context_ir`）。
`task.usage`	object	用量信息，见下。
`aiping_id`	string	平台请求 ID。

usage 用量字段说明：

用量字段	说明
`total_seconds`	本次计费总秒数 = 输入秒数 + 输出秒数。
`input_seconds`	输入参考视频计费秒数（含参考视频时计）。
`output_seconds`	输出视频计费秒数。
`input_image_count`	本次计费涉及的图片数量。
`total_tokens`	H3-Context-IR 任务使用的 Token 总数。
`prompt_tokens`	H3-Context-IR 任务的输入 Token 数。
`completion_tokens`	H3-Context-IR 任务的输出 Token 数。

4.2 任务列表

GET /api/v1/multimodal/minimax/videos/query/video_generation

查询当前用户的 MiniMax 视频任务列表，仅返回近 7 天创建的任务（total 也按 7 天窗口统计）。

查询参数：

参数名	类型	必填	说明
`page_num`	int	否	页码，从 1 开始，默认 1。
`page_size`	int	否	每页条数，默认 20
`filter.status`	string	否	按状态过滤，`queued` / `running` / `succeeded` / `failed` / `cancelled`。
`filter.task_ids`	string	否	按任务 ID 过滤，支持 `a,b` 逗号分隔或重复传参 `filter.task_ids=a&filter.task_ids=b`，自动去重。
`filter.model`	string	否	按平台标准模型名过滤。
`filter.task_type`	string	否	按任务类型过滤，`generation` / `h3_context_ir` / `regeneration`。

过滤条件为多条件 AND，且计入 total（翻页数量与 total 一致）。非法过滤值不报错，静默返回空结果。列表按创建时间倒序，最新在前。

响应示例：

json

{
  "items": [
    {
      "id": "426000000000002",
      "model": "MiniMax-H3",
      "status": "succeeded",
      "task_type": "regeneration",
      "resolution": "2K",
      "duration": 7,
      "ratio": "",
      "created_at": 1785729083,
      "updated_at": 1785729200,
      "content": {
        "url": "https://example.com/output-2k.mp4?Expires=...&Signature=..."
      },
      "usage": {
        "total_seconds": 14,
        "input_seconds": 7,
        "output_seconds": 7
      }
    }
  ],
  "total": 10,
  "aiping_id": "request-uuid"
}

响应字段：

字段	类型	说明
`items`	array[object]	任务列表，元素结构与查询任务的 `task` 对象一致。
`total`	int	满足过滤条件的任务总数（近 7 天窗口内）。
`aiping_id`	string	平台请求 ID。

4.3 取消 / 删除任务

DELETE /api/v1/multimodal/minimax/videos/video_generation/{task_id}

同一端点按任务的实时状态决定行为：

任务实时状态	行为
`queued`（排队中）	取消任务，未开始处理，不扣费
`succeeded` / `failed`（已完成）	删除任务记录
`running`（运行中）	不可操作，返回错误（处理中无法取消）
`cancelled`（已取消）	不可再操作，返回错误

删除成功响应示例：

json

{
  "task_id": "426000000000001",
  "action": "deleted",
  "status": "deleted",
  "aiping_id": "request-uuid"
}

5. 错误响应

创建参数错误、查询错误等场景，透传 MiniMax 官方 OpenAI 风格错误，内部错误码嵌在 message 文本里：

json

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, ... (2013)",
    "http_code": "400"
  },
  "aiping_id": "request-uuid"
}

6. 注意事项

生成结果链接（content.url）为限时下载链接，请及时归档，过期后需重新通过单任务查询接口获取新链接。
响应统一追加平台请求 ID aiping_id（同时通过响应头 AIPing-Id 返回）。

图像生成模型

视频生成模型

可灵 AI

MiniMax

语音生成模型

MiniMax

MiniMax-H3 接口文档

1. 接口列表

2. 鉴权与通用约定

请求头

3. 创建视频任务

3.1 创建视频生成任务

3.2 创建 H3-Context-IR 任务

3.3 创建视频再生成任务

按任务 ID 再生成

按原视频再生成

4. 任务管理

4.1 查询任务

4.2 任务列表

4.3 取消 / 删除任务

5. 错误响应

6. 注意事项

可灵 AI

MiniMax

MiniMax

MiniMax-H3 接口文档 ​

1. 接口列表 ​

2. 鉴权与通用约定 ​

请求头 ​

3. 创建视频任务 ​

3.1 创建视频生成任务 ​

3.2 创建 H3-Context-IR 任务 ​

3.3 创建视频再生成任务 ​

按任务 ID 再生成 ​

按原视频再生成 ​

4. 任务管理 ​

4.1 查询任务 ​

4.2 任务列表 ​

4.3 取消 / 删除任务 ​

5. 错误响应 ​

6. 注意事项 ​

MiniMax-H3 接口文档

1. 接口列表

2. 鉴权与通用约定

请求头

3. 创建视频任务

3.1 创建视频生成任务

3.2 创建 H3-Context-IR 任务

3.3 创建视频再生成任务

按任务 ID 再生成

按原视频再生成

4. 任务管理

4.1 查询任务

4.2 任务列表

4.3 取消 / 删除任务

5. 错误响应

6. 注意事项