Alibaba AI Docs

Appearance

HappyHorse text-to-video API reference ​

HappyHorse text-to-video generates physically realistic, motion-smooth video from text prompts.

Availability ​

The model, endpoint URL, and API key must belong to the same region. Cross-region calls fail.

  • Select a model: Check which region the model belongs to.

  • Select a URL: Use the endpoint URL for the corresponding region. HTTP URLs are supported.

  • Configure an API key : Get an API key for the region, and then Export API key as environment variable.

Note

The sample code in this topic applies to the Singapore region.

HTTP request ​

Text-to-video tasks typically take 1 to 5 minutes, so the API uses asynchronous calls. The workflow has two steps: "Create a task -> Poll for results", as described below:

Step 1: Create a task and get the task ID ​

Singapore ​

POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

US (Virginia) ​

POST https://dashscope-us.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

China (Beijing) ​

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Germany (Frankfurt) ​

POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis

Replace WorkspaceId with your actual Workspace ID. Note

  • After the task is created, use the returned task_id to query the result. The task_id is valid for 24 hours. Do not create duplicate tasks. Instead, use polling to retrieve the result.

  • For guidance for beginners, see Postman.

Request parameters ​

## Text-to-video ​

curl
curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \\
 -H 'X-DashScope-Async: enable' \\
 -H "Authorization: Bearer $DASHSCOPE_API_KEY" \\
 -H 'Content-Type: application/json' \\
 -d '{
 "model": "happyhorse-1.0-t2v",
 "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."
 },
 "parameters": {
 "resolution": "720P",
 "ratio": "16:9",
 "duration": 5
 }
}'

Content-Type *string* (Required) The content type of the request. Must be application/json.

Authorization *string* (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

X-DashScope-Async *string* (Required) Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.

**

**Important ** If this request header is missing, the error "current user api does not support synchronous calls" is returned.

Request body ​

model *string* (Required) The model to use for video generation. Valid values:

  • happyhorse-1.0-t2v

input *object* (Required) Input for the model. Properties

prompt *string* (Required) The text description of the video to generate. Supports any language. Maximum 5,000 non-Chinese characters or 2,500 Chinese characters; excess is truncated.

parameters *object* (Optional) Video parameters such as resolution and duration. Properties

resolution *string* (Optional) Resolution of the generated video. Valid values:

  • 720P
  • 1080P (default)

ratio *string* (Optional) Aspect ratio of the generated video. Valid values:

  • 16:9 (default)
  • 9:16
  • 1:1
  • 4:3
  • 3:4
  • 4:5
  • 5:4

duration *integer* (Optional) Duration of the generated video, in seconds.

  • happyhorse-1.0-t2v: Must be between 3 and 15. Defaults to 5.

watermark *boolean* (Optional) Whether to add a watermark to the generated video. The watermark appears in the lower-right corner with the text "HappyHorse".

  • true (default)
  • false

seed *integer* (Optional) The random number seed must be an integer in the range \[0, 2147483647\]. If not specified, a random seed is generated. A fixed seed improves reproducibility. Because model generation is probabilistic, the same seed does not guarantee identical results.

Response parameters ​

Successful response ​

Save the task_id to query the task status and result.

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

Error response ​

Task creation failed. See Error messages.

json
{
 "code": "InvalidApiKey",
 "message": "No API-key provided.",
 "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}
     **output** `*object*` Task output information.

Properties

task_id *string* The task ID. Valid for queries for 24 hours.

task_status *string* The status of the task. Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.

request_id *string* Unique request identifier for tracing and troubleshooting.

code *string* Error code. Returned only for failed requests. See Error messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

Step 2: Query the result by task ID ​

Singapore ​

GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

US (Virginia) ​

GET https://dashscope-us.aliyuncs.com/api/v1/tasks/{task_id}

China (Beijing) ​

GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Germany (Frankfurt) ​

GET https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

Replace WorkspaceId with your actual Workspace ID. Note

  • Polling recommendation: Video generation takes several minutes. Use a polling mechanism with a reasonable interval, such as 15 seconds.

  • Task state transition: PENDING → RUNNING → SUCCEEDED or FAILED.

  • Result link : After a task succeeds, a video URL valid for 24 hours is returned. Download and save the video to permanent storage, such as OSS.

  • task_id****validity : 24 hours . After this period, queries return the task status as UNKNOWN.

Request parameters ​

## Query task result ​

Replace {task_id} with the task_id value returned by the previous API call. The task_id is valid for queries for 24 hours.

curl
curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id} \\
--header "Authorization: Bearer $DASHSCOPE_API_KEY"
Headers ​

Authorization *string* (Required) Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Path parameters ​

task_id *string* (Required) The ID of the task.

Response parameters ​

## Task succeeded ​

Video URLs are valid for only 24 hours and then automatically purged. Save generated videos promptly.

json
{
 "request_id": "99243b47-ec5f-9413-9993-xxxxxx",
 "output": {
 "task_id": "4673458e-28be-4a05-bf2a-xxxxxx",
 "task_status": "SUCCEEDED",
 "submit_time": "2026-04-20 17:55:17.075",
 "scheduled_time": "2026-04-20 17:55:17.129",
 "end_time": "2026-04-20 17:56:36.658",
 "orig_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.",
 "video_url": "https://dashscope-result.oss-cn-beijing.aliyuncs.com/xxx.mp4?Expires=xxx"
 },
 "usage": {
 "duration": 5,
 "input_video_duration": 0,
 "output_video_duration": 5,
 "video_count": 1,
 "SR": 720,
 "ratio": "16:9"
 }
}

## Task failed ​

When a task fails, task_status is FAILED with an error code and message. See Error messages.

json
{
 "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
 "output": {
 "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
 "task_status": "FAILED",
 "code": "InvalidParameter",
 "message": "The parameter is invalid."
 }
}

## Task query expired ​

The task_id is valid for 24 hours. After this period, queries return the following error.

json
{
 "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
 "output": {
 "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
 "task_status": "UNKNOWN"
 }
}
     **output **`*object*` Task output information.

Properties

task_id *string* The task ID. Valid for queries for 24 hours.

task_status *string* The status of the task. Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.

State transitions during polling:

  • PENDING → RUNNING → SUCCEEDED or FAILED.
  • The initial query status is usually PENDING or RUNNING.
  • When the status changes to SUCCEEDED, the response contains the generated video URL.
  • If the status is FAILED, check the error message and retry the task.

submit_time *string* The time when the task was submitted. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

scheduled_time *string* The time when the task was executed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

end_time *string* The time when the task was completed. The time is in UTC+8 and the format is YYYY-MM-DD HH:mm:ss.SSS.

video_url *string* URL of the generated video. Returned only when task_status is SUCCEEDED. Valid for 24 hours. The video is in MP4 format with H.264 encoding.

orig_prompt *string* The original input prompt, corresponding to the request parameter prompt.

code *string* Error code. Returned only for failed requests. See Error messages.

message *string* Detailed error message. Returned only for failed requests. See Error messages.

 **usage** `*object*` Output statistics. Only successful results are counted.

Properties

input_video_duration *integer* Duration of the input video, in seconds.

output_video_duration *integer* Duration of the output video, in seconds.

duration *integer* Total video duration, used for billing.

SR *integer* Resolution of the output video.

ratio *string* Aspect ratio of the output video.

video_count *integer* Number of output videos. Fixed to 1.

request_id *string* Unique request identifier for tracing and troubleshooting.

Error codes ​

If the API call fails, see Error messages for troubleshooting.

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio