H3 · New API 中转站接入

配置 Hailuo 任务插件渠道，使用客户令牌完成创建、轮询与视频下载。

本文面向 New API 中转站管理员。New API 是由你部署的接口转发和计费服务；平台 H3 是其上游。无需 New API 的开发者请使用平台 V2 直接调用。

分清两段调用

调用方向	地址	使用的密钥
New API → 平台 H3	`https://api.jusuanhub.com`	平台 Account API Key，仅填渠道上游配置
客户程序 → 你的 New API	你的站点地址	该 New API 站点发给客户的令牌

不要把平台 Key 发给中转站客户。 下文所有客户请求均发往自己的 New API 站点，不能把 /v1/tasks/hailuo 拼到平台地址。

已验证官方 New API 源码版本 1d4328e97417a043a161a0dd30a5b129be3ace49 的 Hailuo 插件 1.2.0。使用 Task Plugin（任务插件，渠道类型61） 并选择 hailuo；不要将旧版内置海螺渠道与任务插件混用。基础地址填 https://api.jusuanhub.com，不要追加 /v1；Key 填平台 Account API Key，模型映射使用 MiniMax-H3。客户其他版本或分支需另行核对。

接入顺序：

在支持任务插件的 New API 版本中加载并启用官方 hailuo 插件，新增任务插件渠道；插件设置对应 task_plugin_key: "hailuo"。
填写上述基础地址和平台 Key，添加模型 MiniMax-H3，并将渠道分组与客户令牌可用分组对齐。
在该版本的模型计费配置中为 MiniMax-H3 / hailuo 配置零售价格或计费表达式，并确保客户账户有额度。不要将测试费率或平台账单金额直接当作你的零售价格。
用 New API 客户令牌向下述任务接口提交，再通过 New API 查询和下载。UI 名称随版本变化，缺少任务插件入口的版本不能照此接入。

必须显式提供 metadata.ratio。 该插件遇到视觉素材且未指定比例时会自动发送 adaptive，平台会拒绝这个新请求。插件已有固定比例透传能力。

插件能力边界

能力	官方 Hailuo 1.2.0
四种视频模式、外部 URL 素材	支持，按下文明确传递素材角色
六档固定画幅	支持；必须填写 `metadata.ratio`
提示词优化	默认开启、单独计费；不透传关闭开关
稳定的上游幂等键	默认不透传；New API 任务 ID 不能替代平台幂等键

需要关闭优化时，须由接入方适配插件透传，不能仅在客户 JSON 添加 optimizePrompt: false 就认为已生效。创建超时或结果未知时，先核对原任务；不要自动重新提交或切换渠道，避免重复生成与计费。

四种模式的客户请求

每份 JSON 可独立保存为 newapi-request.json。模型固定 MiniMax-H3，清晰度 768P，时长5–15秒整数；比例为 21:9、16:9、4:3、1:1、3:4、9:16。

素材必须使用有效的公网 HTTPS URL。示例域名没有实际素材；格式、数量、大小和临时存储规则统一见平台素材限制，单文件时长、尺寸和宽高比见各角色素材限制，精确输出尺寸见画幅表。参考视频的2–15秒与输出的5–15秒须分别校验；文件字节数不能换算为秒数。

文生视频

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

图生视频

{
  "model": "MiniMax-H3",
  "prompt": "保持主体，镜头缓慢推进，动作自然，保留环境声",
  "duration": 5,
  "metadata": {
    "resolution": "768P",
    "ratio": "16:9",
    "first_frame_image": "https://your-public-host.example/first.png"
  }
}

首尾帧

{
  "model": "MiniMax-H3",
  "prompt": "保持主体，镜头缓慢推进，动作自然，保留环境声",
  "duration": 5,
  "metadata": {
    "resolution": "768P",
    "ratio": "16:9",
    "first_frame_image": "https://your-public-host.example/first.png",
    "last_frame_image": "https://your-public-host.example/last.png"
  }
}

全能参考

{
  "model": "MiniMax-H3",
  "prompt": "保持主体，镜头缓慢推进，动作自然，保留环境声",
  "duration": 5,
  "metadata": {
    "resolution": "768P",
    "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"
        }
      }
    ]
  }
}

全能参考中删除不使用的素材项，至少保留一项视觉素材；不要将首尾帧字段与 metadata.content 的参考角色混用。图片数量不决定模式，素材角色才决定模式。

创建、轮询与下载

在服务端安全设置 NEW_API_ORIGIN（你的站点基础地址，不带 /v1）和 NEW_API_TOKEN（客户令牌），不要把令牌写入文件或公开日志。

curl --fail-with-body --max-time 120 "$NEW_API_ORIGIN/v1/tasks/hailuo" \
  -H "Authorization: Bearer $NEW_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @newapi-request.json --output newapi-create.json

保存返回的 New API task_id。下载 New API 专用 Python 轮询下载脚本，与 newapi-create.json 放在同一目录，运行 python3 h3-newapi-poll.py。需要 Python 3；无需额外依赖。脚本最多等待30分钟，限制连续读取重试，下载预算1 GiB；只读取原任务，绝不重新创建。

操作	New API 客户接口	鉴权
查询	`GET /v1/tasks/{task_id}`	客户令牌 Bearer
列出产物	`GET /v1/tasks/{task_id}/artifacts`	客户令牌 Bearer
下载视频	`GET /v1/tasks/{task_id}/artifacts/video/content`	客户令牌 Bearer

查询状态与恢复

顶层 `status`	客户端处理
`NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`	继续查询同一任务，建议间隔5秒并限制总等待时间
`SUCCESS`	下载视频；检查文件实际画幅和时长
`FAILURE`	停止轮询，检查 `fail_reason`；不自动重新付费生成
未知状态	停止并核对版本，不能当作成功

New API 查询示意：

{"task_id":"task_example","status":"SUCCESS","progress":"100%","fail_reason":""}

平台 V2 的 task.status、小写状态和票据下载规则不适用于上述客户接口。客户下载必须携带 New API 令牌。不要把上游任务 ID 替换成 New API 任务 ID，反之亦然。

401/403先检查客户令牌与分组，404检查任务归属和版本，余额不足时检查客户额度与零售计费。查询429/502/503/504可有界退避；创建失败或超时先区分未受理与结果未知。脚本等待结束不代表任务已取消，重新运行脚本会继续查询原任务。

接入验收清单

渠道能识别 MiniMax-H3，模型、分组、客户额度与零售计费配置正确。
用一份请求完成创建 → 查询 SUCCESS → 携带客户令牌下载；保存原任务 ID。
核对实际视频尺寸符合所选画幅，并检查声音和画面。需要其他模式时分别替换素材验证。
确认默认优化与视频分别计费；未知提交结果不会触发自动换渠道重试。

平台逐字段定义见 V2 接口参考。该参考描述上游平台接口，不是 New API 客户协议。