# MiniMax H3 视频调用协议

> MiniMax H3 的文生视频、参考图、首尾帧、参考视频和音频、文件上传、2K再生成、提示词优化与预扣结算说明，含完整请求、查询和下载示例。

网页版:https://wanapis.com/docs/minimax-h3

最后验证:2026-11-04 · 协议候选；未做真实付费生成

模型名为 minimax-h3。先提交异步任务，保存公开任务ID，再查询和下载。高级输入及独立操作是否可用，以当前模型能力和价格返回为准；以下模板必须替换示例ID、素材和环境变量后再调用。实际生成、再生成和提示词优化会产生费用。

## 一览

| 项目 | 取值 |
| --- | --- |
| 认证 | Authorization: Bearer $WANAPIS_API_KEY；使用同一账户，令牌需允许 minimax-h3 及对应分组 |
| 默认规格 | 4秒、768P、9:16、fast_mode=false、context_ir_enabled=true |
| 输出范围 | 480p / 768P / 1080p / 2K；4–30秒，2K最长15秒；不提供4K |
| 素材数量 | 最多9图、3参考视频、3参考音频；各模式组合按接口验证 |
| 素材时长 | 参考视频总长建议不超过15秒，单片允许的15.5秒容忍按当前能力执行；音频总长不超过15秒 |
| 上传限制 | 本平台单图30MiB、单视频31MiB、单音频15MiB；请求体总量32MiB，包含multipart/JSON开销；以接口公布的有效上限为准 |
| 额度币种 | 500000 quota = 人民币1元；下面价格均为CNY，最后乘有效分组倍率 |
| 价格和能力 | GET /api/pricing → minimax-h3 的 video_pricing 与 video_pricing_meta.advanced；advanced缺失时仅使用旧能力 |

## 接入步骤

### 1. 核对模型能力与每秒价

输出和参考视频的普通基础秒价：480p ¥0.078、768P ¥0.117、1080p ¥0.182、2K ¥0.195。前5张图免费，普通超额图¥0.065/张，参考音频免费。生成内IR默认¥0.065/次。价格示例为基础分组；实际有效售价、可用模式和上传上限以模型广场与接口为准，不要自行补齐缺失的费项。

**pricing**

```
curl https://api.wanapis.com/api/pricing
```

### 2. 提交最小文本任务

POST /v1/videos 是推荐入口，POST /v1/video/generations 和 /v1/videos/generations 保留兼容。保存返回的 id，提交成功只说明任务已受理。seconds 与 duration 任选其一，若两者都写必须一致；分辨率、比例和size也不能冲突。数值4.0、分数字符串、字符串布尔值和未知字段会被拒绝。

**text-to-video**

```
curl https://api.wanapis.com/v1/videos \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "prompt": "A paper boat crosses a calm lake, slow cinematic tracking shot",
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": 4,
  "fast_mode": false,
  "context_ir_enabled": true
}'
```

### 3. 查询状态，分清两种返回格式

GET /v1/videos/{id} 返回OpenAI风格：顶层status为queued/in_progress/completed/failed，完成地址在metadata.url。GET /v1/video/generations/{id} 返回通用信封：data.status为NOT_START/SUBMITTED/QUEUED/IN_PROGRESS/SUCCESS/FAILURE，地址在data.result_url。不要把两种格式混用。每5–10秒查询一次；视频completed与billing.status=settled是不同状态。

**poll**

```
curl https://api.wanapis.com/v1/videos/task_example \
  -H "Authorization: Bearer $WANAPIS_API_KEY"

curl https://api.wanapis.com/v1/video/generations/task_example \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
```

### 4. 认证下载与保存

任务成功后使用本人公开任务ID下载，仍需Bearer认证。浏览器工作区使用同源会话播放并支持Range；不要把API key放到URL里。结果可用期不保证统一24小时，请及时保存；若响应没有expires_at，不要自行推算失效时间。关闭页面或停止查询不会撤销已经受理的任务。

**download**

```
curl https://api.wanapis.com/v1/videos/task_example/content \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  --output result.mp4
```

### 5. 本地素材先上传

每次上传一个文件，media_type为image、video或audio。先放model、media_type和可选binding_asset_id文本字段，file放最后。响应只提供本平台asset_id（id字段），不是生成任务。将第一次返回的id作为后续上传的binding_asset_id，使一组素材可一起提交；所有素材必须属于本人且仍有效。请把示例asset_image_example替换为真实返回值，不能上传完仍照抄示例ID。URL小素材也可直接在content中使用url，不必先下载再上传；本平台不以浏览器报告的时长结算。

**upload**

```
curl https://api.wanapis.com/v1/videos/assets \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -F 'model=minimax-h3' \
  -F 'media_type=image' \
  -F 'file=@./reference.webp'

curl https://api.wanapis.com/v1/videos/assets \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -F 'model=minimax-h3' \
  -F 'media_type=video' \
  -F 'binding_asset_id=asset_image_example' \
  -F 'file=@./motion.mp4'
```

### 6. 多参考图、视频和音频

content同时放一项text和各参考素材，每项都带明确type与role。每个来源对象只填url或asset_id之一，不能同时填。content不要再与prompt、input_reference或images等旧式输入混用。图片总数包含所有角色，首5图免费；参考视频按合计输入时长向上取整收费，音频免费不代表视频生成免费。请替换示例中的三个素材ID。

**multimodal**

```
curl https://api.wanapis.com/v1/videos \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": 4,
  "fast_mode": false,
  "context_ir_enabled": false,
  "content": [
    {
      "type": "text",
      "text": "A paper boat crosses a calm lake, slow cinematic tracking shot"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "asset_id": "asset_image_example"
      }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "asset_id": "asset_video_example"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "asset_id": "asset_audio_example"
      }
    }
  ]
}'
```

### 7. 首尾帧与旧单图

明确的首尾帧使用first_frame和last_frame，各最多一张，不能用同一素材同时占两个角色。旧input_reference继续接受裸URL字符串或image_url对象，并作为reference_image使用；需要约束首尾画面时用显式角色。加入参考视频可能要求将帧角色改成参考图，请按接口的组合提示调整，不要假定所有模型共享相同规则。

**first-last-frames**

```
curl https://api.wanapis.com/v1/videos \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "resolution": "768P",
  "ratio": "16:9",
  "seconds": 4,
  "context_ir_enabled": false,
  "content": [
    {
      "type": "text",
      "text": "A paper boat crosses a calm lake, slow cinematic tracking shot"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "asset_id": "asset_first_example"
      }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {
        "asset_id": "asset_last_example"
      }
    }
  ]
}'
```

### 8. 单独优化提示词，保留最终文本

独立提示词优化使用专用入口，是按次收费的文本任务，不是视频。保存id并GET /v1/videos/prompt-optimizations/{id}，成功文本在result.text。当前渠道是否支持该操作以能力返回为准。将优化文本用于下一次生成时显式设置context_ir_enabled=false，避免再次执行生成内优化；同时保留最终提示词与素材，供之后再生成使用。

**prompt-optimization**

```
curl https://api.wanapis.com/v1/videos/prompt-optimizations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "seconds": 4,
  "ratio": "16:9",
  "content": [
    {
      "type": "text",
      "text": "A paper boat crosses a calm lake, slow cinematic tracking shot"
    }
  ]
}'

curl https://api.wanapis.com/v1/videos/prompt-optimizations/task_example \
  -H "Authorization: Bearer $WANAPIS_API_KEY"
```

### 9. 从本人768P原任务再生成2K

仅适用于本人成功的minimax-h3 768P原始视频，原时长4–15秒，输出固定2K；不是任意视频放大。POST路径中的task_source_example必须换成本平台源任务ID。mode=source仅在源任务提供的可用模式包含source时使用；不要自动在两个模式之间重试。mode=content需原样重传原最终prompt和全部原参考图/视频/音频，服务端自行从本人源任务加入原片，客户端不传base_video或内部任务ID。若原任务开启了生成内IR却没有可核对的最终提示词，不能把最初输入冒充最终提示词。旧任务可核验的条件较少，以资格返回为准。原片需保持未修改，并满足音轨、24fps、宽高32整除、768P范围和对应帧数要求；只比较素材URL不能证明其内容没变化。再生成成片时长可能被上游向上取整计费，账单可能先保持pending_usage；未核定前预留不是最终消费。

**regeneration**

```
curl https://api.wanapis.com/v1/videos/task_source_example/regenerations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "mode": "source",
  "resolution": "2K"
}'

curl https://api.wanapis.com/v1/videos/task_source_example/regenerations \
  -H "Authorization: Bearer $WANAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "minimax-h3",
  "mode": "content",
  "resolution": "2K",
  "content": [
    {
      "type": "text",
      "text": "Replace with the original final prompt, unchanged"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "asset_id": "asset_original_example"
      }
    }
  ]
}'
```

### 10. 理解预扣、退差与失败

普通费用=[输出秒价×输出秒数＋参考视频秒价×ceil(参考视频总秒数)＋超额图单价×max(图数−5,0)]×长时倍率×优先倍率＋IR固定费，最后整体乘有效分组倍率。16–30秒长时倍率2作用于整段输出与收费素材，fast=true再乘2；IR不随这两项翻倍。参考视频先相加再向上取整：1.2＋1.2秒按3秒收费，不是4秒。提交前按最大可能输入秒数预留（单片最多16计费秒、多片合计15计费秒；具体见报价），成功后按冻结费率和核实用量退差。billing.status=pending_usage时charged_quota仍未知，预留不是最终消费。已受理任务失败全退额度；退款与成功后退差是不同事件。生成完成后改价不改变已冻结报价。

### 11. 再生成与IR的费用另算

再生成是新任务，保留原生成费用，另按输出¥0.078/秒＋原参考视频¥0.078/计费秒＋超过5图部分¥0.052/张收费，最后乘分组倍率。重新收取的是原参考素材，不把原片自身再加成一份参考视频。再生成不继承原任务的长时、优先或IR附加项。独立IR每次¥0.065，只收固定费；前一次IR费用不会自动抵扣后续生成内IR。例：4秒768P、无收费素材、基础分组，生成内IR开启为¥0.533，关闭为¥0.468；4秒原片再生成且无收费参考素材为¥0.312。

### 12. 错误与重试

400通常是字段、数量、冲突或不支持的规格；401/403检查令牌、模型和任务归属；413缩小文件或body；余额不足不会先创建付费任务。POST超时、断线或提示可能受理时，先查已获得的task ID，并保存request ID联系支持，不要盲目重新提交。GET查询遇到临时错误可退避重试。只有确认原任务失败并处理退款后，才决定是否创建新任务；不提供保证取消成功的操作。

## 已知限制

- 本文为扩展协议候选说明，真实付费生成未执行；具体功能开放情况以当前能力、源任务资格与账户有效报价为准。
- 独立提示词优化的响应形式与再生成可用模式需要在实际运行版本中确认；不能把请求成功或离线示例当作最终成片/实际扣费验证。
- 不支持4K、批量n>1、任意视频放大或未经声明的字段；规格档位不保证固定输出像素。
- 素材URL可能过期或内容变化，客户端负责保存原最终提示词与原素材；本平台仅对已保存的条件进行匹配，不承诺验证可变URL的历史字节。

## 常见问题

### 为什么视频已完成，账单还在待结算？

结果状态和费用核定独立。参考视频计量尚缺失或不符合校验时，已预留额度保持pending_usage，不按0或预留上限冒充最终收费。保留任务ID，可继续查询或联系支持。

### 怎么一次知道会预扣多少？

工作区展示确定费用与最高预扣，来源为当前模型价格和服务端输入上界。带参考视频时最高预扣可能高于最终消费，完成核定后退差；缺少费项时不应自行猜价或继续提交。

### 能沿用以前的单图请求吗？

可以。prompt与input_reference的字符串或image_url对象形式保留；四个旧size为1280x720、720x1280、1792x1024、1024x1792。不要与新content混用，不要填写互相矛盾的别名。

### 音频免费、前5张图免费，是整个请求免费吗？

不是。它们只是不额外加收对应素材项，输出视频、参考视频、IR或再生成仍按各自规则收费。

### 为什么其他人的任务ID查不到？

任务、结果和上传素材都按账户归属鉴权；同一字符串不会授予他人访问权。不要将API key或本人任务链接当成公开分享凭证。

---

本文由 WanAPIs 官网生成,和网页版内容同步。全部教程的 Markdown 目录:https://wanapis.com/docs/index.md