跳至正文
EN
获取 API Key
☰

HappyHorse-1.0 API 接入文档

使用 VezAPI 密钥接入 HappyHorse-1.0。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

HappyHorse-图生视频

POST/api/v1/jobs/createTask

模型标识： happyhorse/image-to-video

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `happyhorse/image-to-video` 模型

可选值："happyhorse/image-to-video"

默认："happyhorse/image-to-video"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态

input
必填		object

生成任务的输入参数

input.prompt
可选		string

可选的文本提示词，用于补充/约束由首帧图驱动的视频内容。

maxLength: 5000

input.image_urls
必填		array

输入首帧图片 URL（必须且只能 1 张）。图像限制：格式：JPEG、JPG、PNG、WEBP。分辨率：宽和高不小于300像素。宽高比：1:2.5～2.5:1。文件大小：不超过10MB。

maxItems: 1

input.resolution
可选		string

输出视频分辨率。输出比例跟随输入图片，720p / 1080p 指清晰度档位。

可选值："720p", "1080p"

默认："1080p"

input.duration
可选		integer

输出视频时长（单位：秒）。取值 3–15 的整数，默认 5。

默认：5

minimum: 3

maximum: 15

input.seed
可选		integer

随机种子。

minimum: 0

maximum: 2147483647

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "happyhorse/image-to-video",
  "input": {
    "prompt": "A cat running on the grass",
    "image_urls": [
      "Your prompt"
    ],
    "resolution": "1080p",
    "duration": 5
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

HappyHorse-参考生视频

POST/api/v1/jobs/createTask

模型标识： happyhorse/reference-to-video

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `happyhorse/reference-to-video` 模型

可选值："happyhorse/reference-to-video"

默认："happyhorse/reference-to-video"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态

input
必填		object

生成任务的输入参数

input.prompt
必填		string

用于描述视频内容，并用 character1/character2/... 指代参考图中的角色/主体。

maxLength: 5000

input.reference_image
必填		array

参考图片 URL 列表（顺序很重要，对应 character1、character2...）。图像限制：格式：JPEG、JPG、PNG、WEBP。分辨率：短边不低于400像素，推荐720P以上清晰图。避免传入过小、模糊或压缩过度的图像，影响效果。文件大小：不超过10MB。

minItems: 1

maxItems: 9

input.resolution
可选		string

输出视频分辨率。

可选值："720p", "1080p"

默认："1080p"

input.aspect_ratio
可选		string

输出视频宽高比。

可选值："16:9", "9:16", "1:1", "4:3", "3:4"

默认："16:9"

input.duration
可选		integer

输出视频时长（单位：秒）。取值 3–15 的整数，默认 5。

默认：5

minimum: 3

maximum: 15

input.seed
可选		integer

随机种子。

minimum: 0

maximum: 2147483647

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "happyhorse/reference-to-video",
  "input": {
    "prompt": "A woman in a red qipao character1. The shot opens with a side medium view outlining the tailored fit of the qipao and S-curve silhouette, then cuts to a low-angle shot capturing her gracefully unfolding a folding fan character2, with tassel earrings character3 swaying lightly as she turns her head. Finally, the camera pushes into a facial close-up, freezing on her fingertips lightly touching the fan ribs and the subtle, reserved charm in her expressive gaze. Through multiple angles, it comprehensively showcases an aura of Eastern elegance.",
    "reference_image": [
      "Your prompt"
    ],
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

HappyHorse-文生视频

POST/api/v1/jobs/createTask

模型标识： happyhorse/text-to-video

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `happyhorse/text-to-video` 模型

可选值："happyhorse/text-to-video"

默认："happyhorse/text-to-video"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态

input
必填		object

生成任务的输入参数

input.prompt
必填		string

用于描述要生成的视频内容、场景与风格的文本提示词。

maxLength: 5000

input.resolution
可选		string

输出视频分辨率。

可选值："720p", "1080p"

默认："1080p"

input.aspect_ratio
可选		string

输出视频的宽高比（画面比例）。

可选值："16:9", "9:16", "1:1", "4:3", "3:4"

默认："16:9"

input.duration
可选		integer

输出视频时长（单位：秒）。取值 3–15 的整数，默认 5。

默认：5

minimum: 3

maximum: 15

input.seed
可选		integer

随机种子（用于可复现/控制随机性）。

minimum: 0

maximum: 2147483647

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "happyhorse/text-to-video",
  "input": {
    "prompt": "A miniature city built from cardboard and bottle caps comes to life at night. A cardboard train slowly passes through, with small lights dotting the scene and illuminating the way ahead.",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

HappyHorse-视频编辑

POST/api/v1/jobs/createTask

模型标识： happyhorse/video-edit

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。必填字段。 - 该接口必须使用 `happyhorse/video-edit` 模型

可选值："happyhorse/video-edit"

默认："happyhorse/video-edit"

callBackUrl
可选		string

接收生成任务完成通知的回调 URL。可选配置，生产环境建议使用。 - 任务生成完成后，系统会向该 URL 以 POST 方式推送任务状态和结果 - 回调内容包含生成内容的 URL 及任务相关信息 - 你的回调接口需支持接收 POST 请求及 JSON 格式的请求体 - 也可选择调用任务详情接口，主动轮询任务状态

input
必填		object

生成任务的输入参数

input.prompt
必填		string

视频编辑指令，用自然语言描述“要怎么改”。

maxLength: 5000

input.video_url
必填		string

待编辑的视频 URL（必须且只能 1 个）。 视频限制： 格式：MP4、MOV（建议H.264编码）。 时长：3-60秒。 分辨率：长边不超过2160像素，短边不小于320像素。 宽高比：1:2.5~2.5:1。 文件大小：不超过100MB。 帧率：大于8fps。

input.reference_image
可选		array

可选参考图片 URL（用于风格/局部替换参考）。 图像限制： 格式：JPEG、JPG、PNG、WEBP。 分辨率：宽高尺寸不小于300像素。 宽高比：1:2.5~2.5:1。 文件大小：不超过10MB。

minItems: 0

maxItems: 5

input.resolution
可选		string

输出视频分辨率。

可选值："720p", "1080p"

默认："1080p"

input.audio_setting
可选		string

音频处理策略：auto 表示由模型自动处理；origin 表示尽量保留原视频音频。

可选值："auto", "origin"

默认："auto"

input.seed
可选		integer

随机种子。

minimum: 0

maximum: 2147483647

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "happyhorse/video-edit",
  "input": {
    "prompt": "Make the horse-headed humanoid character in the video wear the striped sweater from the image",
    "video_url": "Your prompt",
    "resolution": "1080p"
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。