HappyHorse 图生视频

HappyHorse 图生视频模型，以首帧图片为基础，支持通过文本描述进行引导，生成物理真实、运动流畅的视频。

接入规则

鉴权方式

路径规则

步骤	路径
创建任务	`POST /v1/videos/generations`
查询结果	`GET /v1/videos/generations/{task_id}`

调用流程

图生视频任务耗时较长（通常 1–5 分钟），采用异步方式：创建任务 → 轮询查询。

步骤 1：创建任务

POST https://api.onelinkai.cloud/v1/videos/generations

说明

创建成功后使用返回的 id 查询结果，有效期 24 小时。

请勿重复创建任务，轮询获取即可。

请求示例

请求参数

参数	类型	必选	说明
`model`	string	✔️	模型名称。可选值：`happyhorse-1.0-i2v`
`prompt`	string		文本提示词，描述期望生成的视频内容。支持任意语言，不超过 5000 个非中文字符或 2500 个中文字符。
`images`	array	✔️	首帧图像 URL 列表，有且仅有 1 张。支持公网 HTTP/HTTPS URL 或 Base64 编码（格式：`data:{MIME_type};base64,{base64_data}`）。图像要求：JPEG / JPG / PNG / WEBP，宽高不小于 300px，宽高比 1:2.5～2.5:1，文件不超过 20MB。
`extra.parameters.resolution`	string		视频分辨率。输出宽高比自动跟随首帧图像，无需指定 `ratio`。可选值：`720P` / `1080P`（默认）。
`extra.parameters.duration`	integer		视频时长（秒），取值范围 `[3, 15]`，默认 `5`。
`extra.parameters.watermark`	boolean		是否添加水印（右下角"Happy Horse"）。`true`（默认）/ `false`。
`extra.parameters.seed`	integer		随机种子，范围 `[0, 2147483647]`。未指定时系统自动生成。

注意：图生视频的宽高比自动跟随输入首帧图像，不支持 ratio 参数。

响应示例

成功

{
  "id": "0385dc79-5ff8-4d82-bcb6-xxxxxx",
  "object": "video",
  "created_at": 1745142917,
  "model": "happyhorse-1.0-i2v",
  "status": "pending",
  "progress": 0
}

失败

{
  "error": {
    "message": "No API-key provided.",
    "type": "video_error"
  }
}

响应参数

参数	类型	说明
`id`	string	任务 ID，用于查询结果，有效期 24 小时。
`status`	string	任务状态：`pending` / `running` / `completed` / `failed` / `canceled` / `unknown`。
`progress`	integer	任务进度（0–100）。

步骤 2：查询任务结果

GET https://api.onelinkai.cloud/v1/videos/generations/{task_id}

说明

建议轮询间隔 15 秒。

状态流转：pending → running → completed / failed。

任务成功后返回视频链接，有效期 24 小时，请及时下载转存。

task_id 有效期 24 小时，超时后状态返回 unknown。

请求示例

响应示例

成功

{
  "id": "e56d806f-76f9-4037-aefa-xxxxxx",
  "object": "video",
  "created_at": 1745142917,
  "completed_at": 1745143000,
  "model": "happyhorse-1.0-i2v",
  "status": "completed",
  "progress": 100,
  "prompt": "一只猫在草地上奔跑",
  "data": {
    "url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx",
    "expires_at": 1745229400
  },
  "usage": {
    "duration": 5,
    "input_video_duration": 0,
    "output_video_duration": 5,
    "video_count": 1
  }
}

失败

{
  "id": "86ecf553-d340-4e21-af6e-xxxxxx",
  "object": "video",
  "status": "failed",
  "fail_reason": "The parameter is invalid."
}

任务过期

{
  "id": "502a00b1-19d9-4839-a82f-xxxxxx",
  "object": "video",
  "status": "unknown"
}

响应参数

参数	类型	说明
`id`	string	任务 ID。
`status`	string	任务状态：`pending` / `running` / `completed` / `failed` / `canceled` / `unknown`。
`progress`	integer	任务进度（0–100）。`completed` 时为 100。
`prompt`	string	原始输入提示词。
`data.url`	string	视频下载链接，仅 `completed` 时返回，有效期 24 小时。视频格式为 MP4（H.264，24fps）。
`data.expires_at`	integer	链接过期时间（Unix 时间戳）。
`usage.duration`	number	计费视频时长（秒）。
`usage.output_video_duration`	number	输出视频时长（秒）。
`usage.video_count`	integer	输出视频数量，固定为 1。
`fail_reason`	string	失败原因，仅 `failed` 时返回。
`completed_at`	integer	任务完成时间（Unix 时间戳）。

使用建议

先联调创建接口，确认能成功返回 id。

再联调查询接口，确认状态流转和结果解析正常。

视频链接有效期 24 小时，建议获取后立即转存至永久存储。

图生视频宽高比自动跟随首帧图像，无需也不支持指定 ratio。

接入规则#

鉴权方式#

路径规则#

调用流程#

步骤 1：创建任务#

请求示例#

请求参数#

响应示例#

响应参数#

步骤 2：查询任务结果#

请求示例#

响应示例#

响应参数#

使用建议#

接入规则

鉴权方式

路径规则

调用流程

步骤 1：创建任务

请求示例

请求参数

响应示例

响应参数

步骤 2：查询任务结果

请求示例

响应示例

响应参数

使用建议