BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
HappyHorse - Gere um vídeo a partir de imagens de referência
Enviar HappyHorse tarefa de referência ao vídeo
Gere vídeos de até 15 segundos em 1080P a partir de 1 a 9 imagens de referência usando o HappyHorse modelo. Forneça várias imagens de referência e um prompt de texto para gerar um vídeo que combine assuntos das imagens em uma cena. Usar [Image 1], [Image 2], etc. no prompt para referenciar imagens por ordem no media matriz.
OpenAPI
openapi: 3.1.0
info:
title: HappyHorse Reference-to-Video API
description: The HappyHorse reference-to-video model lets you provide multiple reference images and a text prompt to generate a video that combines subjects from the images into a scene based on the prompt. Submit a task asynchronously, then poll `GET /tasks/{task_id}` for the result.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com/api/v1
description: Singapore
security:
- BearerAuth: []
paths:
/services/aigc/video-generation/video-synthesis:
post:
operationId: createHappyHorseRefToVideo
summary: Create reference-to-video task
description: Submit a reference-to-video task. Returns a `task_id` for polling.
parameters:
- name: X-DashScope-Async
in: header
required: true
description: Must be set to `enable` for asynchronous task submission.
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/HappyHorseRefToVideoRequest"
responses:
"200":
description: Task submitted successfully
content:
application/json:
schema:
$ref: "#/components/schemas/AsyncTaskSubmitResponse"
"400":
description: Invalid request parameters
content:
application/json:
schema:
$ref: "#/components/schemas/DashScopeErrorResponse"
x-codeSamples:
- lang: curl
label: cURL - Reference-to-video (multi-image)
source: |-
curl --location 'https://maas.qwencloudapi.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.1-r2v",
"input": {
"prompt": "The woman in the red qipao from [Image 1] is first framed in a profile medium shot, highlighting the tailored cut and S-curve silhouette of the dress. The camera then cuts to a low-angle upward shot, capturing the moment she gracefully raises her hand to unfold the folding fan from [Image 2], while the tassel earrings from [Image 3] sway delicately with the turn of her head.",
"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
}
}'
- lang: python
label: Python - Synchronous call
source: |-
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_sync_call():
print('Please wait...')
rsp = VideoSynthesis.call(
api_key=api_key,
model='happyhorse-1.1-r2v',
prompt='The woman in the red qipao from [Image 1] is first framed in a profile medium shot, highlighting the tailored cut and S-curve silhouette of the dress.',
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"
}
],
resolution='720P',
ratio='16:9',
duration=5)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.video_url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_sync_call()
- lang: python
label: Python - Asynchronous call
source: |-
import os
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
api_key = os.getenv("DASHSCOPE_API_KEY")
def sample_async_call():
rsp = VideoSynthesis.async_call(
api_key=api_key,
model='happyhorse-1.1-r2v',
prompt='The woman in the red qipao from [Image 1] is first framed in a profile medium shot, highlighting the tailored cut and S-curve silhouette of the dress.',
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"
}
],
resolution='720P',
ratio='16:9',
duration=5)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print("task_id: %s" % rsp.output.task_id)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
rsp = VideoSynthesis.wait(task=rsp, api_key=api_key)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.video_url)
else:
print('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
sample_async_call()
- lang: java
label: Java - Synchronous call
source: |-
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.*;
public class HappyHorseR2V {
static {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
}
public static void main(String[] args) {
try {
VideoSynthesis vs = new VideoSynthesis();
List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>() {{
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg")
.type("reference_image").build());
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg")
.type("reference_image").build());
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg")
.type("reference_image").build());
}};
Map<String, Object> parameters = new HashMap<>();
parameters.put("resolution", "720P");
parameters.put("ratio", "16:9");
parameters.put("duration", 5);
VideoSynthesisParam param = VideoSynthesisParam.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.model("happyhorse-1.1-r2v")
.prompt("The woman in the red qipao from [Image 1] is first framed in a profile medium shot, highlighting the tailored cut and S-curve silhouette of the dress.")
.media(media)
.parameters(parameters)
.build();
System.out.println("Please wait...");
VideoSynthesisResult result = vs.call(param);
System.out.println(JsonUtils.toJson(result));
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
}
}
- lang: java
label: Java - Asynchronous call
source: |-
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesis;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisParam;
import com.alibaba.dashscope.aigc.videosynthesis.VideoSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
import java.util.*;
public class HappyHorseR2V {
static {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
}
public static void main(String[] args) {
try {
String apiKey = System.getenv("DASHSCOPE_API_KEY");
VideoSynthesis vs = new VideoSynthesis();
List<VideoSynthesisParam.Media> media = new ArrayList<VideoSynthesisParam.Media>() {{
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg")
.type("reference_image").build());
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/fvuihk/hh-v2v2-folding-fan.jpg")
.type("reference_image").build());
add(VideoSynthesisParam.Media.builder()
.url("https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/imerii/hh-v2v-earrings.jpg")
.type("reference_image").build());
}};
Map<String, Object> parameters = new HashMap<>();
parameters.put("resolution", "720P");
parameters.put("ratio", "16:9");
parameters.put("duration", 5);
VideoSynthesisParam param = VideoSynthesisParam.builder()
.apiKey(apiKey)
.model("happyhorse-1.1-r2v")
.prompt("The woman in the red qipao from [Image 1] is first framed in a profile medium shot, highlighting the tailored cut and S-curve silhouette of the dress.")
.media(media)
.parameters(parameters)
.build();
VideoSynthesisResult task = vs.asyncCall(param);
System.out.println(JsonUtils.toJson(task));
System.out.println("Please wait...");
VideoSynthesisResult result = vs.wait(task, apiKey);
System.out.println(JsonUtils.toJson(result));
} catch (ApiException | NoApiKeyException | InputRequiredException e) {
System.out.println(e.getMessage());
}
}
}
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: DashScope API Key. Get one from the [QwenCloud console](https://home.qwencloud.com/api-keys).
schemas:
HappyHorseRefToVideoRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: The model name. For available models, see the [QwenCloud console](https://home.qwencloud.com).
example: happyhorse-1.1-r2v
input:
type: object
required:
- prompt
- media
description: Input content including reference images and text prompt.
properties:
prompt:
type: string
description: Text prompt describing the desired video. Use `[Image 1]`, `[Image 2]`, etc. to reference images in the `media` array (order matches array order). You must specify the object from the reference image, for example, "the woman in a red qipao from [Image 1]". Supports any language. Maximum 5,000 non-Chinese characters or 2,500 Chinese characters (auto-truncated if exceeded).
example: The woman in the red qipao from [Image 1] stands elegantly.
media:
type: array
description: "List of reference images (1-9). The array order defines the image reference order in the `prompt`: the first `reference_image` maps to `[Image 1]`, the second to `[Image 2]`, and so on."
items:
type: object
required:
- type
- url
properties:
type:
type: string
description: "Media asset type. Fixed value: `reference_image`."
enum:
- reference_image
url:
type: string
format: uri
description: |-
URL or Base64-encoded data of the reference image.
**Public URL**: HTTP/HTTPS (e.g., `https://xxx/xxx.jpg`).
**Base64**: `data:{MIME_type};base64,{base64_data}` (supported MIME types: `image/jpeg`, `image/png`, `image/webp`).
Image constraints: Formats: JPEG, JPG, PNG, WEBP. Shortest side at least 400 px (720P+ recommended). File size: up to 20 MB.
minItems: 1
maxItems: 9
parameters:
$ref: "#/components/schemas/HappyHorseRefToVideoParameters"
HappyHorseRefToVideoParameters:
type: object
description: Video generation parameters.
properties:
resolution:
type: string
description: Video clarity tier. Higher resolution costs more.
enum:
- 480P
- 720P
- 1080P
default: 1080P
ratio:
type: string
description: Aspect ratio of the generated video.
enum:
- 16:9
- 9:16
- 1:1
- 4:3
- 3:4
- 4:5
- 5:4
- 9:21
- 21:9
default: 16:9
duration:
type: integer
description: Video duration in seconds (integer, 3-15). Longer videos cost more -- billing is per second.
minimum: 3
maximum: 15
default: 5
watermark:
type: boolean
description: 'Whether to add a watermark to the generated video. `true` (default): adds a "Happy Horse" watermark in the bottom-right corner. `false`: no watermark.'
default: true
seed:
type: integer
description: Seed for reproducible results. Same seed + same parameters produces similar (not identical) output.
minimum: 0
maximum: 2147483647
AsyncTaskSubmitResponse:
type: object
description: Response from an asynchronous task submission.
properties:
request_id:
type: string
description: Unique request identifier for tracing and troubleshooting.
example: 4909100c-7b5a-9f92-bfe5-xxxxxx
output:
type: object
properties:
task_id:
type: string
description: Task ID for polling status. Use with `GET /tasks/{task_id}`.
example: 0385dc79-5ff8-4d82-bcb6-xxxxxx
task_status:
type: string
description: Initial task status, typically `PENDING`.
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
HappyHorseR2VTaskStatusResponse:
type: object
description: Task status response for HappyHorse reference-to-video.
properties:
request_id:
type: string
description: Request ID for troubleshooting. Include this when contacting support.
output:
type: object
properties:
task_id:
type: string
description: Task ID. Queryable for 24 hours after submission.
task_status:
type: string
description: "Task lifecycle: `PENDING` -> `RUNNING` -> `SUCCEEDED` or `FAILED`. `CANCELED` if manually stopped. `UNKNOWN` if expired."
enum:
- PENDING
- RUNNING
- SUCCEEDED
- FAILED
- CANCELED
- UNKNOWN
submit_time:
type: string
description: When the task was submitted (UTC+8, `YYYY-MM-DD HH:mm:ss.SSS`).
scheduled_time:
type: string
description: When the task started executing (UTC+8, `YYYY-MM-DD HH:mm:ss.SSS`).
end_time:
type: string
description: When the task finished (UTC+8). Only present for `SUCCEEDED` or `FAILED` tasks.
orig_prompt:
type: string
description: Your original prompt text.
video_url:
type: string
format: uri
description: URL of the generated video (MP4, H.264 encoding). Only present when `task_status` is `SUCCEEDED`. **Valid for 24 hours** -- download promptly.
code:
type: string
description: Error code. Only present when `task_status` is `FAILED`.
message:
type: string
description: Error message. Only present when `task_status` is `FAILED`.
usage:
type: object
description: Resource consumption. Only present when `task_status` is `SUCCEEDED`.
properties:
duration:
type: number
description: Billable video duration in seconds.
input_video_duration:
type: integer
description: Always `0` for reference-to-video (no input video).
output_video_duration:
type: integer
description: Output video duration in seconds.
video_count:
type: integer
description: Number of videos generated. Always `1`.
ratio:
type: string
description: Aspect ratio of the generated video.
SR:
type: integer
description: Resolution tier used (e.g., `720` for 720P, `1080` for 1080P).
DashScopeErrorResponse:
type: object
description: DashScope API error response.
properties:
request_id:
type: string
description: Unique request identifier for tracing and support.
code:
type: string
description: Machine-readable error code (e.g., `InvalidParameter`, `Throttling`, `Unauthorized`).
example: InvalidParameter
message:
type: string
description: Human-readable error message.
example: Invalid model name