视频生成 Videos

提交视频生成任务

POST /api/v1/videos
Authorization: Bearer sk-xxx
Content-Type: application/json

异步视频生成接口，提交任务后返回 taskId，通过轮询获取结果。

Request

字段	类型	必填	说明
model	string	*	视频生成模型 ID，如 happyhorse-1.1-t2v、wan2.7-i2v
prompt	string	*	视频描述文本

HappyHorse 子模型参数说明

HappyHorse 系列视频模型根据子模型类型不同，所需参数也不同。请根据你使用的模型 ID 后缀判断子模型类型：

子模型类型	模型 ID 后缀	必需参数	可选参数	说明
t2v（文生视频）	-t2v	model, prompt	size, duration	纯文本描述生成视频，无需图片
i2v（图生视频）	-i2v	model, prompt, first_frame_url	size, duration, last_frame_url	从首帧图片生成视频
r2v（参考图视频）	-r2v	model, prompt, ref_image_urls	size, duration	参考一张或多张图片生成视频
video-edit（视频编辑）	video-edit	model, prompt, video_url	size	对输入视频做编辑；输出时长跟随输入视频，duration 对该族不生效

各参数详细说明：

字段	类型	说明
first_frame_url	string	首帧图片 URL（i2v 必需）
video_url	string	待编辑视频的 URL（video-edit 必需；旧写法把视频地址填进 first_frame_url / image_url 同样接受）
last_frame_url	string	尾帧图片 URL（仅 i2v 可选，用于首尾帧控制）
ref_image_urls	array	参考图 URL 数组（r2v 必需），如 ["https://...jpg"]
size	string	视频分辨率，如 1920*1080、1280*720
duration	number	请求的视频时长（秒），不传按 5 秒。对 video-edit 族只是预扣基数，不改变实际输出长度，见下方「计费说明」

请求示例

t2v 文生视频：

{
  "model": "happyhorse-1.1-t2v",
  "prompt": "一只金毛犬在海边奔跑，阳光明媚，慢动作"
}

i2v 图生视频：

{
  "model": "happyhorse-1.1-i2v",
  "prompt": "图片中的人物缓缓转身微笑",
  "first_frame_url": "https://example.com/photo.jpg"
}

r2v 参考图视频：

{
  "model": "happyhorse-1.1-r2v",
  "prompt": "参考图中的人物在公园里散步",
  "ref_image_urls": ["https://example.com/ref1.jpg", "https://example.com/ref2.jpg"]
}

video-edit 视频编辑：

{
  "model": "happyhorse-1.0-video-edit",
  "prompt": "把画面改成夜晚，霓虹灯反光",
  "video_url": "https://example.com/input.mp4"
}

Wan2.7 i2v 首尾帧控制：

{
  "model": "wan2.7-i2v",
  "prompt": "从第一帧过渡到最后一帧，花瓣飘落",
  "first_frame_url": "https://example.com/start.jpg",
  "last_frame_url": "https://example.com/end.jpg"
}

错误提示

如果缺少必需参数，接口会返回清晰的错误提示：

{
  "code": 400,
  "msg": "模型 happyhorse-1.1-i2v 为图生视频(i2v)模型，必须提供 first_frame_url（首帧图片URL）。示例: {\"model\": \"happyhorse-1.1-i2v\", \"prompt\": \"...\", \"first_frame_url\": \"https://...\"}"
}

查询任务状态

GET /api/v1/videos/{taskId}
Authorization: Bearer sk-xxx

状态说明：

task_status	含义	说明
PENDING	排队中	任务已提交，等待处理
RUNNING	生成中	视频正在生成
SUCCEEDED	已完成	生成成功，返回 video_url
FAILED	失败	生成失败，已自动退款

PENDING / RUNNING 响应：

{
  "request_id": "xxx",
  "output": {
    "task_id": "6eea9a05-eb65-48eb-9ed1-4d2f0908994c",
    "task_status": "PENDING"
  }
}

SUCCEEDED 响应：

{
  "request_id": "xxx",
  "output": {
    "task_id": "6eea9a05-eb65-48eb-9ed1-4d2f0908994c",
    "task_status": "SUCCEEDED",
    "video_url": "https://dashscope.oss.aliyuncs.com/xxx.mp4"
  },
  "usage": {
    "duration": 5,
    "video_count": 1
  }
}

💡 建议轮询间隔 5~10 秒，视频生成通常需要 1~3 分钟。

计费说明

视频按秒计价，单价由模型与分辨率档决定。计费秒数取上游实际交付的时长，也就是轮询响应里的 usage.duration，不是请求里填的那个数。

扣费分两步：

1. 提交任务时预扣 —— 按请求的 duration（不传按 5 秒）乘以单价先扣一笔。
2. 任务 SUCCEEDED 时结算差额 —— 用 usage.duration 与预扣基数比对，少扣了补扣、多扣了退回，差额在账单上单独成行；任务 FAILED 则预扣全额退回，不收费。

因此「请求填 5 秒、账单不是 5 秒」是正常的：以实际交付为准。

video-edit（视频编辑）这一族：计费秒数 = 输入 + 输出两段

其它族（t2v / i2v / r2v）从头生成，usage.duration 就是输出视频时长。video-edit 是在一段已有视频上改，上游把「读进去的输入视频」和「改完输出的视频」两段时长相加作为计费量，usage 里会拆给你看：

{
  "usage": {
    "duration": 12.12,
    "input_video_duration": 6.06,
    "output_video_duration": 6.06,
    "video_count": 1,
    "SR": 720
  }
}

两个实际影响：

• 输出时长跟随输入视频，duration 在这族上不生效。 实测同一段 6.06 秒的输入，请求填 duration: 3 和填 duration: 5，交付完全一致（都是输入 6.06s + 输出 6.06s，计费 12.12 秒）。该字段在这族上只起预扣基数作用。
• 成本按输入视频长度线性增长。 6 秒输入约计 12 秒，30 秒输入就约计 60 秒。用 video-edit 前请按输入素材的实际时长估算预算，别按 duration 估。