Reference-to-Video
Generate video from 1–9 reference images, referencing them in the prompt with [Image N]. Supports up to 15 seconds and 1080P resolution. This is an async task-based API: submit a request to receive a task_id, poll for status, then download the video when complete.
Base URL
https://api.autorouter.top— Production
Authentication
BearerAuth: http (bearer)
Authenticate using a Bearer Token.
Format: Authorization: Bearer sk-xxxxxx
Endpoints
POST /api/v1/services/aigc/video-generation/video-synthesis
Create Video Generation Task
Create a video generation task from reference images.
The request header must include X-DashScope-Async: enable.
Request Body
Content-Type: application/json
Example:
{
"model": "happyhorse-1.1-r2v",
"input": {
"prompt": "The woman in a red cheongsam in [Image 1], the camera first frames her fitted silhouette and S-curve from a side mid-shot, then switches to a low-angle shot as she raises her hand to open the folding fan in [Image 2], while the tassel earrings in [Image 3] sway lightly with her head turn, finally pushing in to a facial close-up that holds on her fingertip resting on the fan ribs and the subtle expression in her eyes, showcasing oriental charm from multiple angles.",
"media": [
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
}
]
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5
}
}Properties:
| Name | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model name. Available values: happyhorse-1.1-r2v, happyhorse-1.0-r2v |
input | object | Yes | Basic input such as reference images and prompt |
input.prompt | string | Yes | Text prompt describing elements and visual traits of the generated video. Supports any language. Maximum 5,000 non-Chinese characters or 2,500 Chinese characters. Use placeholders like [Image 1] and [Image 2] to refer to images in the media array; numbering matches array order (first image is [Image 1], and so on) |
input.media | array | Yes | Reference image list. Provide 1–9 images. See details below |
input.media[].type | string | Yes | Media type. Fixed value: reference_image |
input.media[].url | string | Yes | Reference image URL or Base64-encoded data. See details below |
parameters | object | No | Video processing parameters such as resolution, aspect ratio, and duration |
parameters.resolution | string | No | Resolution tier. Available values: 480P, 720P, 1080P (default) |
parameters.ratio | string | No | Aspect ratio. Available values: 16:9 (default), 9:16, 3:4, 4:3, 4:5, 5:4, 1:1, 9:21, 21:9 |
parameters.duration | integer | No | Video duration in seconds. Integer in [3, 15]. Default: 5 |
parameters.watermark | boolean | No | Whether to add a watermark (fixed text "Happy Horse" in the bottom-right corner). true (default) adds it; false does not |
parameters.seed | integer | No | Random seed in [0, 2147483647]. Auto-generated if omitted. A fixed seed improves reproducibility but does not guarantee identical results |
inputobject(Required)
Basic input such as reference images and prompt.
Reference image list. Provide 1–9 images. The first reference_image maps to [Image 1], the second to [Image 2], and so on.
Media type. Fixed value: reference_image.
Reference image URL or Base64-encoded data.
Image constraints:
- Format: JPEG, JPG, PNG, WEBP.
- Resolution: The short side must be at least 400 pixels. Prefer 720P or higher; avoid tiny, blurry, or heavily compressed images, which may hurt output quality.
- File size: Maximum 20MB.
Supported input formats:
- Public URL: HTTP or HTTPS. Example:
https://xxx/xxx.jpg - Base64-encoded image string: Format
data:{MIME_type};base64,{base64_data}. Example:data:image/png;base64,GDU7MtCZzEbTbmRZ......
Responses
200: Task created successfully
Content-Type: application/json
400: Bad request / invalid parameters
Content-Type: application/json
429: Rate limit exceeded
Content-Type: application/json
Request Example
curl -X POST "https://api.autorouter.top/api/v1/services/aigc/video-generation/video-synthesis" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk-xxxxxx" \
-H "X-DashScope-Async: enable" \
-d '{
"model": "happyhorse-1.1-r2v",
"input": {
"prompt": "The woman in a red cheongsam in [Image 1], the camera first frames her fitted silhouette and S-curve from a side mid-shot, then switches to a low-angle shot as she raises her hand to open the folding fan in [Image 2], while the tassel earrings in [Image 3] sway lightly with her head turn, finally pushing in to a facial close-up that holds on her fingertip resting on the fan ribs and the subtle expression in her eyes, showcasing oriental charm from multiple angles.",
"media": [
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg"
},
{
"type": "reference_image",
"url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg"
}
]
},
"parameters": {
"resolution": "720P",
"ratio": "16:9",
"duration": 5
}
}'Response Example
{
"output": {
"task_status": "PENDING",
"task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
},
"request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}Response fields:
| Name | Type | Description |
|---|---|---|
output | object | Task output |
output.task_id | string | Task ID for status queries. Valid for 24 hours |
output.task_status | string | Task status. Enum: PENDING (queued), RUNNING (processing), SUCCEEDED (success), FAILED (failed), CANCELED (canceled), UNKNOWN (missing or unknown) |
request_id | string | Unique request ID for tracing and troubleshooting |
code | string | Error code. Returned only when the request fails |
message | string | Error message. Returned only when the request fails |
GET /api/v1/tasks/{task_id}
Query Task Result by ID
Query task status and result using the task_id returned when creating the task. Queries are valid for 24 hours.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Request authentication. Format: Bearer sk-xxxxxx |
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
task_id | string | Yes | Task ID |
Responses
200: Task queried successfully
Content-Type: application/json
400: Bad request / invalid parameters
Content-Type: application/json
429: Rate limit exceeded
Content-Type: application/json
Request Example
curl -X GET "https://api.autorouter.top/api/v1/tasks/{task_id}" \
-H "Authorization: Bearer sk-xxxxxx"Response Example
{
"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": "The woman in a red cheongsam in [Image 1]...",
"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"
}
}Response fields:
| Name | Type | Description |
|---|---|---|
output | object | Task output |
output.task_id | string | Task ID. Valid for queries for 24 hours |
output.task_status | string | Task status. Enum: PENDING (queued), RUNNING (processing), SUCCEEDED (success), FAILED (failed), CANCELED (canceled), UNKNOWN (missing or unknown). Typical poll flow: PENDING → RUNNING → SUCCEEDED / FAILED |
output.submit_time | string | Task submission time, format YYYY-MM-DD HH:mm:ss.SSS |
output.scheduled_time | string | Task execution time, format YYYY-MM-DD HH:mm:ss.SSS |
output.end_time | string | Task completion time, format YYYY-MM-DD HH:mm:ss.SSS |
output.video_url | string | Video download URL. Returned only when task_status is SUCCEEDED. Link valid for 24 hours; video is MP4 (H.264) |
output.orig_prompt | string | Original prompt, corresponding to the request prompt |
output.code | string | Error code. Returned only when the task fails |
output.message | string | Error message. Returned only when the task fails |
usage | object | Output statistics. Returned only on success |
usage.input_video_duration | integer | Input video duration in seconds |
usage.output_video_duration | integer | Output video duration in seconds |
usage.duration | integer | Total video duration used for billing, equal to input_video_duration + output_video_duration |
usage.SR | integer | Output video resolution tier |
usage.ratio | string | Aspect ratio of the generated video |
usage.video_count | integer | Number of output videos. Always 1 |
request_id | string | Unique request ID for tracing and troubleshooting |
Error Handling
HTTP 400 Parameter Errors (pre-submit validation, no billing)
AutoRouter validates required fields before submitting upstream:
| Scenario | Response |
|---|---|
Missing input.prompt | {"code":"InvalidParameter","message":"...","request_id":"..."} |
Missing input.media or reference count not in 1–9 | {"code":"InvalidParameter","message":"...","request_id":"..."} |
| Unknown model | {"code":"InvalidParameter","message":"unknown model: ...","request_id":"..."} |
HTTP 401 / 403 Auth Errors
401 Unauthorized: API Key invalid or expired403 Forbidden: API Key has no access to this model (check token's model allowlist)
HTTP 402 Insufficient Balance
Returns insufficient user quota. Top up at the AutoRouter console.
Task FAILED Status
The task was accepted but upstream generation failed (output.task_status == "FAILED"). See output.code / output.message for details:
| Reason | Suggested Action |
|---|---|
| Content moderation | Adjust prompt to avoid sensitive content |
| Missing or invalid reference images | media must contain 1–9 type: reference_image elements |
| Media URL unreachable | Ensure the URL is publicly accessible and not expired |
| Media file violates specs | See image limits in Request Body |
| Illegal parameter combo | Follow the Request Body specification |
When a task enters FAILED, AutoRouter automatically refunds the billed quota. Check refund records in the logs page.
Image-to-Video (First Frame)
Generate video from a first-frame image and optional prompt. Async task API: submit a request, receive a task_id, then poll for status to get the result.
Video Editing
Edit an existing video with style transfer, local replacement, and similar operations, optionally with 0–5 reference images. Output duration follows the input video (max 15 seconds). Supports up to 1080P resolution. This is an async task-based API: submit a request to receive a task_id, poll for status, then download the video when complete.