MiniMax H3 Max API 教程：文生视频与图生视频接入

本文先给出完成首次成功请求的最短路径，再补齐生产环境所需的参数校验、轮询、回调、存储和回退设计。H3 Max 专属文档页发布前，请在模型页核对实时路由契约和精确字段。

先创建 EvoLink API Key，在 MiniMax H3 Max 模型页查看实时估价。如果工作流可能需要 2K 或广泛参考素材，同时查看 H3 Max vs H3 指南。

接入前准备

首次请求前确认以下条件：

选择正确的 H3 Max 模型 ID

第一步：发起文生视频请求

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-text-to-video",
    "prompt": "一双高端跑鞋在干净的摄影棚展台上缓慢旋转，柔和日光划过织物表面。镜头缓慢推进，材质真实，不添加文字或额外 Logo。",
    "duration": 5,
    "quality": "768p",
    "aspect_ratio": "16:9"
  }'

主要 T2V 参数如下：

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "video"
}

第二步：发起首尾帧图生视频请求

curl --request POST \
  --url https://api.evolink.ai/v1/videos/generations \
  --header "Authorization: Bearer $EVOLINK_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "minimax-h3-max-image-to-video",
    "prompt": "镜头缓慢环绕半圈，包装盒打开，产品平稳升起。保持包装形状、颜色和光线一致，最终准确落在给定尾帧构图。",
    "image_start": "https://cdn.example.com/h3-max/start.webp",
    "image_end": "https://cdn.example.com/h3-max/end.webp",
    "duration": 8,
    "quality": "768p"
  }'

每张图片必须使用可直接访问的 HTTP(S) URL，并符合当前契约：

• JPG、JPEG、PNG、WEBP、HEIC 或 HEIF。
• 单张图片不超过 30 MB。
• 宽和高均为 256–5,760 像素。
• 宽高比为 0.4–2.5。
• 首帧最多一张，尾帧最多一张。
• 完整 JSON 请求体不超过 64 MB；不支持 Base64 和 mm_file://。

第三步：轮询任务状态

使用同一 Bearer Token 查询任务：

curl --request GET \
  --url "https://api.evolink.ai/v1/tasks/task-unified-1774857405-abc123" \
  --header "Authorization: Bearer $EVOLINK_API_KEY"

{
  "id": "task-unified-1774857405-abc123",
  "model": "minimax-h3-max-text-to-video",
  "object": "video.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://files.example.com/generated-video.mp4"],
  "type": "video"
}

轮询应使用有上限、带随机抖动的指数退避，而不是持续高频请求。例如从约 2 秒开始，逐渐增加到 10–15 秒，在应用定义的截止时间后暂停，并允许后续 Worker 使用已保存的任务 ID 恢复查询。H3 Max 契约不提供取消能力，因此客户端超时并不代表上游任务已被取消。

第四步：生产环境增加回调

{
  "model": "minimax-h3-max-text-to-video",
  "prompt": "一段电影感俯拍镜头，同一城市街区从清晨过渡到夜晚。",
  "duration": 5,
  "quality": "768p",
  "aspect_ratio": "16:9",
  "callback_url": "https://api.example.com/webhooks/evolink/video"
}

EvoLink 当前契约要求 HTTPS，禁止私网 IP，等待响应上限为 10 秒，失败后最多重试 3 次。回调处理器应：

1. 使用应用配置的验证机制校验请求。
2. 将任务 ID 作为幂等键。
3. 尽快返回 2xx。
4. 把下载和重型后处理交给队列。
5. 必要时在向客户最终交付前，用任务查询接口再次对账。

同时保留轮询作为恢复路径。Webhook 可能延迟、被网络策略拒绝，或被应用基础设施重复处理。

提交前校验请求

按错误类型处理

需要把 HTTP 错误与异步任务失败分开处理：创建调用可能成功，但生成任务之后仍会失败。日志应记录任务 ID、路由、输入类型、时长、画质、最终状态、错误码、重试次数和回退结果，同时避免记录密钥或敏感素材 URL。

完成生产交接

保存业务任务与上游任务的关系

提交前先创建自己的业务 Job ID，再保存 EvoLink 任务 ID、模型 ID、标准化参数、客户或工作区 ID、时间戳和交付状态。这样即使 Worker 重启，也能恢复重试、审计和支持流程。

及时下载完成结果

H3 Max 结果 URL 保留 24 小时。把验收通过的视频复制到长期存储，并记录校验值或对象 Key。不要把临时结果 URL 直接作为永久客户资产。

明确区分轮询重试和重新生成

轮询超时不能触发新的生成任务。先查询已经保存的任务 ID；只有原任务进入终态失败，而且重试策略允许时，才创建新的计费尝试。

调用前路由不兼容任务

评测可用输出

至少追踪：

• 任务成功率和完成延迟；
• 首次通过率与重试率；
• 每条验收通过视频的成本；
• 提示词、身份和关键帧遵循；
• 内容审核与无效请求比例；
• 回退频率与恢复成功率；
• 结果 URL 到期前的下载完成率。

常见接入错误

上线前检查清单

1. API Key 只保存在服务端，并且可以轮换。
2. T2V 与 I2V 使用不同校验 Schema。
3. 本地校验时长、画质、宽高比和图片限制。
4. Worker 退出前持久化创建响应中的 id。
5. 轮询使用有上限的退避策略，并支持恢复。
6. 回调处理具备幂等性，同时保留轮询。
7. 在 24 小时内复制完成的 MP4。
8. 日志区分请求错误、任务失败和人工审核拒绝。
9. 价格来自当前模型页或价格服务，不硬编码博客数值。
10. 针对不兼容或失败任务测试 H3 和一条独立回退。

常见问题

EvoLink 上的 MiniMax H3 Max 使用什么接口？

应该使用哪个模型 ID？

H3 Max API 是同步接口吗？

可以生成 4 秒 H3 Max 视频吗？

不可以。支持时长为 5–15 秒内的整数。EvoLink 上支持 4 秒下限的是 MiniMax H3，而不是 H3 Max。

可以只传尾帧吗？

可以。图生视频模型支持只传首帧、只传尾帧和同时传首尾帧。

可以传 Base64 图片吗？

图生视频需要传宽高比吗？

不要传。输出会跟随输入帧比例，应按计划交付的格式准备源图片。

结果 URL 可以保存多久？

24 小时。交付流程应把完成后的 MP4 复制到长期存储。

当前价格在哪里查看？

查看 H3 Max 产品页的实时价格区块和估价器，不要把博客里的固定单价写进生产预算。

API 文档与核验范围

• EvoLink MiniMax H3 Max 模型页与实时路由契约
• EvoLink 异步任务状态文档
• MiniMax 官方视频生成 V2 文档