MiniMax 图生视频（i2v）

概览

MiniMax Image to Video（minimax_i2v）能把一张参考图变成一段由文本 prompt 驱动的短视频——运镜、动作、风格都由 prompt 描述。与 Music Video 流水线不同，这是单次调用：立即拿到一个 task_id，大约一分钟内视频就能就绪。

基础配置

配置项	值
Base URL	https://api.foxaihub.com/api/v2
鉴权头	api-key: YOUR_API_KEY
task_type	minimax_i2v

Warning: 请求头名字是 api-key，不是 api_key。任何余额大于 $0 的账户都能提交——不像 Music Video 流水线那样有单独的最低余额门槛。

接口一览

接口	用途
POST /aigc/task	提交一个图生视频任务
POST /aigc/task/wait	提交任务并阻塞等待，直到任务结束或超时
GET /aigc/task?ids=	读取一个或多个任务的状态与结果

---

参数与约束

所有参数都放在建单请求的 params 对象里。每一项都会在扣费之前完成校验——传值不合法会返回 400，且不会扣费。

字段	类型	必填	约束
image	string（URL）	是	必须是可公开下载的 http(s) URL——这里不接受 base64，与 Music Video API 不同
last_frame_image	string（URL）	否	可选的尾帧：可公开下载的 http(s) URL，同样不接受 base64。传了就是首尾帧一起生成，不传就和过去一样只按首帧生成
prompt	string	是	描述你想要的运镜、动作或风格
resolution	string	是	"768p" 或 "1080p"
aspect_ratio	string	是	"1:1"、"4:3"、"3:4"、"16:9"、"9:16" 之一
duration	integer（秒）	是	3–15

Note: 实际生成像素由 resolution + aspect_ratio 在服务端查表换算得到，不是你直接传的数字——同一个组合任何时候都会得到完全相同的尺寸。768p 下：1:1 是 768×768，4:3 是 1024×768，3:4 是 768×1024，16:9 是 1344×768，9:16 是 768×1344；1080p 下对应尺寸整体等比放大到 1:1 = 1088×1088，4:3 = 1440×1088，3:4 = 1088×1440，16:9 = 1920×1088，9:16 = 1088×1920。所有尺寸都已经是 32 的倍数，不需要你自己对齐。

尾帧：让生成的片段收在指定画面上

不传 last_frame_image 时行为和过去完全一样：只用 image 当首帧，运镜和收尾画面完全交给 prompt 描述。传了之后，模型会尝试让视频从 image 过渡到 last_frame_image 指定的画面——适合「开场是这张图，结尾定格在那张图」这种有明确落点的镜头。

• last_frame_image 只对 minimax_i2v 生效；lip-sync（minimax_ia2v）和 LTX（ltx_i2v）目前都不支持，传了会被直接忽略。
• 尾帧图和首帧图一样会被裁剪缩放到最终的生成尺寸，构图差异太大的两张图容易在中间过渡处出现不自然的形变。
• 不额外计费：价格仍然只看 resolution 和 duration，传不传尾帧不影响这次任务扣多少钱。

为什么时长必须是整数秒

生成按每秒 24 帧运行，帧数计算公式是 duration × 24 + 1。小数时长会让模型的时间维度对不齐，所以只接受 3 到 15 之间的整数。

---

API 参考

POST /aigc/task

提交一个图生视频任务。提交时立即扣费。

Parameters

Field	Type	Required	Notes
task_type	string	Yes	必须是 "minimax_i2v"
params.image	string（URL）	Yes	可公开下载的 http(s) URL
params.last_frame_image	string（URL）	No	可选的尾帧，可公开下载的 http(s) URL
params.prompt	string	Yes	运镜 / 动作 / 风格
params.resolution	string	Yes	"768p" 或 "1080p"
params.aspect_ratio	string	Yes	"1:1" / "4:3" / "3:4" / "16:9" / "9:16"
params.duration	integer	Yes	3-15 秒

Request Body

{
  "task_type": "minimax_i2v",
  "params": {
    "image": "https://example.com/ref.jpg",
    "prompt": "电影感推镜，缓缓推向主体",
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}

Response

{ "success": true, "task_id": "a42e2c77-ded8-48aa-8aa4-dfd9daa43801" }

Errors

Status	When	Body
400	某个参数校验失败（resolution/aspect_ratio 不在允许范围、时长超范围、image 不是 URL）	{"success":false,"error":"Invalid params for minimax_i2v: resolution: Invalid enum value"}
400	task_type 未知或已禁用	{"success":false,"error":"Unsupported task type: minimax_i2v"}
401	api-key 缺失/无效，或余额为 0	{"message":"Unauthorized"}
402	扣费本身失败（余额不足）	{"success":false,"error":"Insufficient balance"}
500	该 task_type 的定价配置无效	{"success":false,"error":"Invalid price configuration for task type: minimax_i2v"}

POST /aigc/task/wait

与 POST /aigc/task 相同，但会阻塞 HTTP 响应，直到任务到达终态或 wait_timeout 到期。适合不想自己轮询的脚本。

Parameters

Field	Type	Required	Notes
task_type	string	Yes	"minimax_i2v"
params	object	Yes	与上面相同的结构
wait_timeout	integer（秒）	No	1-600，默认 60

Request Body

{
  "task_type": "minimax_i2v",
  "params": {
    "image": "https://example.com/ref.jpg",
    "prompt": "电影感推镜，缓缓推向主体",
    "resolution": "768p",
    "aspect_ratio": "16:9",
    "duration": 5
  },
  "wait_timeout": 120
}

Response

任务到达 completed 或 failed 后，返回完整的任务对象（与 GET /aigc/task 的形状相同）。

Errors

Status	When	Body
408	wait_timeout 到期时任务仍在运行	{"success":false,"task_id":"...","status":"processing","message":"Task wait timeout after 60s"}
400 / 401 / 402 / 500	与 POST /aigc/task 相同	见上表

GET /aigc/task?ids=

按 id 读取一个或多个任务。免费。响应是一个裸数组，不是对象。

Parameters

Field	Type	Required	Notes
ids	string	Yes	逗号分隔的 task id，一次最多 25 个

Response

[ { "task_id": "...", "task_type": "minimax_i2v", "status": "completed", "params": {...}, "data": ["https://cdn.../result.mp4"], "created_at": "...", "queue_time_sec": 3, "generation_time_sec": 41 } ]

Errors

Status	When	Body
400	ids 缺失，或请求的 id 数超过 25 个	{"error":"Task IDs required"}
401	api-key 缺失或无效	{"message":"Unauthorized"}

---

Webhook

追踪视频任务进度有两种方式：通过 GET /aigc/task?ids= 轮询（或短脚本使用 POST /aigc/task/wait），或者配置 Webhook。在生产环境中我们推荐使用 Webhook——当任务完成或失败时，服务器会自动向你的接口推送通知，无需长连接或高频轮询。

Note: Webhook 在 Dashboard 控制台配置（每个账户对应一个接收地址），配置完成后，所有 AIGC 任务（包括 minimax_i2v 和 minimax_ia2v）在终态时都会自动推送到该地址，直接在你的服务器上接收处理即可。

投递格式

每次投递都是一次带有标准外层的 POST 请求：

{
  "event": "task.completed",
  "type": "minimax_i2v",
  "delivery_id": "9f2c1a3e-abcd-4d11-8f00-0123456789ab",
  "created_at": "2026-08-26T09:31:02.000Z",
  "data": {
    "task_id": "a42e2c77-ded8-48aa-8aa4-dfd9daa43801",
    "task_type": "minimax_i2v",
    "status": "completed",
    "params": {
      "image": "https://example.com/ref.jpg",
      "prompt": "a cinematic dolly shot",
      "resolution": "768p",
      "aspect_ratio": "16:9",
      "duration": 5
    },
    "data": ["https://cdn.../result.mp4"],
    "created_at": "2026-08-26T09:30:10.000Z",
    "queue_time_sec": 3,
    "generation_time_sec": 41
  }
}

请求头	值
Content-Type	application/json
User-Agent	FoxAI-Webhook/1
X-Webhook-Event	与 body 中的 event 一致（task.completed 或 task.failed）
X-Webhook-Type	与 body 中的 type 一致
X-Webhook-Delivery	与 body 中的 delivery_id 一致
X-Webhook-Timestamp	投递时的 Unix 时间戳（秒）

结果类型

一个地址会收到账户下所有业务的推送，所以 event 表示发生了什么，type 表示这是哪种结果。type 与建单时传入的 task_type 完全一致，可以直接用它来分发处理逻辑：

type	结果类型
minimax_i2v	图生视频任务到达终态
minimax_ia2v	对口型视频（图片 + 音频）任务到达终态
asr-serverless	音乐转写任务到达终态
mv	音乐视频流水线事件
ping	在 Dashboard 触发的测试投递

事件列表

Webhook 事件	触发条件	data 包含内容
task.completed	任务成功生成	完整任务对象，data 数组中包含视频 URL
task.failed	任务生成失败（已自动全额退款）	包含失败原因的任务对象

重试策略

• 每次尝试超时时间为 10 秒。
• 分别在 5 秒、10 秒、20 秒后重试——最多总共 4 次尝试，在约 35 秒内收敛。
• 仅在网络错误、超时、HTTP 408、429 与 5xx 时重试。其余 4xx 状态码不会重试。
• 同一条投递在多次重试中保持相同的 X-Webhook-Delivery（即 delivery_id）——可用作幂等去重。

安全性建议

Warning: 建议在 Webhook URL 中携带一段较长的随机路径或 token 参数。在处理关键业务逻辑时，收到 Webhook 后建议调用 GET /aigc/task?ids= 进行二次确认。

---

限制与生命周期

任务生命周期

任务只有四种状态，并且只会单向推进：

pending -> processing -> completed
                       -> failed

状态	含义
pending	已接受，等待 GPU worker 领取
processing	worker 正在运行生成
completed	data 里是结果——一个数组，第一项就是视频 URL
failed	出了点问题；扣的钱已自动退回

没有固定的 SLA，但正常负载下任务通常在一分钟以内就能完成。队列繁忙，或者 GPU 从零冷启动扩容，都会延长这个时间——请用 GET /aigc/task?ids= 轮询，或用 POST /aigc/task/wait，而不要假设一个固定耗时。

排队耗时与生成耗时

任务对象里带两个耗时字段，单位都是秒：queue_time_sec 是建单（created_at）到第一次被 worker 领取（进入 processing）之间的时长，也就是排了多久队；generation_time_sec 是从第一次被领取到到达 completed/failed 之间的时长，也就是真正生成花了多久。在对应节点还没发生之前都是 null——比如任务还在 pending 时两个都是 null，进了 processing 之后 generation_time_sec 仍然是 null，直到终态才会有值。

Note: minimax_i2v 内部其实是两段式流水线（先出草稿 latent，再 refine 成片，中间会经过一个不对外暴露的 streaming 中间态）。generation_time_sec 覆盖的是从第一次被领取到最终完成/失败的全程，包含中间的交接等待，不会因为分两段跑而变成两个数字或漏掉某一段。

重试与超时

领取了任务却停止响应的 worker 会被回收并重试，最多总共 3 次。如果所有尝试都用完，任务会被标记为 failed 并退款——你不需要自己实现超时和退款逻辑。

任务可见性

Warning: GET /aigc/task 不校验归属——任何持有合法 api-key 的人，只要知道 task_id 就能读取它的状态和结果。如果 prompt 或结果内容比较敏感，请把 task_id 当作半私密信息，不要把它暴露在公开链接里。

用 webhook 代替轮询

详见上方的「Webhook 通知」一节获取完整配置接口、投递格式与重试策略。

---

推荐客户端数据库结构

如果你在自己的后端（如 MySQL / PostgreSQL）持久化任务状态，以下是推荐的表结构定义：

任务表（Tasks Table）

CREATE TABLE aigc_tasks (
  task_id CHAR(36) NOT NULL PRIMARY KEY,
  task_type VARCHAR(32) NOT NULL,
  status VARCHAR(20) NOT NULL,
  params JSON NOT NULL,
  data JSON NULL,
  created_at DATETIME(3) NULL,
  synced_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
  CONSTRAINT chk_aigc_tasks_status CHECK (status IN ('pending', 'processing', 'completed', 'failed'))
) ENGINE=InnoDB;

CREATE INDEX idx_aigc_tasks_status ON aigc_tasks (status);
CREATE INDEX idx_aigc_tasks_task_type ON aigc_tasks (task_type);

Webhook 幂等去重表

搭配 INSERT IGNORE 或 ON DUPLICATE KEY UPDATE 使用，确保同一条 Webhook 投递不会被重复消费：

CREATE TABLE webhook_deliveries (
  delivery_id CHAR(36) NOT NULL PRIMARY KEY,
  task_id CHAR(36) NULL,
  event VARCHAR(64) NOT NULL,
  payload JSON NOT NULL,
  received_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
) ENGINE=InnoDB;

CREATE INDEX idx_webhook_deliveries_task_id ON webhook_deliveries (task_id);

同步策略

• 在 POST /aigc/task 返回 task_id 后立即向 aigc_tasks 写入一条记录。
• 当收到 Webhook 推送或轮询拉取到最新状态时，根据 task_id 执行 upsert 更新状态与结果。
• 当 status 变为 completed 时，从 data 数组第一项提取视频 URL 供业务端使用。

计费规则

minimax_i2v 按分辨率档位和秒数计费——建单时立即扣款。如果任务失败或超时，扣的钱会自动全额退回。

计费公式

price = unit_price_by_resolution[resolution] x duration

resolution	每秒单价	含义
768p	$0.025	768p 档位的每秒单价，也是实际的最低消费（duration 最小是 3 秒，即 $0.075）
1080p	$0.05	1080p 档位的每秒单价，不随 aspect_ratio 变化

算价示例

resolution	aspect_ratio	时长	计算	价格
768p	16:9（横屏）	5秒	$0.025 x 5	$0.125
768p	9:16（竖屏）	3秒（最短）	$0.025 x 3	$0.075
1080p	16:9（横屏）	15秒（最长）	$0.05 x 15	$0.75

失败会怎样

• 扣费发生在 worker 开始处理之前，也就是提交的那一刻。
• 如果任务最终状态是 failed，扣的钱会自动全额退回——你这边不需要做任何操作。
• 无响应的 worker 最多会被重试 3 次；如果所有尝试都用完，任务会被标记为 failed 并按同样方式退款。