HappyHorse

1. Overview

All video generation capabilities (text-to-video, image-to-video, reference-to-video, video editing) are submitted through the same endpoint, distinguished by the model field:

POST /v1/videos

2. Top-level Request Parameters

All video control parameters (resolution, watermark, audio, random seed, etc.) must be placed inside the metadata field and cannot be placed at the top level of the request. Only the following fields are accepted at the top level:

Parameter	Type	Required	Description
model	string	Yes	Pass the HappyHorse mapped model name, e.g. happyhorse-1.0-i2v-720p
prompt	string	Yes	Video generation prompt / scene description
input_reference	string	Yes (image-to-video)	First-frame image URL (publicly accessible), used for image-to-video
duration	int	No	Video duration (seconds), typically in the range 3~10
seconds	string	No	Alternative way to express duration, optional per model requirements
size	string	No	Video size (e.g. 1280*720); resolution is mainly determined by the model name suffix (-720p / -1080p), no parameter needs to be passed
metadata	object	No	All video control parameters go here (see table below)

Note: Passing watermark / audio / seed / parameters directly at the top level will not take effect. Please put them in metadata uniformly.

3. metadata Control Parameters

Resolution note: Resolution is specified by calling different models (the -720p / -1080p suffix in the model name), no parameter needs to be passed. For example happyhorse-1.0-i2v-720p means 720P, and happyhorse-1.0-i2v-1080p means 1080P. There is no resolution parameter in metadata.

Parameter	Type	Default	Description
watermark	bool	false (off by default)	Whether to add a platform watermark, pass true explicitly if a watermark is needed
audio	bool	Model default	Whether to generate audio, only supported for Video Editing (edit) tasks
seed	int	Random	Random seed, range 0 ~ 2147483647, used for result reproduction

metadata Request Example

metadata content (JSON):

{
  "watermark": true,
  "seed": 123456
}

cURL

curl --location --request POST 'https://neolink.com/api/v1/videos' \
--header 'Authorization: Bearer <API Key>' \
--form 'model="happyhorse-1.0-i2v-720p"' \
--form 'prompt="A calico cat playing a piano on stage"' \
--form 'input_reference="https://example.com/first_frame.png"' \
--form 'metadata={"watermark":true,"seed":123456}'

Python

import requests

url = "https://neolink.com/api/v1/videos"

headers = {
    "Authorization": "Bearer <API Key>"
}

data = {
    "model": (None, "happyhorse-1.0-i2v-720p"),
    "prompt": (None, "A calico cat playing a piano on stage"),
    "input_reference": (None, "https://example.com/first_frame.png"),
    "metadata": (None, '{"watermark":true,"seed":123456}'),
}

response = requests.post(url, headers=headers, data=data)

print(response.status_code)
print(response.text)

4. Text-to-Video (t2v)

POST /v1/videos

cURL

curl --location --request POST 'https://neolink.com/api/v1/videos' \
--header 'Authorization: Bearer <API Key>' \
--form 'model="<Model ID>"' \
--form 'prompt="A calico cat playing a piano on stage"' \
--form 'duration="4"' \
--form 'ratio="16:9"' \
--form 'metadata={"watermark":true,"seed":123456}'

Python

import requests

url = "https://neolink.com/api/v1/videos"

headers = {
"Authorization": "Bearer <API Key>"
}

data = {
"model": (None, "<Model ID>"),
"prompt": (None, "A calico cat playing a piano on stage"),
"duration": (None, "4"),
"ratio": (None, "16:9"),
"metadata": (None, '{"watermark":true,"seed":123456}'),
}

response = requests.post(url, headers=headers, data=data)

print(response.status_code)
print(response.text)

Supported Models: happyhorse-1.0-t2v-720p, happyhorse-1.0-t2v-1080p

5. Image-to-Video (i2v)

POST /v1/videos

cURL

curl --location --request POST 'https://neolink.com/api/v1/videos' \
--header 'Authorization: Bearer <API Key>' \
--form 'model="<Model ID>"' \
--form 'prompt="A calico cat playing a piano on stage"' \
--form 'duration="4"' \
--form 'input_reference="xxx.png"' \
--form 'metadata={"watermark":true,"seed":123456}'

Python

import requests

url = "https://neolink.com/api/v1/videos"

headers = {
"Authorization": "Bearer <API Key>"
}

data = {
"model": (None, "<Model ID>"),
"prompt": (None, "A calico cat playing a piano on stage"),
"duration": (None, "4"),
"input_reference": (None, "xxx.png"),
"metadata": (None, '{"watermark":true,"seed":123456}'),
}

response = requests.post(url, headers=headers, data=data)

print(response.status_code)
print(response.text)

Supported Models: happyhorse-1.0-i2v-720p, happyhorse-1.0-i2v-1080p

6. Reference-to-Video (r2v)

POST /v1/videos

cURL

curl --location --request POST 'https://neolink.com/api/v1/videos' \
--header 'Authorization: Bearer <API Key>' \
--form 'model="<Model ID>"' \
--form 'prompt="[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，[Image 3]中的流苏耳坠随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。"' \
--form 'duration="3"' \
--form 'ratio="9:16"' \
--form 'input_reference="https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg,https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"' \
--form 'metadata={"watermark":true,"seed":123456}'

Python

import requests

url = "https://neolink.com/api/v1/videos"

headers = {
"Authorization": "Bearer <API Key>"
}

data = {
"model": (None, "<Model ID>"),
"prompt": (None, "[Image 1]中身着红色旗袍的女性，镜头先以侧面中景勾勒旗袍修身剪裁与S型曲线，随即切换至低角度仰拍，捕捉她轻抬玉手展开[Image 2]中的折扇的同时，[Image 3]中的流苏耳坠随头部转动轻盈摆动的细节，最后推近至面部特写，定格在她指尖轻点扇骨、眼波流转间的含蓄风情，多视角全方位展现东方韵味。"),
"duration": (None, "3"),
"ratio": (None, "9:16"),
"input_reference": (None, "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg,https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"),
"metadata": (None, '{"watermark":true,"seed":123456}'),
}

response = requests.post(url, headers=headers, data=data)

print(response.status_code)
print(response.text)

Supported Models: happyhorse-1.0-r2v-720p, happyhorse-1.0-r2v-1080p

7. Video Editing (edit)

POST /v1/videos

cURL

curl --location --request POST 'https://neolink.com/api/v1/videos' \
--header 'Authorization: Bearer <API Key>' \
--form 'model="<Model ID>"' \
--form 'prompt="A calico cat which is in this video playing a piano on stage"' \
--form 'input_reference="xxx.mp4"' \
--form 'metadata={"watermark":true,"audio":true,"seed":123456}'

Python

import requests

url = "https://neolink.com/api/v1/videos"

headers = {
"Authorization": "Bearer <API Key>"
}

data = {
"model": (None, "<Model ID>"),
"prompt": (None, "A calico cat which is in this video playing a piano on stage"),
"input_reference": (None, "xxx.mp4"),
"metadata": (None, '{"watermark":true,"audio":true,"seed":123456}'),
}

response = requests.post(url, headers=headers, data=data)

print(response.status_code)
print(response.text)

Supported Models: happyhorse-1.0-edit-720p, happyhorse-1.0-edit-1080p