视频生成

POST /v1/videos

视频生成是异步任务接口。创建任务后返回任务 ID，通过 GET /v1/videos/{id} 轮询状态。

请求格式

支持两种互斥的输入格式（混用返回 400）。

格式一：平台自有格式

{
  "model": "minimax-video-01",
  "prompt": "A cinematic shot of a sunset over mountains",
  "references": [
    {
      "type": "image",
      "role": "reference_image",
      "url": "https://example.com/image.jpg"
    }
  ],
  "ratio": "16:9",
  "duration": 5
}

格式二：行业同构格式（对齐火山 Ark / MiniMax H3 V2）

{
  "model": "minimax-video-01",
  "content": [
    {
      "type": "text",
      "text": "A cinematic shot of a sunset over mountains"
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg"
      }
    }
  ],
  "aspect_ratio": "16:9",
  "duration": 5
}

参数说明

参数	类型	说明
`model`	string	视频生成模型 ID
`prompt`	string	提示词（格式一必填）
`references[]`	array	参考素材列表（格式一）
`references[].type`	string	素材类型：`image`、`video`、`audio`
`references[].role`	string	角色：`reference_image`、`reference_video`、`reference_audio`、`first_frame`
`references[].url`	string	素材 URL 或 `data_url` 或 `asset_id`
`content[]`	array	行业同构格式（格式二，与 `references` 互斥）
`content[].type`	string	`text`、`image_url`、`video_url`、`audio_url`
`content[].text`	string	文本内容（type=text 时必填）
`content[].image_url/video_url/audio_url`	object	媒体 URL，支持 `{url}` 或 `{asset_id}`
`ratio` / `aspect_ratio`	string	画面比例（互为别名，不同时传 400）
`duration`	integer	目标时长（秒）
`resolution`	string	分辨率
`watermark` / `aigc_watermark`	boolean	水印开关（互为别名，不同时传 400）
`seed`	integer	随机种子
`generate_audio`	boolean	是否生成音频
`return_last_frame`	boolean	是否返回最后一帧
`callback_url`	string	回调 URL（见下方说明）

回调说明

callback_url 支持 MiniMax 式 challenge 验证：

平台向回调 URL 发送 POST {challenge} 请求，要求响应体回显该值。
验证通过后，任务状态变更时推送 GET /v1/videos/{id} 同款资源 JSON。
失败重试最多 5 次，均失败后停止回调。

查询任务状态

curl https://shotject.com/v1/videos/{videoId} \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxx"

任务状态

状态	说明
`queued`	排队中
`running`	生成中
`succeeded`	成功
`failed`	失败
`cancelled`	已取消
`expired`	已过期

响应示例

{
  "id": "video_xxx",
  "object": "video",
  "model": "minimax-video-01",
  "status": "succeeded",
  "duration": 5,
  "ratio": "16:9",
  "aspect_ratio": "16:9",
  "created_at": "2026-08-25T12:00:00Z",
  "completed_at": "2026-08-25T12:05:00Z",
  "content": {
    "video_url": "https://shotject.com/v1/videos/video_xxx/content?token=...",
    "last_frame_url": "https://shotject.com/v1/videos/video_xxx/last-frame?token=..."
  },
  "usage": {
    "completion_tokens": 1500,
    "total_tokens": 2000
  },
  "portal_billing": {
    "billing_mode": "per_second",
    "second_quota": 1000,
    "reserved_duration_seconds": 5,
    "max_billing_quota": 5000,
    "billed_duration_seconds": 5,
    "billed_quota": 5000
  }
}

获取视频内容

curl https://shotject.com/v1/videos/{videoId}/content?token=...
curl https://shotject.com/v1/videos/{videoId}/last-frame?token=...

视频内容通过签名 URL 访问，支持 Range 请求和断点续传。

计费

视频按秒计费（per_second），预占 duration × 每秒单价 的额度，生成完成后按实际时长结算。