H3 V2 直接调用

从自己的服务端直接调用平台，请按本文操作。中转站管理员请阅读 New API 接入教程；逐字段定义见 V2 接口参考。

完成第一次调用

1. 在平台创建 API Key，在自己的服务端设置 JUSP_API_KEY。
2. 从下方四种模式中选一份完整 JSON，保存为 request.json；素材 URL 换成实际公网地址。
3. 使用下面的创建命令，保存 create.json。同一业务重试保持正文和幂等键；新业务换键。
4. 下载 Python 轮询下载脚本，与 create.json 放在同一目录，运行 python3 h3-v2-poll.py。脚本只查询原任务，不创建新任务。

curl --fail-with-body --max-time 120 \
  'https://api.jusuanhub.com/v2/video_generation' \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: your-stable-business-request-id' \
  --data-binary @request.json --output create.json

创建返回 task_id 只代表受理；最终成功、失败与下载方式见 查询、下载与失败处理。本页不会执行请求或保存密钥。

接口与支持范围

本接口是 MiniMax H3 的兼容子集，使用平台 Account API Key。原 V1 媒体接口 保持不变；V2 无需先上传素材获取 assetId。

创建和查询使用 Authorization: Bearer <API_KEY>。模型名为 MiniMax-H3，清晰度仅 768P，时长 duration 为 5–15 秒整数。2K、4 秒、回调、多参考视频和 aigc_watermark: true 不支持。

所有模式统一固定画幅

每个新请求都必须显式填写 ratio，只接受下表六个值。 不传、adaptive、其他比例或自定义宽高都会被拒绝。素材原始尺寸不会改变所选画幅。

比例名称表示平台预设档位，精确像素以表格及查询返回的 width、height 为准。

画幅小提示： 生成视频使用所选固定画幅。建议上传与目标画幅比例一致的图片或参考视频；比例不一致可能造成画面拉伸、压缩、裁剪或构图变化。可在提交前自行裁剪到相同比例；首尾帧建议使用一致的画幅。全能参考用于引导生成，不保证逐像素保留原构图。

用素材角色明确选择模式

content 包含一项 text，以及所需素材项。图片数量不能代替模式选择：一张 first_frame 是图生，一张 reference_image 是全能参考。

不要混合首尾帧角色和全能参考角色。省略图片 role 仅为兼容而默认首帧，两张图片都省略不会自动成为首尾帧。

四种模式的完整请求

以下每份 JSON 均可独立保存为 request.json，使用开头的创建命令。替换示例素材 URL 为你可公开读取的实际地址；示例域名没有可用素材。content 恰好包含一项非空 text，提示词最多 7000 字符。不传不支持的字段，名称和大小写须精确。

文生视频

{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "content": [
    {
      "type": "text",
      "text": "保持场景主体，镜头缓慢推进，动作自然，保留环境声"
    }
  ]
}

图生视频

{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "content": [
    {
      "type": "text",
      "text": "保持场景主体，镜头缓慢推进，动作自然，保留环境声"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://your-public-host.example/first.png"
      }
    }
  ]
}

首尾帧

{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "content": [
    {
      "type": "text",
      "text": "保持场景主体，镜头缓慢推进，动作自然，保留环境声"
    },
    {
      "type": "image_url",
      "role": "first_frame",
      "image_url": {
        "url": "https://your-public-host.example/first.png"
      }
    },
    {
      "type": "image_url",
      "role": "last_frame",
      "image_url": {
        "url": "https://your-public-host.example/last.png"
      }
    }
  ]
}

全能参考

{
  "model": "MiniMax-H3",
  "resolution": "768P",
  "duration": 5,
  "ratio": "16:9",
  "content": [
    {
      "type": "text",
      "text": "保持场景主体，镜头缓慢推进，动作自然，保留环境声"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://your-public-host.example/reference.png"
      }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://your-public-host.example/reference.mp4"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://your-public-host.example/reference.wav"
      }
    }
  ]
}

外部素材与费用

• 素材地址必须是公网 HTTPS、端口 443；不支持内网、回环地址、URL 用户名密码或附加鉴权头。图片另支持 PNG/JPEG/WebP base64 data URL；视频使用 MP4，音频和各角色限制见下表。跳转后的地址同样必须满足公网限制；不接受 URL fragment。
• 无视频最多 9 张图，有视频最多 8 张图；最多 1 个视频、3 段音频，音频总长不超过 15 秒；总引用不超过 12 项，纯音频参考不支持。
• JSON 最多 64 MiB，素材下载总量最多 128 MiB；单次下载最多 30 秒，总下载上下文最多 90 秒。签名 URL 必须在提交摄入期间有效。
• 提示词优化默认开启，与视频分别计费。直接 V2 请求使用 JSON "optimizePrompt": false 关闭，prompt_optimizer 为别名，两者同时提供必须一致。字符串 "false" 无效。
• 素材是临时任务输入，不加入个人素材库。中心输入一小时到期，在途任务保护其字节；执行缓存保留现有终态后 24 小时恢复窗口，随后按清理周期回收。不能承诺所有副本一小时内物理删除。
• 长期记录保留脱敏来源和媒体摘要，不保存完整签名 URL。临时素材清理后不可直接复用；生成视频遵循原结果生命周期，请及时下载。结果 URL 最长成功后七天有效，资产或权限提前失效时同步失效。

各角色素材限制

上述时长和宽高比范围均包含端点；宽高比为素材宽度除以高度，解码像素为宽度乘以高度。首尾帧不套用全能参考的0.4–2.5宽高比限制。参考视频自带音轨不占独立参考音频名额；MOV 按音频身份解析时须有有效音轨，不占参考视频名额。

文件大小与时长是独立限制，必须同时满足。1 MiB = 1,048,576 字节；相同时长的文件会因编码、码率、分辨率不同而大小不同，不能由字节数换算是否满足2–15秒。请求 duration 的5–15秒是生成视频时长，不是参考素材的时长范围。

平台检查文件真实内容，不以扩展名代替格式检测。请求总量和素材数量还须同时满足上文限制；不能把单文件上限简单乘以素材数量。V1 与 V2 使用同一角色素材限制。最新角色规格可从 GET /v1/services 对应 H3 的 mediaSpecContract.inputAssets.roleLimits 查询，按 generationMode 和 role 匹配；这只是发现规格，V2 提交仍使用 URL。

默认优化失败时任务会失败，不自动退回原文生成。已经执行的优化即使失败也可能计费；关闭优化不跳过内容安全审核。优化重试、费用和失败分类见提示词优化教程，其 V1 响应字段不能直接套到 V2。

查询、下载与失败处理

创建后先持久保存 task_id、原请求和幂等键。查询使用原平台 API Key：

TASK_ID=$(jq -er '.task_id' create.json)
curl --fail-with-body --max-time 60 \
  -H "Authorization: Bearer $JUSP_API_KEY" \
  "https://api.jusuanhub.com/v2/query/video_generation/$TASK_ID" --output task.json

成功查询响应示意（用量为示意值）：

{"task":{"id":"job_example","model":"MiniMax-H3","status":"succeeded","created_at":1800000000,"updated_at":1800000060,"resolution":"768P","duration":5,"ratio":"16:9","width":1344,"height":768,"task_type":"generation","modality":"video","content":{"url":"https://api.jusuanhub.com/v2/video_generation/results/asset_example/content?ticket=REDACTED"},"usage":{"input_seconds":0,"input_image_count":0,"output_seconds":5.167,"total_seconds":5.167}}}

任务失败时可能返回 HTTP 200 和 {"task":{"status":"failed","error":{"code":"prompt_optimization_failed","message":"..."}}}；这里省略了其他任务字段。HTTP 请求本身失败则是 {"type":"error","error":{"type":"bad_request_error","code":"unsupported_request","message":"...","http_code":"400"},"request_id":"..."}。

仅成功后下载，URL 已带短期票据，不需要额外 Bearer，也不要把 API Key 转发到下载地址：

# 确认 task.status 为 succeeded 后执行
RESULT_URL=$(jq -er '.task.content.url' task.json)
curl --fail-with-body --max-time 300 "$RESULT_URL" --output result.mp4
# 元信息和断点读取同样使用完整票据 URL
curl --fail-with-body --head "$RESULT_URL"
curl --fail-with-body --range 0-127 "$RESULT_URL" --output first-128-bytes.bin

下载 URL 是敏感凭证，不写入公开日志。票据绑定原 API Key 的状态、权限和结果资产；Key 撤销或资产失效会让 URL 提前失效。过期后不能靠重新查询无限延长有效期。

可下载完整 Python 轮询下载示例，放在 create.json 同目录，安全提供 JUSP_API_KEY 后运行 python3 h3-v2-poll.py。脚本最多等待30分钟，对少量临时读取错误退避，下载预算1 GiB；从不提交新任务。等待结束后重跑脚本继续原任务即可。V1 的 jobUrl、outputs[] 和鉴权下载教程不适用于此响应。

成功 usage.input_seconds 为参考视频时长，input_image_count 为输入图片数；output_seconds 为探测的实际产物时长，可能与请求 duration 略有差异；total_seconds 为参考视频与产物时长之和，不包含参考音频。它们不是金额，优化用量也不包含在其中；平台费用以实际账单为准，中转站另行配置零售计费。

New API 配置与请求示例

中转站接入已独立整理到 New API 接入教程，包含渠道配置、四种完整请求和专用轮询下载脚本。平台 V2 与 New API 的令牌、查询状态和下载鉴权不同，请勿混用。

接口字段见 V2 创建参考、V2 查询参考及 完整 OpenAPI。

已接受历史任务

已接受的旧 adaptive 任务继续使用原冻结画布，查询、下载和同键同请求重放保持可用；不会重新下载素材、改尺寸或重新生成。新请求适用六档规则。同一固定任务更换 ratio 必须使用新的业务幂等键；旧键修改参数会冲突。