HappyHorse 视频编辑 API 参考

数眼智能 · API 文档
最后更新：2026-06-26

概述

HappyHorse 视频编辑模型支持输入视频与参考图，结合文本指令完成风格变换、局部替换等编辑任务。数眼智能已完成对该模型的兼容适配，您可通过数眼智能平台统一调用。

接口地址

环境	Base URL
数眼智能	`https://platform.shuyanai.com/ali`

在此 Base URL 基础上拼接官方路径即可完成调用。

认证方式

所有请求须在 Authorization 请求头中携带 API Key，格式如下：

Authorization: Bearer sk-xxxx

调用流程

视频编辑任务耗时较长（通常 1–5 分钟），API 采用异步调用方式，分为两个步骤：

创建任务 — 提交视频编辑请求，获取 task_id。

轮询查询 — 根据 task_id 查询任务状态与结果。

步骤一：创建任务

请求

POST https://platform.shuyanai.com/ali/api/v1/services/aigc/video-generation/video-synthesis

请求头（Headers）

参数名	类型	必选	说明
`Content-Type`	string	是	固定值：`application/json`
`Authorization`	string	是	API Key 认证。格式：`Bearer sk-xxxx`
`X-DashScope-Async`	string	是	异步处理标识，必须设置为 `enable`。缺少此请求头将返回错误：`"current user api does not support synchronous calls"`

请求体（Request Body）

参数名	类型	必选	说明
`model`	string	是	模型名称。固定值：`happyhorse-1.0-video-edit`
`input`	object	是	模型输入信息，详见下表
`parameters`	object	否	视频编辑参数，详见下表

`input` 对象

参数名	类型	必选	说明
`prompt`	string	是	文本提示词，用于描述对视频的编辑意图（如风格转换、局部替换等）。支持任意语言输入，长度不超过 5000 个非中文字符或 2500 个中文字符，超出部分自动截断。
`media`	array	是	媒体素材列表，必须包含 1 个 `video` 类型元素，可选包含 0~5 个 `reference_image` 类型元素。

`media[]` 元素属性

参数名	类型	必选	说明
`type`	string	是	媒体素材类型。可选值：`video`（待编辑的视频，必传）、`reference_image`（参考图像，可选）
`url`	string	是	媒体素材的 URL 地址

素材数量限制：

素材类型	数量要求
`video`	有且仅有 1 个
`reference_image`	0 ~ 5 张

视频限制（type=video）：

项目	要求
格式	MP4、MOV（建议 H.264 编码）
时长	3 ~ 60 秒
分辨率	长边不超过 4096 像素，短边不小于 360 像素
宽高比	1:2.5 ~ 2.5:1
文件大小	不超过 100MB
帧率	大于 8fps
输入方式	公网 URL（支持 HTTP/HTTPS 协议）

输出视频时长说明：输出视频时长为 3~15 秒。当输入视频不超过 15 秒时，输出时长与输入一致；当输入视频超过 15 秒时，系统自动截取前 15 秒。

参考图像限制（type=reference_image）：

项目	要求
格式	JPEG、JPG、PNG、WEBP
分辨率	宽高尺寸不小于 300 像素
宽高比	1:2.5 ~ 2.5:1
文件大小	不超过 20MB

支持的图像输入格式：

公网 URL：支持 HTTP 或 HTTPS 协议。示例：https://xxx/xxx.png

Base64 编码：格式为 data:{MIME_type};base64,{base64_data}。示例：data:image/png;base64,GDU7MtCZ...

图像格式	MIME Type
JPEG/JPG	`image/jpeg`
PNG	`image/png`
WEBP	`image/webp`

`parameters` 对象

参数名	类型	必选	默认值	说明
`resolution`	string	否	`1080P`	视频分辨率档位。可选值：`720P`、`1080P`
`watermark`	boolean	否	`true`	是否添加水印（位于视频右下角，文案固定为"Happy Horse"）。`true`：添加；`false`：不添加
`audio_setting`	string	否	`auto`	声音控制。`auto`：由模型自行控制；`origin`：保留输入视频的原始声音
`seed`	integer	否	随机	随机数种子，取值范围：`[0, 2147483647]`。固定 seed 可提升结果可复现性，但不保证完全一致

请求示例

成功响应

{
  "output": {
    "task_status": "PENDING",
    "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
  },
  "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

异常响应

{
  "code": "InvalidApiKey",
  "message": "No API-key provided.",
  "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

响应字段说明

字段名	类型	说明
`output.task_id`	string	任务 ID，用于后续查询。有效期 24 小时
`output.task_status`	string	任务状态。枚举值见任务状态说明
`request_id`	string	请求唯一标识，可用于溯源和问题排查
`code`	string	错误码（仅在请求失败时返回）
`message`	string	错误详情（仅在请求失败时返回）

步骤二：查询任务结果

请求

GET https://platform.shuyanai.com/ali/api/v1/tasks/{task_id}

将 {task_id} 替换为步骤一返回的任务 ID。

请求头（Headers）

参数名	类型	必选	说明
`Authorization`	string	是	API Key 认证。格式：`Bearer sk-xxxx`

轮询建议

视频编辑通常需数分钟，建议设置 15 秒的轮询间隔。

任务状态流转：PENDING → RUNNING → SUCCEEDED / FAILED。

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

task_id 有效期为 24 小时，超时后将无法查询。

请求示例

成功响应（任务完成）

{
  "request_id": "c11018a8-3f83-9591-a636-xxxxxx",
  "output": {
    "task_id": "051c7b40-b2c5-4341-aee4-xxxxxx",
    "task_status": "SUCCEEDED",
    "submit_time": "2026-04-26 14:13:14.373",
    "scheduled_time": "2026-04-26 14:13:14.419",
    "end_time": "2026-04-26 14:14:13.679",
    "orig_prompt": "让视频中的角色穿上图片中的条纹毛衣",
    "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxxx.mp4"
  },
  "usage": {
    "duration": 13.24,
    "input_video_duration": 6.62,
    "output_video_duration": 6.62,
    "video_count": 1,
    "SR": 720
  }
}

异常响应（任务失败）

{
  "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
  "output": {
    "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
    "task_status": "FAILED",
    "code": "InvalidParameter",
    "message": "The resolution is not valid xxxxxx"
  }
}

响应字段说明

字段名	类型	说明
`output.task_id`	string	任务 ID
`output.task_status`	string	任务状态。枚举值见任务状态说明
`output.submit_time`	string	任务提交时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`
`output.scheduled_time`	string	任务开始执行时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`
`output.end_time`	string	任务完成时间。格式：`YYYY-MM-DD HH:mm:ss.SSS`
`output.video_url`	string	生成的视频下载链接。仅在 `SUCCEEDED` 状态返回，有效期 24 小时。视频格式：MP4（H.264 编码）
`output.orig_prompt`	string	原始输入的 prompt
`output.code`	string	错误码（仅在失败时返回）
`output.message`	string	错误详情（仅在失败时返回）
`usage.duration`	float	总视频时长（秒），用于计费
`usage.input_video_duration`	float	输入视频时长（秒）
`usage.output_video_duration`	float	输出视频时长（秒）
`usage.video_count`	integer	输出视频数量，固定为 1
`usage.SR`	integer	输出视频分辨率档位
`request_id`	string	请求唯一标识，可用于溯源和问题排查

任务状态说明

状态值	说明
`PENDING`	任务排队中
`RUNNING`	任务处理中
`SUCCEEDED`	任务执行成功
`FAILED`	任务执行失败
`CANCELED`	任务已取消
`UNKNOWN`	任务不存在或状态未知（task_id 不存在或已超过 24 小时有效期）

完整调用示例（Python）

注意事项

异步必选头：X-DashScope-Async: enable 为必填请求头，缺少将报错。

task_id 有效期：任务 ID 有效期为 24 小时，过期后无法查询。

视频链接有效期：生成的视频下载链接有效期为 24 小时，请及时下载保存。

请勿重复创建：同一请求仅需创建一次任务，通过轮询获取结果即可。

查询频率限制：查询接口默认 RPS 为 20，建议轮询间隔不低于 15 秒。

输入视频时长：输出视频最长 15 秒，超过 15 秒的输入视频将自动截取前 15 秒。

声音控制：通过 audio_setting 参数可选择保留原始声音（origin）或由模型自行控制（auto）。

错误码

如调用失败并返回错误信息，常见错误码如下：

错误码	说明
`InvalidApiKey`	API Key 无效或未提供
`InvalidParameter`	请求参数不合法
`Throttling`	请求频率超限

如遇其他错误码，请联系数眼智能技术支持获取帮助。

本文档由数眼智能提供，基于阿里云百炼 HappyHorse 模型兼容适配。

HappyHorse-视频编辑

HappyHorse 视频编辑 API 参考#

概述#

接口地址#

认证方式#

调用流程#

步骤一：创建任务#

请求#

请求头（Headers）#

请求体（Request Body）#

input 对象#

media[] 元素属性#

parameters 对象#

请求示例#

成功响应#

异常响应#

响应字段说明#

步骤二：查询任务结果#

请求#

请求头（Headers）#

轮询建议#

请求示例#

成功响应（任务完成）#

异常响应（任务失败）#

响应字段说明#

任务状态说明#

完整调用示例（Python）#

注意事项#

错误码#

HappyHorse 视频编辑 API 参考

概述

接口地址

认证方式

调用流程

步骤一：创建任务

请求

请求头（Headers）

请求体（Request Body）

`input` 对象

`media[]` 元素属性

`parameters` 对象

请求示例

成功响应

异常响应

响应字段说明

步骤二：查询任务结果

请求

请求头（Headers）

轮询建议

请求示例

成功响应（任务完成）

异常响应（任务失败）

响应字段说明

任务状态说明

完整调用示例（Python）

注意事项

错误码