视频总览

视频生成是异步任务：提交后拿到任务 ID，轮询到完成，再在有效期内下载成片。

# 1. 提交任务，记下返回的 task.id（形如 vt…）
curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-5-260628",
    "content": [
      {
        "type": "text",
        "text": "一只橘猫在阳光下的草地上奔跑，镜头跟随"
      }
    ]
  }'

# 2. 每 5 秒查询一次，直到 task.status 为 completed
#    成片地址在 task.outputs
curl https://api.hop-base.com/v1/video/tasks/vt你的任务ID \
  -H "Authorization: Bearer sk-你的密钥"

选择系列

HopBase 在售六个视频模型系列，都走下方同一套异步流程：提交 → 轮询 → 下载。

官方价列是该系列最低的一档起价，完整分档见各系列页与模型卡；可灵对口型等特殊模式另行计价。实际单价以登录后的模型广场为准。

模型 ID 与分组

每个系列属于不同的分组，请用包含该分组的密钥调用。

可灵另有动作控制、数字人与对口型型号，见可灵页。各系列的最小请求与结果位置如下：

MiniMax 纯文生视频另需 ratio。可灵的特殊模式见可灵页。Seedance 的 content[] 常用 text 与 image_url 元素。

任务流程：提交 → 轮询 → 下载

所有视频模型都按这三步调用。

提交

HopBase 按请求的 model 与密钥所含分组交给对应系列处理。请求体与状态值各系列不同，以各自文档为准。各系列提交成功的状态码不同，客户端以 2xx 判断提交成功。

密钥只能调通它所含分组对应的系列，一把密钥可以包含多个视频分组。请用实际要使用的密钥调 GET /v1/models，从返回结果里取完整模型 ID。模型 ID 精确匹配，写错会被直接拒绝，不会就近路由。

轮询

用提交返回的任务 ID 查询状态，直到任务成功或失败。Seedance、Grok Imagine、MiniMax 与可灵还有任务列表：

GET /v1/video/tasks?page=1&limit=20

万相与快乐马没有列表接口，任务 ID 需要自行留存。

下载

成片地址是 api.hop-base.com 域名下的签名地址，有效期自任务完成起计算：

再次查询返回同一地址、不会续期，过期访问返回 410。请及时下载保存。

余额与计费

提交视频任务时按「可用余额 − 进行中任务的预估费用 − 本次预估费用」判断。不足返回 402，code 为 insufficient_balance。任务结束后预估自动释放。

Insufficient balance: available $X, reserved in flight $Y, this request estimated $Z
Insufficient quota: …    # 设有额度的企业成员额度不足时，message 以此开头

可灵对口型无法预估，不做预留。

失败的视频任务一律不计费。任务结束后，单任务查询响应的根对象还会带 usage：

失败且未扣费的任务为 0。任务进行中不返回该字段，且单查时只对创建任务的那把密钥返回；示例中的金额仅作示意。任务列表（不带任务 ID 的 GET /v1/video/tasks）里每个终态任务的 usage 也带同样的 cost、cost_usd 与 currency，列表按账户列出，同一账户其他密钥创建的任务同样带金额。

官方牌价见价格页。你的实际单价以登录后的模型广场为准，每次请求的实际扣费见控制台「使用记录」。

失败、超时与取消

提交返回 2xx 只表示已受理。生成失败时查询仍返回 HTTP 200，状态为失败，原因是英文说明，没有稳定的错误码。

Seedance 读 task.error.message，其他系列见各自页面。控制台「使用记录」会显示失败分类与处理建议，详见错误说明。

进行中任务的超时上限各系列不同，见各自页面。Seedance 任务创建超过 24 小时仍未结束会被自动判为失败，message 为：

The task did not finish within 24 hours and was terminated automatically

视频任务不支持取消。

参考素材对比

各模型接受的参考素材数量：

• Seedance 首尾帧最多 2 图；2.0 的首尾帧不能混参考模式。
• MiniMax-H3 的首尾帧与参考模式互斥；H3-Max 不接受任何 reference_*。
• 万相 3.0 的文档、网页各 ≤1 且互斥，首尾帧与参考组互斥。
• 可灵的 usage 与特殊模式逐型号见可灵页。
• Grok Imagine 的 content 只放 text。

各模型接受的编码形式：

Seedance 2.0 上传素材库的 URL 仅支持 HTTP(S)。MiniMax-H3-Max 不能借 Data URL 绕过参考类型限制。快乐马不支持视频/音频参考。

Data URL 是 data:媒体MIME;base64,编码内容，不能只给裸 base64。

下一步

• Seedance：Seedance 2.0 / 2.5 参数、返回结果与报错
• 可灵：可灵视频参数与任务模式
• API 参考：提交视频任务：各系列完整请求字段
• 并发、超时与计费：并发上限、超时与计费规则
• 错误码与重试：各错误码的含义以及是否该重试