创建 Happy Horse 视频任务

本页示例中的 {BASE_URL} 表示 https://api.uniall.ai。

更新时间：2026-08-10

概览

所有能力都使用唯一公共模型 happy-horse。通过 operation 选择文生、图生、多参考图或视频编辑，通过 resolution 选择输出档位。

不要使用已删除的旧档位模型名。旧名字与当前公共契约不兼容。

接口

POST /v1/videos

兼容的创建路径：

POST /v1/videos/generations
POST /v1/video/generations

新接入建议使用 /v1/videos。

鉴权

Authorization: Bearer sk-***
Content-Type: application/json

能力矩阵

`operation`	提示词	图片输入	视频输入	分辨率	`duration`	`aspect_ratio`
`text_to_video`	必填	不接受	不接受	`720p`、`1080p`	可选，默认 `5`	可选，默认 `16:9`
`image_to_video`	可选	恰好 1 张	不接受	`720p`、`1080p`	可选，默认 `5`	不支持
`reference_to_video`	必填	1 至 9 张	不接受	`720p`、`1080p`	可选，默认 `5`	可选，默认 `16:9`
`edit_video`	必填	0 至 5 张	恰好 1 个	`720p`、`1080p`	不支持	不支持

请求体参数

参数	类型	必填	说明
`model`	string	是	固定为 `happy-horse`。
`operation`	string	是	`text_to_video`、`image_to_video`、`reference_to_video` 或 `edit_video`。
`resolution`	string	是	所有操作均支持 `720p` 或 `1080p`。
`prompt`	string	条件必填	除 `image_to_video` 外均必填，最长 `2500` 字符。
`duration`	integer	否	仅生成使用，范围 `3` 至 `15`，默认 `5`；编辑请求不能传。
`aspect_ratio`	string	否	仅文生和多参考图生视频使用；图生和编辑请求不能传。
`image`	string	条件必填	`image_to_video` 推荐使用的单张 HTTP(S) 图片字段。
`images`	string[]	条件必填	`reference_to_video` 使用的 1 至 9 张 HTTP(S) 图片。
`reference_image_urls`	string[]	否	多参考图的别名；视频编辑也可使用，最多 5 张。
`video`	string	条件必填	`edit_video` 使用的单个 HTTP(S) 源视频。
`seed`	integer	否	随机种子，范围 `0` 至 `2147483647`。
`watermark`	boolean	否	是否添加水印，默认 `false`。
`audio_setting`	string	否	仅编辑使用：`auto` 或 `origin`，默认 `auto`。

文生和多参考图生视频支持以下 aspect_ratio：

16:9
9:16
1:1
4:3
3:4
4:5
5:4
9:21
21:9

size 和 enable_safety_checker 不属于 Happy Horse 公共参数，传入会被拒绝。

公共 HappyHorse 1.0 契约不开放 480p。把 resolution 设为 480p 的请求会在任务创建前被拒绝。

输入规则

模式	可用素材字段
文生视频	不传图片或视频字段
图生视频	使用 `image`，或通过受支持的图片别名传入恰好 1 张图片
多参考图生视频	使用 `images` 或 `reference_image_urls`，传入 1 至 9 个 URL
视频编辑	使用 `video`，并可选传入最多 5 个 `reference_image_urls`

所有媒体输入都必须是完整、可公开访问的 HTTP 或 HTTPS URL。当前模型契约不接受文件上传、裸 Base64 或 Data URL。

请求示例

文生视频

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "text_to_video",
    "resolution": "1080p",
    "prompt": "A white horse runs across a misty grassland at sunrise, realistic movement and soft rim light.",
    "duration": 7,
    "aspect_ratio": "21:9",
    "seed": 12345,
    "watermark": false
  }'

图生视频

输出构图跟随源图片，因此不要传 aspect_ratio。

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "image_to_video",
    "resolution": "720p",
    "image": "https://example.com/source-frame.png",
    "prompt": "The subject walks forward naturally while the camera slowly pushes in.",
    "duration": 5,
    "seed": 67890,
    "watermark": false
  }'

image_to_video 可以省略提示词。

多参考图生视频

提示词可以使用 character1 至 character9，按数组顺序指代参考图。

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "reference_to_video",
    "resolution": "720p",
    "prompt": "character1 drives character2 across the lunar surface while both identities remain consistent.",
    "reference_image_urls": [
      "https://example.com/character.png",
      "https://example.com/vehicle.png"
    ],
    "duration": 8,
    "aspect_ratio": "16:9",
    "seed": 24680,
    "watermark": false
  }'

视频编辑

编辑时长跟随源视频，不能传 duration 或 aspect_ratio。

curl -X POST "{BASE_URL}/v1/videos" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "happy-horse",
    "operation": "edit_video",
    "resolution": "1080p",
    "prompt": "Replace the jacket with the referenced red jacket while preserving identity, motion, camera movement, and background.",
    "video": "https://example.com/source-video.mp4",
    "reference_image_urls": [
      "https://example.com/red-jacket.png"
    ],
    "audio_setting": "origin",
    "seed": 13579,
    "watermark": false
  }'

使用 audio_setting: "origin" 保留原音频；使用 auto 让服务自动决定音频处理方式。

`extra_body` 兼容

推荐把公共参数直接放在请求体顶层。兼容客户端也可以把 operation、resolution、seed、watermark 和 audio_setting 放入 extra_body。不要在顶层和 extra_body 中传入互相冲突的值。

{
  "model": "happy-horse",
  "prompt": "Turn the room into a warm wooden studio.",
  "video": "https://example.com/source-video.mp4",
  "extra_body": {
    "operation": "edit_video",
    "resolution": "720p",
    "audio_setting": "auto",
    "watermark": false
  }
}

响应示例

任务已受理

{
  "id": "task_xxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxx",
  "object": "video.generation.job",
  "model": "happy-horse",
  "status": "queued",
  "progress": 0,
  "created_at": 1785801600,
  "video_url": null
}

任务状态与结果

创建成功后保存 id 或 task_id，随后调用 GET /v1/videos/{task_id}，直到任务进入 completed 或 failed。统一的轮询间隔、状态字段、错误结构、结果地址和鉴权下载方式见视频生成概览。

视频编辑等最终结算操作应在任务完成后再次读取 billing_contract。

素材限制

图生视频源图片

格式：JPEG、JPG、PNG、BMP 或 WebP。
最小尺寸：300px。
画面比例：1:2.5 至 2.5:1。
最大文件：10MB。

多参考图

格式：JPEG、JPG、PNG 或 WebP。
数量：1 至 9 张。
最短边至少 400px，建议 720p 以上。
每张最大 10MB。

视频编辑源素材

格式：MP4 或 MOV，推荐 H.264。
输入时长：3 至 60 秒；编辑服务最多处理 15 秒。
尺寸：长边不超过 2160px，短边不小于 320px。
画面比例：1:2.5 至 2.5:1。
帧率：大于 8fps。
最大文件：100MB。

编辑参考图支持 JPEG、JPG、PNG 或 WebP，尺寸至少 300px，每张最大 10MB。

计费说明

文生、图生和多参考图生成按请求的输出时长与分辨率档位结算。
视频编辑根据实际输入和输出视频时长进行最终结算，最终费用可能与提交时预估不同。
resolution 是服务档位，不保证每种画幅或源图片都对应一个固定像素尺寸。
最终金额以 UniAll 当前价格页和任务结算记录为准。

常见错误

错误	原因	处理方式
模型名无效	使用了已删除的旧档位模型名	把 `model` 改为 `happy-horse`
缺少参数	未传 `operation` 或 `resolution`	显式传入两个参数
参数不支持	传入了 `size` 或 `enable_safety_checker`	删除不支持的字段
素材数量不正确	当前操作收到错误数量的图片或视频	按能力矩阵调整素材
分辨率不正确	`resolution` 为 `480p` 或其他不支持的值	使用 `720p` 或 `1080p`
编辑参数不正确	编辑请求包含 `duration` 或 `aspect_ratio`	删除不支持字段
素材下载失败	URL 私有、过期、重定向异常或无法访问	使用稳定的公开 HTTPS URL

概览​

接口​

鉴权​

能力矩阵​

请求体参数​

输入规则​

请求示例​

文生视频​

图生视频​

多参考图生视频​

视频编辑​

extra_body 兼容​

响应示例​

任务已受理​

任务状态与结果​

素材限制​

图生视频源图片​

多参考图​

视频编辑源素材​

计费说明​

常见错误​

相关页面​

概览

接口

鉴权