iModelSpace 文档

Appearance

视频生成 POST /v1/videos/generations ​

异步视频生成端点。支持文生视频 / 首尾帧 / 多素材参考 / V2V 动作迁移。

端点 ​

POST https://api.imodel.space/v1/videos/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求参数 ​

字段位置类型必传默认范围说明
modelbodystring✅"minimax-h3"—模型代号，固定 "minimax-h3"
promptbodystring✅*—≤ 7000文本提示词，最长 7000 字符（多模态输入上限）；与 image / video 互斥必传一项
durationbodyinteger✅6[4, 15]视频时长（秒），minimax-h3 后端硬约束 [4, 15]（防 duration=0 逃费）
sizebodystring❌——可选，无需传。实际宽×高由 resolution × aspect 算出。传值会被后端忽略（见下方说明）
resolutionbodystring✅—[128, 8192]P 数（minimax-h3 强校验），按 P 查 rates 算费
aspectbodystring✅——画面比例（minimax-h3 强校验白名单）
fpsbodyinteger❌24—帧率
imagebodystring❌——参考图 URL（首尾帧 / 全能参考时必填）
videobodystring❌——参考视频 URL（V2V 动作迁移时必填）
seedbodyinteger❌——随机种子，固定种子可获得确定性生成结果
metadatabodyobject❌——附加元数据；首尾帧填 { "mode": "first_last_frame" }，全能参考填 { "mode": "universal", ... }。参考 metadata.mode 枚举值

请求示例 ​

图像来源（image / video）

image 与 video 字段不是必须使用本平台素材上传——只要是公网可访问的 URL 都行（不限域名）。三种典型来源：

  1. 本平台素材库：API Key 上传 后用返回的 cdn_url —— 自动入库、可在素材管理页查/改/删、跨任务复用
  2. 自有图床：你自己 OSS / S3 / 七牛 / 又拍云 / 自建 nginx 等任何公网可访问的存储
  3. 公共 CDN：Unsplash / 公司 CDN / 图床服务等

只要 URL 返回 200 且能识别扩展名（Content-Type 或 URL 后缀），后端 worker 会直接 GET 拉下来灌给 ComfyUI。私有 bucket 公开 URL 403 会被拒，需要走 CDN 或临时签名 URL。

size 字段（可选，无需传） ​

size 是 OpenAI 协议历史字段（形如 "1280x720"）。minimax-h3 后端完全靠 resolution + aspect 推算实际分辨率（参见 计费元数据 meta.sizes）；size 即使传了也会被忽略,后端不会保存该字段、不影响计费与生成。

建议：所有调用方不要再传 size，保持请求体精简。需要实际 W×H 时改读 GET /v1/models 的 meta.sizes 表。

全能参考（metadata.mode=universal，2026-09-01 新增） ​

图片 / 视频 / 音频混合参考生成。所有参考素材通过 metadata 传入，prompt 用对应标签引用素材。

json
{
  "model": "minimax-h3",
  "prompt": "<Picture 1> 让画面中的角色动起来，配 <Audio 1> 的背景音乐，参考 <Video 1> 的镜头运动",
  "duration": 6,
  "resolution": "768P",
  "aspect": "16:9",
  "metadata": {
    "mode": "universal",
    "ref_image_0": "https://cdn.example.com/character.jpg",
    "ref_image_0_name": "character.jpg",
    "ref_video_0": "https://cdn.example.com/motion.mp4",
    "ref_video_0_name": "motion.mp4",
    "ref_audio_0": "https://cdn.example.com/bgm.mp3",
    "ref_audio_0_name": "bgm.mp3"
  }
}

metadata 键说明：

键说明
ref_image_0 ~ ref_image_8参考图片 URL（≤9 张），ref_image_N_name 为对应原始文件名（可选，推荐传，与 prompt 引用保持一致）
ref_video_0 ~ ref_video_2参考视频 URL（≤3 个），每段 2–15 秒；ref_video_N_name 同上
ref_audio_0 ~ ref_audio_2参考音频 URL（≤3 段），每段 2–15 秒；ref_audio_N_name 同上

prompt 引用标签（按类型各自从 1 编号）：<Picture 1>…<Picture 9>（图片）、<Video 1>…<Video 3>（视频）、<Audio 1>…<Audio 3>（音频）。

数量上限（超限返回 400 minimax_h3_ref_media_overflow）：图片 ≤9、视频 ≤3、音频 ≤3、所有素材总数 ≤12。

枚举值 ​

resolution（P 数） ​

minimax-h3 必传，按 P 查 rates 计费。

值说明
480P480 短边，约 0.5MP
608P608 短边
768P768 短边，约 1MP；推荐档位
832P832 短边

aspect（画面比例） ​

minimax-h3 强校验白名单。

值说明
16:9横屏，主推比例
1:1方屏，社交平台常用
9:16竖屏，短视频平台常用

metadata.mode（模式） ​

minimax-h3 用 metadata.mode 决定加载哪个 UNet 主模型 + 走哪个工作流模板。

值触发条件UNet 主模型工作流适用场景
universal全能参考（metadata 传 ref_image_* / ref_video_* / ref_audio_* 时必传）minimax_h3_ref2va_pruned_int8_convrot.safetensorsminimax_h3_api.json（9 图 + 3 视频 + 3 音频槽位）图片/视频/音频混合参考，prompt 用 <Picture n> / <Video k> / <Audio j> 引用素材
first_last_frame首尾帧生视频（有 metadata.last_frame 时可省略 mode，自动按此模式处理）minimax_h3_fl2va_pruned_int8_convrot.safetensorsminimax_h3_api.json提供首帧 + 尾帧控制视频起止画面
未传 / 其它值—兜底 universalminimax_h3_api.json没指定 mode 且没传 last_frame 时，按 universal 处理（兼容老调用方）

首尾帧模式建议显式传 "first_last_frame"，避免依赖隐式判断。

枚举值的「模式」与 aspect 「比例」是不同维度：mode 控制 UNet + 工作流选择（提交侧维度），aspect 控制画幅比例（渲染侧维度），两者独立组合。

成功响应 ​

HTTP 202

json
{
  "id": "v_7f9c1d3a-1b2c-4d5e-8a9f-0c1d2e3f4a5b",
  "status": "queued",
  "created_at": 1763692800,
  "poll_url": "/v1/tasks/v_7f9c1d3a-1b2c-4d5e-8a9f-0c1d2e3f4a5b"
}
字段类型说明
idstring任务编号（task_no），后续轮询用
statusstring任务状态：queued / scaling / running / succeeded / failed / cancelled / timeout（完整枚举见任务查询）
created_atinteger任务创建时间（Unix 秒）
poll_urlstring轮询路径，模板为 /v1/tasks/{id}

下一步用 id 调 任务查询 GET /v1/tasks/{task_no}。

文档更新记录 ​

日期更新内容
2026-09-15新增错误码 minimax_h3_ref_video_not_allowed(minimax-h3 不支持视频参考素材);核心能力描述移除「3 视频参考」表述
2026-09-05成功响应 status 字段说明补全状态枚举(新增 scaling / timeout),并链接到任务查询页的完整枚举说明

错误码表 ​

4xx — 客户端请求问题 ​

HTTPcode说明解决建议
400invalid_request_error参数错误：检查 prompt（≤7000）/ 素材数（≤9 图 + 3 视频 + 3 音频）对照「请求参数表」逐字段核验必传项与枚举取值
400minimax_h3_resolution_requiredminimax-h3 必传 resolution（P 数，如 720P），用于按档位计费在请求体加 resolution 字段，值从「枚举值 → resolution」取
400minimax_h3_aspect_requiredminimax-h3 必传 aspect（16:9 / 1:1 / 9:16），与 resolution 共同决定实际分辨率在请求体加 aspect 字段，值从「枚举值 → aspect」取
400minimax_h3_resolution_invalidresolution 必须是「数字+P」形式，范围 128-8192如传 480P / 768P / 1080P；避免 720p（小写）/ 0P / 8KP / 720（无后缀）
400minimax_h3_aspect_invalidaspect 仅支持 {16:9, 1:1, 9:16}如传 21:9 / 4:3 会被拒绝，请改用白名单内比例
400minimax_h3_ref_media_overflow全能参考素材数量超限（图片 ≤9 / 音频 ≤3 / 总数 ≤12，minimax-h3 暂不支持视频参考）减少素材数量后重试
400minimax_h3_ref_video_not_allowedminimax-h3 不支持上传参考视频（顶层 video 字段 与 metadata.ref_video_N 均不允许）改用图片（metadata.ref_image_N）或音频（metadata.ref_audio_N）作为参考素材
400media_requiredprompt / image 至少传一项（minimax-h3 不接受视频输入）补传其中之一
400model_requiredmodel 字段必传且非空model 设为 "minimax-h3"
402insufficient_quota账户灵石不足，无法生成在控制台「灵石充值」购买后重试
408timeout生成超时建议拆分多段生成，或降低分辨率至 768P
451content_blocked输入素材涉及版权或敏感词，已被拒绝修改提示词 / 更换参考素材

5xx — 服务端问题 ​

HTTPcode说明解决建议
500internal_error上游服务异常（ComfyUI / 工作流执行失败）稍后重试；持续失败请联系客服并附 task_no
502upstream_unavailable上游 ComfyUI 不可达稍后重试
503gpu_busy当前 GPU 资源排队中，任务稍后会执行无需处理，等待任务进入 running 即可

通用 4xx/5xx 见 错误码总表。

Copyright © imodel.space