跳到内容

MiniMax ​

更新时间

Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation认证: Tokenhub API Key / Bearer

MiniMax 视频(海螺视频)是 MiniMax 推出的视频生成模型系列,支持文生视频、图生视频(首帧 / 首尾帧)、多模态参考生视频等能力,具备 2K 直出、原生立体声等特性。H3 支持文本以及图片、视频、音频的多模态参考生成;H3 Max 支持文本和首帧 / 尾帧输入。

两款模型统一使用 content 多模态数组传参,提交端点为 POST /v1/wand/minimax-video-v2/generation,查询端点为 GET /v1/wand/minimax-video-v2/tasks/{task_id}。文生、图生、多模态参考生三种能力共用同一提交端点,通过 content 数组中的素材类型与 role 区分。

基本信息 ​

项目值
调用路径Tokenhub API
支持解除护栏支持

前提条件 ​

参考: 下文所有示例中的 YOUR_API_KEY 均需替换为您自己的 API Key,鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。

各版本支持规格 ​

版本分辨率比例时长选型建议
minimax-video-h3768P / 2K21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:164 ~ 15 秒旗舰款:2K 直出、多模态参考(图 / 视频 / 音频)、原生立体声。
minimax-video-h3-max480P / 768P21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:165~15 秒H3 极速版:出片更快、成本更低;不支持中间帧与多模态参考生视频。

参考: ratio(画幅)取值规则:文生视频必填且不能为 adaptive;图生视频由输入图片决定(恒 adaptive);多模态参考生视频可选。

输入模式 ​

版本输入
minimax-video-h3文生视频 / 图生视频(首帧和尾帧)/ 基于多模态参考的生成
minimax-video-h3-max文生视频 / 图生视频(首帧 / 尾帧),不支持中间帧。

分辨率转换 ​

版本输入分辨率输出分辨率
minimax-video-h31080P / 4K768P / 2K
minimax-video-h3-max1080P / 2K / 4K768P

H3 Max 不支持中间帧和多模态参考输入。

调用流程 ​

视频生成属于耗时较长的任务(通常 1~3 分钟),因此 API 采用异步调用方式,由以下两个步骤组成。

  1. 提交任务:调用 POST /v1/wand/minimax-video-v2/generation,成功后会返回 task_id。
  2. 轮询结果:用 task_id 调用任务结果查询 API,直到状态变为 task.status = succeeded,再从 task.content.url 中获取视频 URL。

参考: 所有 API 响应中都包含用于排查问题的顶层 request_id。查询 API 还会返回表示用量(含 tokenhub_usage.total_tokens)的 tokenhub_usage。任务状态枚举为 queued / running / succeeded / failed / cancelled,请以实际响应为准。

文生视频 ​

API 说明 ​

若仅使用文本提示词生成视频,请在提示词中用自然语言直接描述运镜等镜头表现。

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

请求参数 ​

参数必填类型说明
model必填string模型名称。取值:minimax-video-h3、minimax-video-h3-max
content必填array[object]多模态输入数组。文生视频时仅包含一个 text 元素。子字段:type(text)、text(提示词)。
resolution必填string视频分辨率。h3:768P / 2K(1080P 输入会降级为 768P,4K 输入会降级为 2K),h3-max:仅支持 480P / 768P,不支持 2K(1080P / 2K / 4K 输入会在无额外提示的情况下降级为 768P)。
duration必填integer视频时长(秒)。h3:4~15 的整数,h3-max:5~15 的整数(不支持 4 秒)。
ratio必填string宽高比。文生视频时为必填,且不能使用 adaptive(adaptive 会按 16:9 处理)。可选项:21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。
aigc_watermark选填boolean是否添加 AIGC 水印。默认值:false。

请求示例 ​

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "一只橙色小猫在窗台上看向镜头"
    }
  ],
  "resolution": "2K",
  "duration": 6,
  "ratio": "16:9"
}'

参考: 若要调用高速版本,请将示例中的 model 换成 minimax-video-h3-max。h3-max 不支持 2K 或 4 秒 时长。

响应参数 ​

字段类型说明
task_idstring所创建任务的任务 ID,用于轮询查询任务状态。
request_idstring用于排查问题的唯一请求标识符。

参考: 提交响应中不包含 base_resp。提交是否成功,以 HTTP 状态码和是否返回 task_id 判断。

响应示例 ​

json
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

错误码 ​

请求失败时会返回错误码。具体错误码和处理建议请参考「附录:统一错误码」。任务提交成功后,生成阶段的任务状态可通过「查询任务结果」API 确认。

图生视频(首帧 / 首帧和尾帧) ​

API 说明 ​

将图片作为首帧,并可选地同时指定为尾帧,再结合文本提示词生成视频。输出宽高比跟随输入图片。

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

请求参数 ​

参数必填类型说明
model必填string模型名称。取值:minimax-video-h3、minimax-video-h3-max
content必填array[object]多模态输入数组:text 1 个 + image_url 项 1~2 个(role 为 first_frame / last_frame,首帧可省略 role)。图片约束:JPG / JPEG / PNG / WEBP / HEIC / HEIF,宽高 [256, 5760] px,宽高比 [0.4, 2.5],单张图片 ≤ 30 MB;支持 URL 或 Base64 两种格式。
• URL:需公网可访问(http / https)。
• Base64:所有图片大小和 ≤ 75 MB,转为 Base64 后大小和 ≤ 100 MB;格式为 data:image/<图片格式>;base64,<Base64 编码>(注:图片为 jpg 时格式填 jpeg)。
resolution必填string视频分辨率。h3:768P / 2K(1080P 输入会降级为 768P,4K 输入会降级为 2K),h3-max:仅支持 480P / 768P,不支持 2K(1080P / 2K / 4K 输入会在无额外提示的情况下降级为 768P)。
duration必填integer视频时长(秒)。h3:4~15 的整数,h3-max:5~15 的整数(不支持 4 秒)。
ratio选填string宽高比。图生视频的默认值为 adaptive(由输入图片决定),也可以显式指定 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。其他取值会被忽略且不报错。
aigc_watermark选填boolean是否添加 AIGC 水印。默认值:false。

参考: minimax-video-h3-max 支持首帧和尾帧,但不支持中间帧。

请求示例 ​

首帧和尾帧生成:

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "从首帧自然过渡到尾帧"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/start.jpg"
      },
      "role": "first_frame"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/end.jpg"
      },
      "role": "last_frame"
    }
  ],
  "resolution": "768P",
  "duration": 6
}'

响应参数 ​

与「文生视频」的输出参数相同。

响应示例 ​

json
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

错误码 ​

请求失败时会返回错误码。具体错误码和处理建议请参考「附录:统一错误码」。任务状态说明与「文生视频」相同。

多模态参考生视频(H3 专用) ​

API 说明 ​

将文本与参考图片、参考视频或参考音频组合生成视频。该功能仅支持 minimax-video-h3。minimax-video-h3-max 不支持多模态参考输入,若 content 中存在 reference_image、reference_video 或 reference_audio,会立即返回参数错误。不能仅输入音频。必须包含至少一个参考视频或图片。

API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation

请求参数 ​

参数必填类型说明
model必填string模型名称。取值:minimax-video-h3
content必填array[object]多模态输入数组:text 1 个 + 参考素材(role 为 reference_image / reference_video / reference_audio)。参考图片:最多 9 个,参考视频:最多 3 个,参考音频片段:最多 3 个,全部素材:最多 12 个。子字段和素材限制条件请参考下表。
resolution必填string视频分辨率。可选项:768P / 2K。
duration必填integer视频时长(秒)。可选项:4~15 的整数。
ratio选填string宽高比。默认值为 adaptive(自动),也可显式设为 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16。
aigc_watermark选填boolean是否添加 AIGC 水印。默认值:false。

content 数组元素的子字段:

参数必填类型说明
type必填string素材类型。枚举值:text / image_url / video_url / audio_url。
text条件必填string文本提示词。type=text 时为必填(每个请求都必须包含一个非空的 text 项)。
image_url条件必填object图片素材。type=image_url 时为必填。支持 URL 或 Base64。约束:JPG / JPEG / PNG / WEBP / HEIC / HEIF,宽高 [256, 5760] px,宽高比 [0.4, 2.5],单张 ≤ 30 MB;Base64 格式为 data:image/<格式>;base64,<编码>(jpg 填 jpeg)。结构:{ "url": "..." }
video_url条件必填object视频素材。type=video_url 时为必填。支持 URL 或 Base64。约束:MP4 / MOV,单段 2~15 秒、总时长 ≤ 15 秒,单个 ≤ 50 MB;Base64 所有参考视频大小和 ≤ 64 MB,格式为 data:video/<格式>;base64,<编码>(mov 填 quicktime)。结构:{ "url": "..." }
audio_url条件必填object音频素材。type=audio_url 时为必填。支持 URL 或 Base64。约束:WAV / MP3,单段 2~15 秒,单个 ≤ 15 MB;Base64 所有音频大小和 ≤ 48 MB、转为 Base64 后 ≤ 64 MB,格式为 data:audio/<格式>;base64,<编码>(mp3 填 mpeg)。结构:{ "url": "..." }
role选填string素材用途。枚举值:first_frame / last_frame / reference_image / reference_video / reference_audio。

参考: 图生视频和多模态参考生成是互斥的。若 content 中存在 reference_image / reference_video / reference_audio 角色中的任意一个,就不能使用 first_frame / last_frame,反之亦然。参考视频:MP4 / MOV(H.264 / H.265),不超过 50 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒,宽度和高度分辨率 256~5760 px,帧率 23.976~60 fps。参考音频:WAV / MP3,不超过 15 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒。不能仅输入音频。整个请求正文大小不能超过 64 MB。较大的文件请使用公网 URL 而非 Base64。

请求示例 ​

bash
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/generation' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "minimax-video-h3",
  "content": [
    {
      "type": "text",
      "text": "参考图中的角色在参考视频的场景中自然运动"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/character.jpg"
      },
      "role": "reference_image"
    },
    {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/scene.mp4"
      },
      "role": "reference_video"
    }
  ],
  "resolution": "768P",
  "duration": 6,
  "ratio": "16:9"
}'

响应参数 ​

与「文生视频」的输出参数相同。

响应示例 ​

json
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

错误码 ​

请求失败时会返回错误码。具体错误码和处理建议请参考「附录:统一错误码」。任务状态说明与「文生视频」相同。

查询任务结果 ​

API 说明 ​

所有生成功能共用的任务查询方式。提交任务并返回 task_id 后,通过统一的任务查询端点轮询任务状态。成功后从结果中获取视频 URL。

API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/{task_id}

参考: 路径中的 {task_id} 是提交任务时返回的 task_id,示例中以 YOUR_TASK_ID 表示。视频生成大约需要 1~3 分钟,建议每 3~5 秒 轮询一次。

请求参数 ​

参数必填类型说明
task_id必填string任务 ID(路径参数),即提交任务时返回的 task_id。

请求示例 ​

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-video-v2/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

响应参数 ​

字段类型说明
taskobject任务对象。
task.idstring任务 ID。
task.modelstring所使用的模型名称(例如 MiniMax-H3、MiniMax-H3-Max)。
task.statusstring任务状态:queued / running / succeeded / failed。
task.task_typestring任务类型(例如 generation(视频生成))。
task.created_atinteger任务创建时间,为秒级 Unix 时间戳。
task.updated_atinteger任务更新时间,为秒级 Unix 时间戳。
task.contentobject所创建任务结果的内容,成功时返回。
task.content.urlstring生成视频的下载 URL。它是有效期为 12 小时 的临时 URL,请立即下载并保存。
task.durationinteger视频时长(秒)。
task.resolutionstring视频分辨率(例如 768P)。
task.ratiostring视频宽高比(例如 16:9)。
task.usageobject任务的视频用量信息。
task.usage.input_image_countinteger输入图片数。
task.usage.input_secondsinteger输入视频时长(秒)。
task.usage.output_secondsinteger输出视频时长(秒)。
task.usage.total_secondsinteger全部视频时长(秒)。
tokenhub_usageobject本次请求的用量。
tokenhub_usage.total_tokensinteger本次任务消耗的 token 数,用于计费和结算。
request_idstring用于定位和排查问题的唯一请求标识符。

参考: 查询响应是不含 base_resp 或顶层 status 的 task 对象。任务标识符和状态位于 task.id / task.status 中。

响应示例 ​

生成成功:

json
{
  "task": {
    "id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
    "model": "MiniMax-H3-Max",
    "task_type": "generation",
    "status": "succeeded",
    "created_at": 1772345678,
    "updated_at": 1772345810,
    "resolution": "768P",
    "duration": 5,
    "ratio": "16:9",
    "content": {
      "url": "https://example.com/output-video.mp4"
    },
    "usage": {
      "total_seconds": 5,
      "input_seconds": 0,
      "output_seconds": 5,
      "input_image_count": 0
    }
  },
  "tokenhub_usage": {
    "total_tokens": 102655
  },
  "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}

错误码 ​

status说明处理建议
succeeded生成成功从 task.content.url 中获取视频 URL。
queued / running排队等待 / 生成中每 3~5 秒 轮询一次,直到任务成功。
failed生成失败确认失败原因(参考 task.error)并修正后重试。若持续失败,请联系技术支持并提供 request_id。

请求级错误码请参考「附录:统一错误码」。

附录 ​

统一错误码 ​

HTTP 状态码业务码错误信息说明
2000成功请求成功。
4011000认证失败缺少 Authorization 或 apikey 无效。
4011001Authorization 为空未传入 Authorization 头。
4011002Authorization 无效apikey 无效或已过期。
4011003Authorization 尚未生效apikey 尚未生效。
4011004Authorization 已过期apikey 已过期。
4291100账号异常账号异常(可能因结算欠费、停用或封禁导致)。
4291101账号欠费(后付费)后付费账号的结算已欠费。
4291102资源包耗尽或已过期资源包已耗尽或已过期。
4031103拒绝访问所请求的资源无法访问所请求的资源(未订阅相应模型/功能)。
4001200请求参数有误请求参数有误(缺少必填字段、类型有误、枚举值超出范围等)。
4001201参数无效参数值有误。请在文档中确认有效取值范围。
4041202所请求的方法无效HTTP 方法有误。
4041203所请求的资源不存在端点路径有误或资源不存在。
4001300触发平台策略触发了平台策略(例如内容审核未通过或输入不合规)。
4001301触发平台敏感词列表内容中包含敏感词或不合规的提示词。
4291302API 调用频率过高调用频率过高,已触发限速。
4291303并发数或 QPS 超出限制并发数或 QPS 超出预设配额。
4001304触发 IP 策略触发了基于 IP 地址策略的拦截。
5005000内部服务器错误内部服务器错误。
5035001服务器暂时不可用服务暂时不可用(通常因高负载或维护导致)。
5045002服务器内部超时服务器内部超时。

通用素材限制条件 ​

图片:JPG / JPEG / PNG / WEBP / HEIC / HEIF,不超过 30 MB,宽度和高度 256~5760 px,宽高比 0.4~2.5,首帧最多 1 个,尾帧最多 1 个,参考图片最多 9 个。

视频(参考视频,h3 专用):MP4 / MOV(H.264 / H.265,音频 AAC / MP3),不超过 50 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒,宽度和高度 256~5760 px,宽高比 0.4~2.5,帧率 23.976~60 fps。

音频(参考音频,h3 专用):WAV / MP3,不超过 15 MB,最多 3 个片段,每个片段 2~15 秒 且总时长不超过 15 秒。

参考: 整个请求正文大小不能超过 64 MB。较大的文件请使用公网 URL 而非 Base64。

FAQ ​

1. 两个模型中应该选择哪一个? ​

  • 需要 2K 直接输出、多模态参考(参考图片/视频/音频)、最短时长 4 秒 时:minimax-video-h3。
  • 不需要多模态参考,但要 H3 的画质,并希望生成更快、成本更低时:minimax-video-h3-max。

2. 时长和分辨率的限制是什么? ​

  • h3:时长 4~15 秒,分辨率 768P / 2K(1080P 输入会降级为 768P,4K 会降级为 2K)。
  • h3-max:时长 5~15 秒(不支持 4 秒),分辨率仅支持 480P / 768P,1080P / 2K / 4K 输入会在无额外提示的情况下降级为 768P。

3. 如何控制运镜? ​

在提示词中用自然语言描述运镜,例如「镜头缓慢推近」或「镜头向左横移」。无需特殊的指令语法。

4. 生成的视频链接会过期吗? ​

链接会过期。生成结果是有效期为 12 小时 的临时地址。任务成功后,请立即下载视频文件并转存到自有存储中。请勿依赖该链接长期使用。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages