万相 / 快乐马：视频生成 API

万相 3.0 与快乐马 1.1 按官方原始路径提交异步视频任务，轮询 HopBase 任务 ID 拿到成片。

HopBase 按官方接口格式提供万相与快乐马视频生成,并且保持原始路径。用官方 SDK 或 HTTP 写好的代码迁过来只需改 base URL 和密钥——请求体、响应结构、路径都不用动。

可用型号

万相 3.0 的时长也可以传 -1 表示自动。它的参考组最多 10 张参考图、5 段参考视频、5 段参考音频、1 个文档、1 个网页链接。

请使用上表中的精确 ID。未登记任何别名,未知模型名会被拒绝。wan3.0-video-prime、happyhorse-1.1-video-edit 以及快乐马 1.0 系列均未上架。

wan3.0-video 与 happyhorse-1.1-* 分属两个分组——万相 3.0 官方直连与快乐马 1.1 官方直连,密钥包含某个模型所在的分组才能调到它，一把密钥可以同时包含这两个分组。请在正式付费调用前用 GET /v1/models 确认密钥能调用哪些模型。

分档价与完整规格见模型卡:wan3.0-video、happyhorse-1.1-t2v、happyhorse-1.1-i2v、happyhorse-1.1-r2v。

请求参数

所有请求使用 Authorization: Bearer sk-your-key 与 Content-Type: application/json。你不需要额外发送异步请求头,任务始终异步执行。

{
  "model": "wan3.0-video",
  "input": { "prompt": "...", "media": [{ "type": "first_frame", "url": "..." }] },
  "parameters": { "resolution": "1080P", "duration": 5 }
}

快乐马的中文 prompt 在 2,501-5,000 字之间不报错,但会被截断到约 2,500 字。

input.media

file 接受的格式:docx / doc / xlsx / xls / pptx / ppt / pdf / txt / key / pages / numbers / md。

对万相 3.0,首尾帧输入与参考组(reference_*、file、link)在同一次请求中互斥。

url 接受绝对的公网 http(s) 地址或 data: 内嵌(base64)。oss:// 会被拒绝——该对象归属你自己的云账号,网关无法代取。

类型、数量与组合在提交时校验;文件大小、尺寸、编码、时长与页数由服务在执行时校验。整个 JSON 请求体上限 128 MiB(含 base64 体积),大素材请用 URL。

parameters

模型不支持的参数返回 400,不会被忽略。网关总会发送 resolution 与 duration(默认值见上表);其他没传的字段不会发出,由服务默认值生效。

图生视频示例:

{
  "model": "happyhorse-1.1-i2v",
  "input": {
    "prompt": "镜头缓缓推进,光影在场景中流动",
    "media": [{ "type": "first_frame", "url": "data:image/jpeg;base64,..." }]
  },
  "parameters": { "resolution": "720P", "duration": 5, "watermark": false }
}

返回结果

提交响应

提交成功返回 200,HopBase 任务 ID 在官方响应结构的 output.task_id(形如 blt…):

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "PENDING"
  },
  "request_id": "..."
}

任务查询字段

轮询 GET /api/v1/tasks/{task_id},建议约 15 秒一次。

output.task_status(大写)依次经过 PENDING → RUNNING → SUCCEEDED | FAILED,只有后两者是终态,其他任何值都按进行中处理。一条片子通常 1-5 分钟完成,万相 3.0 的长片更久。

进行中

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "RUNNING"
  },
  "model": "wan3.0-video"
}

成功

成功时响应在 output.video_url 携带成片地址:

{
  "output": {
    "task_id": "blt60x4115010d-d361-4bfc-b131-a382f1c400a5",
    "task_status": "SUCCEEDED",
    "video_url": "https://api.hop-base.com/...",
    "orig_prompt": "..."
  },
  "usage": { "video_count": 1, "duration": 5, "SR": 1080, "output_video_duration": 5, "input_video_duration": 0, "ratio": "16:9", "billed_seconds": 5, "billing_bucket": "1080p", "cost": 4.08, "cost_usd": 0.6, "currency": "CNY" }
}

失败

失败任务不计费。code 恒为 TaskFailed,只能看 output.message 区分原因(异步任务失败):

{ "output": { "task_id": "blt60x...", "task_status": "FAILED", "code": "TaskFailed", "message": "..." } }

最小示例

BASE=https://api.hop-base.com
# 1. 提交
curl "$BASE/api/v1/services/aigc/video-generation/video-synthesis" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "input": {
      "prompt": "日出时分航拍云海之上的雪山"
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5,
      "ratio": "16:9"
    }
  }'

# 2. 用返回的 output.task_id 轮询,约 15 秒一次
curl "$BASE/api/v1/tasks/blt你的任务ID" \
  -H "Authorization: Bearer sk-your-key"

注意事项

• 未知字段与第二个 JSON 值会在请求发出前就被拒绝。这是刻意的。
• 参考素材由官方侧下载,而不是 HopBase 下载。屏蔽机房 IP 的图床(很多免费图床都会)会让任务在提交几分钟后失败,建议用 data: 内嵌或你自己的对象存储 / CDN。
• 查询路径 /api/v1/tasks/{task_id} 前面不带 /v1,和其他页面的视频查询接口不同。
• 没有列表接口,任务 ID 需要自行留存。
• 创建超过 2 小时仍未结束的任务会被自动判为失败,这两个系列的任务都不支持取消。
• output.video_url 是 api.hop-base.com 域名下的签名地址,自任务完成起 24 小时有效。再次查询返回同一地址、不会续期,过期访问返回 410,请在有效期内下载保存。
• usage.ratio 回报的是成片实际比例,可能是原始尺寸(如 1632:937)而不是请求里的枚举值。

常见报错 → 改法

请求错误返回 {"code":…,"message":…}。

413 与 404 的 message 原文:

request body exceeds the 128 MiB limit (received N bytes)
invalid task ID format
task not found            # 用其他用户的密钥查询也是这条

其他字段(OpenAI 的 size / n / image、万相 2.x 的 img_url / negative_prompt / shot_type、media 元素里的多余键)一律返回 400:

400 {"code":"InvalidParameter","message":"request body does not match the JSON contract: json: unknown field \"size\""}

任务失败时按 output.message 处理:

计费

提交任务时按「可用余额 − 进行中任务的预估费用 − 本次预估费用」判断,不足返回 402,code 为 insufficient_balance,任务结束后预估自动释放。失败任务不计费。视频任务通用规则详见视频总览。

两个系列都按视频秒数计费,单价随分辨率档位不同,不按 token 计量:

本次扣费 = usage.billed_seconds × usage.billing_bucket 档的单价

档位由 usage.SR(成片的分辨率档位,480 / 720 / 1080)决定;同一档位下两个系列单价不同。

两者的计费时长口径不同:

• 万相 3.0 官方写明「输入视频和输出视频均计费」,计费时长 = 输入视频时长 + 输出视频时长,所以 usage.input_video_duration 也计入计费秒数——无视频输入时它是 0.0。
• 快乐马 1.1 三个模型是「仅输出计费」,其中参考生视频的 input_video_duration 官方文档写明固定为 0。

任务结束后,查询响应根对象的 usage 还会带 cost_usd（本任务从余额实际扣除的美元金额，未扣费的失败为 0）、cost（同一笔的人民币金额）与 currency（恒为 CNY）。

官方牌价见价格页。你的实际单价以登录后的模型广场为准,每次请求的实际扣费见用量记录。

下一步

• 视频总览——所有视频模型共用的余额预占、超时与结果地址规则
• MiniMax 海螺 H3 视频 API
• 错误码与重试——含异步任务失败
• 并发、超时与计费