选择模型
model 选择 Base / Fast / Mini,mode 选择生成方式,resolution 选择 480p / 720p。Pro 暂未开放。
PUBLIC VIDEO API
使用模型版本、生成模式、分辨率、比例、秒数、提示词、AI 优化开关和媒体素材提交异步视频生成任务。
https://minimax.api.easyframe.cnAuthorization: Bearer sk-...。可在 API 面板创建 Key,或使用 API 调试台 可视化调用同一组公开接口。01 / QUICK START
model 选择 Base / Fast / Mini,mode 选择生成方式,resolution 选择 480p / 720p。Pro 暂未开放。
调用 POST /v1/videos,发送时长、提示词和该模型允许的媒体素材。
用返回的 id 查询状态,完成后通过 /content 下载 MP4。
MINIMAX H3 V2
已有 MiniMax H3 V2 客户端可继续使用官方的 model、content[]、duration 与 ratio 请求结构;现有 /v1/videos 接口保持不变。
POST /v2/video_generation创建任务,成功返回 {"task_id":"task_..."}。GET /v2/query/video_generation/{task_id}查询 queued / running / succeeded / failed / cancelled,成功视频位于 task.content.url。curl -fsS https://minimax.api.easyframe.cn/v2/video_generation \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
--data-binary '{
"model": "MiniMax-H3",
"content": [{"type": "text", "text": "A paper boat crosses a sunlit stream."}],
"resolution": "768P",
"duration": 5,
"ratio": "16:9"
}'
MiniMax-H3 使用 Base 档位及其已持久化的全局或用户价格;官方 768P 名称对应当前模型对齐的 720p 画布,响应同时返回 X-H3-Native-Resolution: 720p。首尾帧请求按官方规则忽略具体 ratio;图生视频及其他无法确定画布的 adaptive 请求使用 16:9,并通过 X-H3-Adjusted 告知。first_frame、last_frame、reference_image、reference_audio;参考图最多 9 张、参考音频最多 3 个、合计最多 12 个。每个文本项最多 7,000 字符;多个文本项合并后的提示词最多 30,000 字符。2K、4 秒、参考视频、callback_url、mm_file://、任务列表/删除、Context-IR 和再生成会返回官方结构错误,不会创建任务或计费。ARK IMAGE API
Ark 图片客户端使用公开 Base URL https://minimax.api.easyframe.cn/api/v3 和本站 API Key。公开 URL 不包含上游内部的 /plan 路径;也可使用兼容前缀 /v3。
POST /api/v3/images/generations已启用并配置价格后调用 Seedream 图片生成。| 模型 | 类型 | 状态 |
|---|---|---|
doubao-seedream-5.0-lite | 图片 | 适配已就绪;管理员明确配置持久化价格前不开放生产调用 |
02 / MODEL CATALOG
目录保留 minimax-h3-pro,当前状态为暂未开放;可调用版本为 minimax-h3-mini、minimax-h3-fast 和 minimax-h3-base。生成模式和 480p / 720p 分辨率由请求参数独立选择,不提供 -standard 型号。
03 / REQUEST CONTRACT
纯文生视频直接使用 JSON。素材可先直传 TOS 并在 JSON 中引用 asset_...;已有 HTTP(S) URL、multipart 和 base64 请求会由平台校验后自动转存 TOS。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | enum | 是 | minimax-h3-mini、minimax-h3-fast 或 minimax-h3-base。minimax-h3-pro 暂未开放,调用返回 HTTP 503 和 model_temporarily_unavailable。 |
mode | enum | 是 | t2va、i2va、fl2va、l2va 或 ref2va。 |
resolution | enum | 是 | 480p 或 720p。 |
prompt | string | 是 | UTF-8 文本,最多 30,000 字符。可以直接提交自然语言,也可以提交下方的官方 H3 结构。所有提示词都会在入队前经过内容安全审查。prompt_optimization=false 时,通过审查的 Unicode 字符、标点、引号、空格、换行、标签和时间码均按输入原样传递。 |
prompt_optimization | boolean | 否 | 只能是 true 或 false,默认 false。要求文字无失真时必须保持 false;设为 true 表示授权 AI 重组结构描述,但台词、歌词和画面文字仍须逐字保留。普通优化失败时保留原始提示词并返回 prompt_optimization.fallback=true。已识别的人物替换请求在两次输出均不合规时改用经过校验的六段式确定性修复。 |
seconds | enum(integer|string) | 是 | 只允许 5、6、7、8、9、10、11、12、13、14 或 15。必须为整数,按输出秒计费;JSON 可传整数,multipart 可传字符串,例如 "5"。 |
aspect_ratio | enum | 否 | 画面比例,默认 16:9。支持 16:9 横屏、9:16 竖屏、1:1 方屏、4:3/3:4、21:9/9:21、4:5/5:4。各比例同价,按 档位×分辨率 计费。 |
images | file|asset ID|URL | 按模型 | I2VA 传 1 张首帧;FL2VA 传 1-2 张,依次是首帧和尾帧;L2VA 传 1 张尾帧;Ref2VA 最多 9 张参考图。JSON 值可使用已完成上传的 asset_... 或公开 HTTP(S) URL。 |
audios | file|asset ID|URL | REF2VA 可选 | 参考音频,最多 3 个。REF2VA 至少需要一张图片或一个音频,两类合计最多 12 个。JSON 值可使用已完成上传的 asset_... 或公开 HTTP(S) URL。 |
videos 字段,将返回 HTTP 422 和 reference_video_not_supported;网关会在计费和视频内容落盘前拒绝,任务不会创建。该限制只针对参考输入,接口仍正常生成并返回 MP4 视频。prompt_review_acknowledgment_required 并要求账号在工作台确认。自动处置关闭不影响请求审核和拒绝审计;优化器输出不会触发账号处罚。低于管理员双门置信度阈值的事件不计入自动停用。被拒正文不写入处置库,只保留摘要、分类、置信度、策略版本和请求身份。审核、确认、限速或停用都不会创建任务、占用生成算力或产生生成费用。20 MiB。50 MiB。120 MiB;完整 multipart 请求最大 128 MiB。限制值本身允许,超过 1 字节即拒绝。本地文件超限返回 HTTP 413、错误码 media_too_large,任务不会创建。TOS 素材在签发上传地址和完成确认时均校验大小。
小素材保持原文件。图片超过 8 MiB 或长边超过 2048 像素时,自动缩放并转为高质量 JPEG。只有处理后的文件会作为模型输入。
POST /v1/assets声明图片或音频的文件名、类型、字节数及可选 SHA-256,返回对象级 PUT 签名。PUT {upload.url}直接上传文件;必须原样发送响应中的全部 upload.headers。POST /v1/assets/{asset_id}/complete平台 HEAD 校验 TOS 对象后将素材标记为 ready。GET /v1/assets/{asset_id}查询当前 API Key 所属素材的状态和有效期。POST /v1/assets
{
"kind": "image",
"filename": "first.png",
"content_type": "image/png",
"size_bytes": 183421,
"sha256": "可选的 64 位十六进制 SHA-256"
}
PUT {upload.url}
Headers: {upload.headers}
Body: first.png 的原始字节
POST /v1/assets/asset_.../complete
POST /v1/videos
{
"model": "minimax-h3-base",
"mode": "i2va",
"resolution": "720p",
"seconds": 5,
"prompt": "A slow camera push toward the subject.",
"images": ["asset_..."]
}
04 / H3 PROMPT SYNTAX
prompt 始终只是一个 UTF-8 字符串,不是嵌套对象。自然语言和官方 H3 结构都能直接提交;结构化写法用于更精确地控制时间线、声音和参考关系。
| 提交方式 | prompt 内容 | prompt_optimization | 是否改写 |
|---|---|---|---|
| 自然语言原文 | 直接描述画面、动作、镜头、台词和声音,无固定模板 | false | 不改写,逐字符传递 |
| 官方 H3 原文 | 按本节三段式或六段式填写完整字符串 | false | 不改写,字段、标签、换行和原文全部保留 |
| AI 整理 | 自然语言或已有提示词 | true | 会重组结构描述;台词、歌词和画面文字逐字保留 |
prompt_optimization=false。API 不会翻译、清理、合并或重排 Unicode 字符、标点、单双引号、空格、换行、[Shot N]、<d> 或时间码。curl --form-string 'prompt=...'。不要使用 -F 'prompt=@...' 发送以 @ 开头的原文,因为 curl 会把它解释为文件。媒体文件字段仍使用 -F images=@file.png。GUIDED FORMAT
先选择模式,再按顺序展开每个必填段。例子中的字段顺序可直接作为当前模式的骨架。
integrated_multimodal_description: [Shot 1] 2D-animated, a wide shot frames two celestial bodies orbiting in a deep star field. The camera pushes in with small amplitude at slow speed as the smaller body develops cracks and fragments drift outward. An unseen narrator (S1) says in an off-screen voiceover: <d>[Chinese] 这个距离被称为“洛希极限”。</d> while every visible character's lips remain completely closed.
overall_soundscape: Low space ambience continues beneath a soft rumble as the smaller body fractures.
non_diegetic_music: Sparse piano notes at a slow tempo with sustained low strings.
整个代码块就是一个 prompt 字符串。字段名和结构描述使用英文;<d> 内的中文、中文引号和句号保持原样。T2VA 不添加关键帧对齐指令。
@ 指令只是浏览器端编辑工具,不是 API 必填格式。只有用户明确输入 @ 指令时 Studio 才会在发送前编译;普通文字和粘贴的官方 H3 原文保持原样。[Shot N] 只表示真实剪辑点。同一机位里的动作、表情和台词阶段使用 @时间,不要拆成多个镜头;AI 优化默认保持单一连续镜头,只保留用户明确要求的切镜。prompt_optimization=true 时,提示词和生成规格才会交给 AI 优化;上传的图片和音频文件不会发送给提示词优化服务。在 Studio 提示词框输入 @ 可搜索辅助指令;API 客户端无需使用这些指令。官方 H3 原文可保持原样粘贴,需要转换时再使用显式的“导入 H3”操作。
| 指令 | 用途 | 输入例子 | 转换结果 |
|---|---|---|---|
@结构 | 展开当前模型的完整结构 | @结构 | 基础模式三段式;Ref2VA 六段式 |
@画面 | 基础模式音画正文 | @画面 | integrated_multimodal_description: |
@主体定义 | Ref2VA 参考定义 | @主体定义 | subject_definitions: |
@摘要 | Ref2VA 任务摘要 | @摘要 | summary: |
@保留分析 | Ref2VA 保留关系 | @保留分析 | retention_analysis: |
@详细描述 | Ref2VA 逐镜头正文 | @详细描述 | detailed_description: |
@环境声 | 环境声、动作声和非语言人声 | @环境声 "雨声、脚步声和远处车流声" | overall_soundscape: 雨声、脚步声和远处车流声 |
@配乐 | 角色听不到的画外配乐 | @配乐 无 | non_diegetic_music: N/A |
@镜头 | 仅用于真实切镜 | @镜头 2 00:08.500 跳切到人物面部大特写。 | [Shot 2] At 00:08.500, 跳切到人物面部大特写。 |
@时间 | 当前镜头内的动作或台词时间,不切镜 | @时间 00:02.000 女子缓缓抬眼。 | At 00:02.000, 女子缓缓抬眼。 |
@说话人 | 单个稳定说话人 ID | @说话人 1 | (S1) |
@共同说话 | 多个说话人共同发声 | @共同说话 1,2 | (S1,S2) |
@台词 | 保留原语言和原文台词 | @台词 中文 "我们出发吧。" | <d>[Chinese] 我们出发吧。</d> |
@歌词 | 保留原语言和原文歌词 | @歌词 英语 "Here comes the sun." | <d>[English] Here comes the sun.</d> |
@旁白 | 画外旁白并声明画面人物闭唇 | @旁白 1 中文 "我仍记得那条路。" | (S1) says in an off-screen voiceover: <d>...</d> |
@跨镜 | 同一句语音跨越切镜 | @台词 中文 "我们现在@跨镜" | <d>[Chinese] 我们现在<scenetrans></d> |
@截断 | 语音被视频结尾截断 | @台词 中文 "等一下@截断" | <d>[Chinese] 等一下<cutoff></d> |
@画面文字 | 保留画面中真实文字 | @画面文字 "营业中" | "营业中" |
@运镜 | 运动类型、幅度和速度 | @运镜 推近 小幅 慢速 朝向她手中的信。 | The camera pushes in with small amplitude at slow speed... |
@主体 | Ref2VA 参考主体 | @主体 1 | <Subject 1> |
@图片 | 参考图像或具体帧锚点 | @图片 1 | <Picture 1> |
@音频 | 复用或参考音频 | @音频 1 | <Audio 1> |
@任务 | Ref2VA 任务类型 | @任务 参考生成 + 音频参考 | [reference generation + audio reference] |
@视觉关系 | 视觉参考保留程度 | @视觉关系 完全保留 | fully_preserved |
@音频关系 | 音频复制或参考程度 | @音频关系 参考 | reference |
<d>[Chinese] 我们出发吧。</d> 后会显示为 @台词 中文 "我们出发吧。";发送请求时再还原为完全相同的官方标签。integrated_multimodal_description: [Shot 1] ...
overall_soundscape: ...
non_diegetic_music: ...
正文按时间线同时写视觉、动作、镜头、对话与画内声音。按照官方 Skill,固定字段和结构描述使用英文;只有台词、歌词和画面中真实可见的文字保留原语言与原文。
subject_definitions:
...
summary:
...
retention_analysis:
...
detailed_description:
...
overall_soundscape:
...
non_diegetic_music:
...
For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.Picture 1 对齐 0.00 秒,Picture 2 对齐视频结尾的 S.SS 秒。指令放在第一行。<Picture 1> 对齐最后一个 [Shot N] 在视频结尾的 S.SS 秒。[Shot 1]At MM:SS.mmmAt 00:02.000, she raises her gaze.[Shot N][Shot 2] At 00:08.500, the camera cuts to...pushes in with small amplitude at slow speed。运动类型:Zoom In / Out、Push In / Pull Out、Pan Left / Right、Truck Left / Right、Tilt Up / Down、Pedestal Up / Down、Arc Shot、Tracking Shot、Static Shot、Shake Slightly / Strongly、POV、Roll Clockwise / Counterclockwise。
| 语法 | 用途 | 规则 | 完整例子 |
|---|---|---|---|
(S1) / (S1,S2) | 说话人 ID | 按首次发声顺序编号,同一说话人跨镜头始终复用同一 ID;不发声的主体不分配 ID。 | The two children (S1,S2) shout together: <d>[Chinese] 等等我们!</d> |
<d>[Language] ...</d> | 对话或歌词 | 标签内只放语言名和内容。无论时长估算是否充足,所有台词及标点均逐字保留;时长不足时自动提高语速、压缩停顿并允许对白跨镜连续,绝不删减、改写、漏读、合并或截断。 | <d>[Chinese] 我们出发吧。</d> |
off-screen voiceover | 画外旁白 | 使用确切短语 says in an off-screen voiceover,并在 <d> 后声明画面中对应角色的嘴唇保持闭合。 | The man (S1) says in an off-screen voiceover: <d>[Chinese] 我仍记得那条路。</d> while his lips remain completely closed. |
<scenetrans> | 跨切镜连续语音 | 同一句台词跨切镜时,在切镜前后两个 <d> 的连接点都放入此标签,并说明声音连续。 | [Shot 1] (S1) says: <d>[Chinese] 我们现在<scenetrans></d> and the voice continues across the cut. [Shot 2] At 00:03.500, (S1) continues: <d>[Chinese] <scenetrans>出发。</d> |
<cutoff> | 结尾截断语音 | 台词被视频结尾有意截断时放在截断处。 | (S1) calls out: <d>[Chinese] 等一下,前面是<cutoff></d> |
"visible text" | 画面可见文字 | 招牌、标签、字幕等用英文双引号包围,保留原文和标点。 | A red neon sign reading "营业中" glows above the doorway. |
<Subject N> | Ref2VA 参考主体 | 可定义人物、物体、场景、动作或风格;一个主体可来自多个素材。 | <Subject 1> is the woman whose appearance comes from <Picture 1>. |
<Picture N> | 具体图像帧锚点 | 只在图像是首帧、关键帧、尾帧或构图锚点时单独定义;仅用于主体身份时在 <Subject N> 内引用。 | <Picture 1> is the first frame of [Shot 1], showing a woman beside a café window. |
<Audio N> | 音频复用或参考 | 可复用音频信号,或参考音色、节拍、音乐风格、台词内容和音效质感。 | <Audio 1> is the voice-timbre reference for <Subject 1> (S1). |
<Picture 1>、<Picture 2> ...<Audio 1>、<Audio 2> ...Picture、Audio 和 Subject 各自从 1 开始,不共用一个编号。summary 的任务类型可使用 [keyframe completion]、[reference generation]、[audio reuse] 和 [audio reference],多个类型用 + 连接。
视觉保留程度:fully_preserved、partially_preserved、attribute_transfer、weak_reference。
音频关系:fully_copy、partially_copy、reference、weak_reference。
使用音频参考时,应在 subject_definitions 中定义 <Audio N> 的用途,并在后续段落保持一致。
| 模式 | 放置位置 | 完整例子 |
|---|---|---|
| I2VA | 提示词第一行 | For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced. |
| FL2VA | 提示词第一行 | How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot 1) aligns with the 8.00-second mark of the target video. |
| L2VA | 提示词第一行 | How the reference pictures align with the target video — <Picture 1> (from [Shot 1]) aligns with the 6.00-second mark of the target video. |
| 能力 | 规则 | 完整例子 |
|---|---|---|
| 首镜 | 从 1 开始,不写时间 | [Shot 1] Live-action, cinematic, a medium shot frames a woman beside the train window. |
| 镜内时间点 | 动作、表情、台词阶段继续使用当前镜头 | At 00:02.000, she raises her gaze and begins speaking. |
| 后续镜头 | 仅用于真实切镜;编号连续且切镜时间小于视频时长 | [Shot 2] At 00:08.500, the camera cuts to an extreme close-up. |
| 单人说话 | 按首次发声顺序分配稳定 ID | The young woman with a quiet voice (S1) says: <d>[Chinese] 我们出发吧。</d> |
| 共同说话 | 复用已有说话人 ID | The two children (S1,S2) shout together: <d>[English] Wait for us!</d> |
| 台词 / 歌词 | <d> 内只有语言标签和原文,不翻译、不改写 | <d>[Japanese] ここから始めよう。</d> |
| 画外旁白 | 使用确切短语并在标签后声明对应画面人物闭唇 | The man (S1) says in an off-screen voiceover: <d>[English] I still remember that road.</d> while his lips remain completely closed. |
| 跨镜语音 | 切镜前后各一个 <scenetrans>,并说明声音连续 | [Shot 1] (S1) says: <d>[Chinese] 我们现在<scenetrans></d> and the voice continues across the cut. [Shot 2] At 00:03.500, (S1) continues: <d>[Chinese] <scenetrans>出发。</d> |
| 结尾截断 | 在被结尾截断的位置使用 <cutoff> | (S1) calls out: <d>[Chinese] 等一下,前面是<cutoff></d> |
| 画面文字 | 英文双引号包围,保留原文和标点 | A red neon sign reading "营业中" glows above the doorway. |
运镜必须写成自然英文句子。中等幅度和正常速度通常省略;需要强调时使用 with small/large amplitude 和 at slow/fast speed。
| 类型 | 中文含义 | 完整例子 |
|---|---|---|
Zoom In | 变焦拉近 | The camera zooms in on the handwritten address. |
Zoom Out | 变焦拉远 | The camera zooms out to reveal the empty platform. |
Push In | 机位推近 | The camera pushes in with small amplitude at slow speed toward the folded letter. |
Pull Out | 机位拉远 | The camera pulls out with large amplitude at slow speed from the cyclist. |
Pan Left | 镜头左摇 | The camera pans left to follow the departing train. |
Pan Right | 镜头右摇 | The camera pans right with large amplitude at fast speed, revealing the doorway. |
Truck Left | 机位左移 | The camera trucks left beside the walking woman. |
Truck Right | 机位右移 | The camera trucks right with small amplitude along the counter. |
Tilt Up | 镜头上摇 | The camera tilts up from her shoes to her face. |
Tilt Down | 镜头下摇 | The camera tilts down to the broken glass on the floor. |
Pedestal Up | 机位升高 | The camera pedestals up above the crowded table. |
Pedestal Down | 机位降低 | The camera pedestals down to the child's eye level. |
Arc Shot | 环绕主体 | The camera moves in an arc around the singer. |
Tracking Shot | 跟随移动主体 | The camera tracks the cyclist through the wet street. |
Static Shot | 固定机位 | The camera holds a static shot as the runner exits the frame. |
Shake Slightly | 轻微抖动 | The camera shakes slightly with each distant impact. |
Shake Strongly | 强烈抖动 | The camera shakes strongly as the door slams shut. |
POV | 主体主观视角 | The shot holds the cyclist's POV while approaching the tunnel. |
Roll Clockwise | 顺时针旋转 | The camera rolls clockwise as the room appears to tilt. |
Roll Counterclockwise | 逆时针旋转 | The camera rolls counterclockwise at slow speed around the lens axis. |
| 标签 | 适用场景 | 定义例子 |
|---|---|---|
<Subject 1> | 可见人物、物体、场景、动作或风格 | <Subject 1> is the woman whose appearance comes from <Picture 1>. |
<Picture 1> | 首帧、关键帧、尾帧、编辑帧或构图锚点 | <Picture 1> is the first frame of [Shot 1], showing a woman beside a café window. |
<Audio 1> | 信号复用或音色、节拍和音效参考 | <Audio 1> is the voice-timbre reference for <Subject 1> (S1). |
| 任务类型 | 何时使用 | summary 例子 |
|---|---|---|
keyframe completion | 图片是具体首帧、关键帧或尾帧 | [keyframe completion] The target video begins from <Picture 1>. |
reference generation | 素材提供人物、场景、风格、动作或运镜指导 | [reference generation] The target video preserves <Subject 1> from <Picture 1>. |
audio reuse | 完整或部分复用同一音频信号 | [audio reuse] The target video reuses <Audio 1> as its final soundtrack. |
audio reference | 只参考音色、节拍、内容或音效质感 | [audio reference] The target speaker follows the timbre of <Audio 1> without copying its signal. |
| 关系值 | 含义 | retention_analysis 例子 |
|---|---|---|
fully_preserved | 定义的视觉角色完整保留 | <Subject 1> (appears in [Shot 1]): fully_preserved - identity and clothing are retained. |
partially_preserved | 仍使用参考,但部分特征改变 | <Picture 1> ([Shot 1] first frame): partially_preserved - composition is retained while lighting changes. |
attribute_transfer | 把参考特征迁移给另一个可识别主体 | <Subject 2> (appears in [Shot 2]): attribute_transfer - the coat pattern transfers to the target actor. |
weak_reference | 只保留宽泛风格、类别或构图相似性 | <Picture 1> (visual style): weak_reference - only the broad color treatment is retained. |
fully_copy | 完整复制源音频为最终音轨 | <Audio 1>: fully_copy - it is reused 1:1 as the complete final audio track. |
partially_copy | 只复制部分时间线或音频层 | <Audio 2>: partially_copy - the dialogue layer is copied while ambience is replaced. |
reference | 不复制信号,只参考具体声音特征 | <Audio 3>: reference - the target voice follows its timbre without copying the signal. |
weak_reference | 音频只保留宽泛类别或氛围相似性 | <Audio 4>: weak_reference - only a broadly similar acoustic texture is used. |
overall_soundscape展开例子使用 1–4 句英文汇总环境声、动作声和非语言人声;不要重复台词。只有明确要求全片完全静音时才写 N/A。
overall_soundscape: Steady rain taps against the café windows. The entrance bell rings once, followed by wet footsteps and the scrape of a chair.non_diegetic_music展开例子使用 1–3 句英文描述角色听不到的配乐,写乐器、速度、节奏和动态;没有画外配乐时写 N/A。
non_diegetic_music: Sparse piano notes at a slow tempo, joined by sustained low strings that gradually increase in volume before fading out.detailed_description 应明确构图、主体、环境、动作、运镜、声音和参考素材生效位置。@ 指令。管理员还可以选择实验验证通道,让实验通道设备接收独立的验证任务;生产通道默认不变。05 / EXAMPLES
JSON:提交完整 H3 原文并关闭优化,模型收到的提示词与 JSON 解码后的字符串一致。
curl -fsS https://minimax.api.easyframe.cn/v1/videos \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-H "Content-Type: application/json" \
--data-binary '{
"model": "minimax-h3-base",
"mode": "t2va",
"resolution": "720p",
"prompt_optimization": false,
"prompt": "integrated_multimodal_description: [Shot 1] A paper boat crosses a sunlit stream as the camera slowly pushes in.\n\noverall_soundscape: Running water and light wind.\n\nnon_diegetic_music: Sparse piano notes at a slow tempo.",
"seconds": "6",
"aspect_ratio": "9:16"
}'
multipart:图片是 0.00 秒的 <Picture 1> 首帧。
curl -fsS https://minimax.api.easyframe.cn/v1/videos \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-F model=minimax-h3-base \
-F mode=i2va \
-F resolution=480p \
-F seconds=5 \
-F aspect_ratio=16:9 \
--form-string prompt_optimization=false \
--form-string prompt='For the target video, at 0.00 seconds into the target video, <Picture 1> (from [Shot 1]) is fully referenced.
integrated_multimodal_description: [Shot 1] The camera slowly pushes toward the woman in <Picture 1> as she looks up and smiles.
overall_soundscape: Soft room tone and fabric movement.
non_diegetic_music: N/A' \
-F images=@first.png
multipart:第一张是首帧,第二张是可选尾帧。
curl -fsS https://minimax.api.easyframe.cn/v1/videos \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-F model=minimax-h3-base \
-F mode=fl2va \
-F resolution=480p \
-F seconds=5 \
-F aspect_ratio=16:9 \
--form-string prompt_optimization=false \
--form-string prompt='How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot 1) aligns with the 5.00-second mark of the target video.
integrated_multimodal_description: [Shot 1] A product begins in the position and framing established by Picture 1. The camera holds a static shot as the product rotates at a steady speed and settles into the exact pose, spacing, and composition established by Picture 2 at the end.
overall_soundscape: A quiet room tone continues beneath the soft mechanical sound of the rotating platform.
non_diegetic_music: N/A' \
-F images=@start.png \
-F images=@end.png
multipart:图片是视频结尾的 <Picture 1> 尾帧。
curl -fsS https://minimax.api.easyframe.cn/v1/videos \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-F model=minimax-h3-base \
-F mode=l2va \
-F resolution=480p \
-F seconds=5 \
-F aspect_ratio=9:16 \
--form-string prompt_optimization=false \
--form-string prompt='How the reference pictures align with the target video — <Picture 1> (from [Shot 1]) aligns with the 5.00-second mark of the target video.
integrated_multimodal_description: [Shot 1] A falling glass breaks and its fragments settle into the exact composition in <Picture 1>.
overall_soundscape: A sharp glass impact followed by fragments sliding.
non_diegetic_music: N/A' \
-F images=@last.png
multipart:参考图像和音频字段可重复,提示词使用六段式。
curl -fsS https://minimax.api.easyframe.cn/v1/videos \
-H "Authorization: Bearer $MINIMAX_API_KEY" \
-F model=minimax-h3-fast \
-F mode=ref2va \
-F resolution=720p \
--form-string prompt_optimization=false \
--form-string prompt='subject_definitions:
<Subject 1> is the person whose appearance comes from <Picture 1>.
<Audio 1> is the voice-timbre reference for <Subject 1> (S1).
summary:
[reference generation + audio reference] The target video preserves <Subject 1> and follows the referenced voice timbre.
retention_analysis:
<Subject 1> (appears in [Shot 1]): fully_preserved - identity and clothing are retained.
<Audio 1>: reference - voice timbre is referenced without copying the signal.
detailed_description:
The target video is in a realistic cinematic style.
[Shot 1] <Subject 1> (S1) walks through the frame and says, <d>[Chinese] 我们出发吧。</d>
overall_soundscape:
Natural outdoor ambience and footsteps.
non_diegetic_music:
N/A' \
-F seconds=6 \
-F aspect_ratio=16:9 \
-F images=@person.png \
-F audios=@voice.wav
06 / RESPONSE
POST /v1/videos创建任务,返回公开 task_... ID。GET /v1/videos/queue查看当前账号的并发占用、可用名额,以及当前 API Key 的活跃任务。GET /v1/videos/{id}查询状态与进度;完成后返回 1 小时有效的 TOS 下载地址,视频从完成时起保留 24 小时。POST /v1/videos/{id}/cancel取消排队中或生成中的任务;重复请求安全。GET /v1/videos/{id}/content兼容下载入口,完成后重定向到临时 TOS 地址。{
"id": "task_7f3...",
"object": "video",
"model": "minimax-h3-base",
"mode": "t2va",
"status": "queued",
"progress": 0,
"queue": {
"deadline_at": 1787414640,
"remaining_seconds": 240,
"max_wait_seconds": 240
},
"seconds": "5",
"resolution": "480p",
"aspect_ratio": "16:9",
"size": "864x480"
}queue_supply_overdue 表示系统正在执行逾期供给,而不是任务失败。progress_detail.mode 判断进度是否可测量。url 可直接下载 MP4,无需再次携带 API Key;每次查询都会刷新,有效期默认 1 小时。queue_timeout 只会出现在旧版本已终止的历史任务中。{
"id": "task_7f3...",
"status": "completed",
"url": "https://media-delivery-prod-ztzmxr.tos-cn-guangzhou.volces.com/prod/jobs/.../output.mp4?X-Tos-...",
"url_expires_at": 1787072400,
"asset_expires_at": 1787155200,
"storage_backend": "tos",
"content_type": "video/mp4",
"size_bytes": 12345678,
"sha256": "..."
}progress_detail.mode=indeterminate 表示模型仍在初始化或当前阶段没有可测量总量,此时 progress 只是兼容用的阶段下限,不是精确百分比;determinate 才表示采样器已上报可测量步骤。health=delayed 表示执行节点仍在线,但生成进度已明显超过历史基线。硬件活动指标只证明进程存活,不会重置模型进度计时。runtime_budget_seconds 是系统根据同规格成功历史的中位数、MAD 与 P90 计算的单次执行安全预算。GET /v1/videos/queue
Authorization: Bearer $MINIMAX_API_KEY
{
"object": "video.queue",
"concurrency_limit": 3,
"active_count": 2,
"key_active_count": 1,
"available_slots": 1,
"queued_count": 1,
"in_progress_count": 1,
"global_queued_count": 7,
"queue_max_wait_seconds": 240,
"scheduling_policy": "cache_fair_v3",
"queue_projection_truncated": false,
"tasks": [
{
"id": "task_7f3...",
"status": "queued",
"progress_detail": {
"stage": "queued",
"elapsed_seconds": 84.2
},
"queue": {
"deadline_at": 1787414640,
"remaining_seconds": 155,
"max_wait_seconds": 240
},
"queue_position": 1,
"queue_ahead": 0
}
]
}active_count、available_slots 和并发上限由同一账号的全部 API Key 共享。key_active_count、排队/生成数量和 tasks 只包含当前 API Key 创建的任务;状态、取消和下载也只能使用创建任务的 Key。POST /v1/videos/task_7f3.../cancel
Authorization: Bearer $MINIMAX_API_KEY排队任务立即返回 status: "cancelled"。生成中的任务先返回 cancellation_requested: true,请继续查询,直到状态变为 cancelled。已结束任务保持原状态。
07 / ERRORS
| HTTP | 场景 | 处理建议 |
|---|---|---|
401 | API Key 缺失或无效 | 在 API 面板创建或检查 Key。 |
404 | 模型或任务不存在 | 检查 model、resolution 和创建响应中的任务 ID。 |
413 | media_too_large:单个媒体、素材合计或 multipart 请求超限,任务未创建 | 压缩文件或减少本次素材后重新提交;不要使用同一请求原样重试。 |
403 | moderation_temporarily_suspended 或 moderation_manually_suspended | 等待 Retry-After 指定的时间,或通过工作台联系管理员申诉。 |
422 | 参数/媒体素材不合法、reference_video_not_supported、prompt_review_rejected,或双门拒绝的 prompt_review_acknowledgment_required | 不要提交 videos 字段;按响应修正其他字段、素材数量或提示词。仅当响应为 prompt_review_acknowledgment_required 时登录工作台完成内容安全确认。被拒绝的请求不会创建任务。 |
428 | moderation_acknowledgment_required:账号尚未完成当前内容安全确认 | 登录工作台,阅读声明、勾选确认并准确输入要求的确认文字。 |
429 | moderation_rate_limited:账号审核请求达到管理员配置的窗口上限 | 按 Retry-After 等待后再提交;任务查询和已有幂等任务不受影响。 |
429 | 账号并发已满,或 resource_budget_cooldown 资源保护已触发 | 并发已满时调用 GET /v1/videos/queue;资源保护触发时按 Retry-After 等待。已有任务的查询、取消及幂等重试不受影响。 |
503 | prompt_review_unavailable 或 moderation_audit_unavailable:审查或处置审计暂时不可用,任务未创建 | 稍后使用同一幂等键重试。 |
5xx | 其他服务暂时不可用 | 带幂等键重试创建请求。 |