Reference-to-Video

Doc version：v1.0.0 | Last updated：2026-07-22
This platform fully supports the official Tongyi Wanxiang (Wan) video generation API. Requests and responses are transparently proxied; parameter semantics are identical to the official API.

Generate videos based on the subject (person, character, object, etc.) in reference images/videos, and use reference syntax in the prompt to specify the role of each reference asset. Suitable for serialized creation scenarios that require character consistency.

Reference-to-video involves two protocols with different request body structures — be careful to distinguish them:

Model	Protocol	Reference asset field	Prompt reference syntax	Resolution parameter	Audio	Multi-shot
`wan2.7-r2v`, `wan2.7-r2v-2026-06-12`	New	`input.media` (array of objects, type + url)	Chinese "图1 / 视频1", English "Image 1 / Video 1"; images and videos are counted separately	`parameters.resolution` (`720P`/`1080P`)	Generates videos with audio by default, no setting needed; supports `reference_voice` voice-tone reference	`shot_type` not supported; achieve multi-shot by writing a storyboard script in the prompt
`wan2.6-r2v`	Legacy	`input.reference_urls` (array of strings)	`character1`, `character2` (images and videos are counted together in array order)	`parameters.size` (widthheight, e.g. `1280720`)	`audio` parameter not supported (only the flash variant supports it)	`parameters.shot_type` (`single`/`multi`)
`wan2.6-r2v-flash`	Legacy	Same as `wan2.6-r2v`	Same as above	Same as above	Supports `audio` (true = with audio / false = silent)	Same as above

⚠️ Important: the reference asset field for wan2.6-r2v is reference_urls (an array, mixing images and videos). The legacy field reference_video_urls is deprecated, and made-up field names (such as ref_imgs) are rejected outright by the official API with the error please provide reference_video_urls or reference_urls.

Prompt Reference Syntax

Reference assets are referenced by number in the prompt; the number matches the asset's position in the array:

wan2.7-r2v (images and videos counted separately)

In Chinese, use "图1、图2" to refer to reference images and "视频1、视频2" to refer to reference videos; in English, write Image 1, Video 1 (space between word and number, first letter capitalized).

The 1st reference_image is "Image 1", and the 1st reference_video is "Video 1"; both can be present at the same time.

If there is only one image / one video, you can simply write "the reference image" / "the reference video".

Both phrasings are supported: "[Image 1] playing inside [Image 2]" and "the cat from [Image 1] playing in the room from [Image 2]".

When the reference image is a multi-panel grid (storyboard), it is recommended to describe it as a storyboard script, and pass only one multi-panel image per request.

wan2.6-r2v (counted together)

Use character1, character2 to reference the reference characters: the 1st URL in the reference_urls array is character1, the 2nd is character2, and so on (no distinction between images and videos).

Each reference asset should contain only a single character.

Create Task

POST https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis

Request Headers

Parameter	Type	Required	Default	Description
`Content-Type`	string	Yes	application/json	Data exchange format
`Authorization`	string	Yes		Authentication, `Bearer {API_KEY}`

The X-DashScope-Async: enable header required by the official API is automatically added by the platform — no need to include it in your request.

Request Body — wan2.7-r2v (new protocol)

Parameter	Type	Required	Default	Description
`model`	string	Yes		`wan2.7-r2v` or `wan2.7-r2v-2026-06-12`
`input.prompt`	string	Yes		Prompt, Chinese or English, ≤5000 characters (truncated if longer) See "Prompt Reference Syntax" above for reference syntax
`input.negative_prompt`	string	No		Negative prompt, ≤500 characters
`input.media`	array of object	Yes		Array of reference assets. At most 1 first-frame image; at least 1 reference image + reference video and no more than 5 in total; when an asset serves as a subject character it should contain only a single character
`input.media[].type`	string	Yes		Asset type: `reference_image` — reference image (subject character / scene reference) `reference_video` — reference video (subject character + voice-tone reference; empty establishing shots are not recommended) `first_frame` — first-frame image (can be combined with subject references for joint control)
`input.media[].url`	string	Yes		Asset location. Images support public HTTP(S) URLs or Base64 (`data:{MIME_type};base64,{data}`); videos support public HTTP(S) URLs
`input.media[].reference_voice`	string	No		Audio URL specifying the voice tone of this asset's subject character (voice tone reference only, unrelated to spoken content). If the reference video contains audio and this is not specified, the video's original audio is used by default; if both are provided, `reference_voice` takes precedence. It is recommended that the audio language match the prompt language
`parameters.resolution`	string	No	1080P	Resolution tier, options `720P`/`1080P`; affects cost
`parameters.ratio`	string	No	16:9	Aspect ratio, options `16:9`/`9:16`/`1:1`/`4:3`/`3:4` Automatically ignored when a first-frame image is provided; the output uses an approximate ratio based on the first frame's aspect ratio
`parameters.duration`	integer	No	5	Video duration in seconds; affects cost Integer in 2–10 when reference assets include a video; integer in 2–15 when they do not
`parameters.prompt_extend`	boolean	No	true	Intelligent prompt rewriting; noticeable improvement for short prompts, but increases processing time
`parameters.watermark`	boolean	No	false	"AI-generated" watermark in the bottom-right corner
`parameters.seed`	integer	No	Random	Range [0, 2147483647]; identical seeds still do not guarantee identical results

Request Body — wan2.6-r2v (legacy protocol)

Parameter	Type	Required	Default	Description
`model`	string	Yes		`wan2.6-r2v` or `wan2.6-r2v-flash`
`input.prompt`	string	Yes		Prompt, ≤1500 characters Use `character1`, `character2` to reference the reference characters (counted together in array order)
`input.negative_prompt`	string	No		Negative prompt, ≤500 characters
`input.reference_urls`	array of string	Yes		Array of reference file URLs, mixing images and videos: 0–5 images, 0–3 videos, images + videos ≤ 5 in total; affects cost ⚠️ The legacy field `reference_video_urls` is deprecated — do not use it
`parameters.size`	string	No	1920*1080	Output resolution; must be specified as exact pixels "widthheight" (not `1:1` or `720P`); affects cost 720P tier: `1280720`(16:9), `7201280`(9:16), `960960`(1:1), `1088832`(4:3), `8321088`(3:4) 1080P tier: `19201080`(16:9), `10801920`(9:16), `14401440`(1:1), `16321248`(4:3), `1248*1632`(3:4)
`parameters.duration`	integer	No	5	Video duration in seconds, integer in 2–10; affects cost
`parameters.shot_type`	string	No	single	Shot type: `single` single shot / `multi` multi-shot; takes precedence over descriptions in the prompt
`parameters.audio`	boolean	No	true	Only supported by `wan2.6-r2v-flash`. `true` with audio / `false` silent (must be explicitly set to false to generate a silent video); affects cost
`parameters.watermark`	boolean	No	false	"AI-generated" watermark in the bottom-right corner
`parameters.seed`	integer	No	Random	Range [0, 2147483647]

Reference Asset Constraints

Asset	Count	Format	Dimensions / Duration	Size
Reference image	wan2.7: images + videos ≤ 5 in total; wan2.6: 0–5 images and images + videos ≤ 5 in total	JPEG, JPG, PNG (alpha channel not supported), BMP, WEBP	Width/height 240–8000 px; wan2.7 requires aspect ratio 1:8–8:1	≤ 20MB
Reference video	wan2.7: images + videos ≤ 5 in total; wan2.6: 0–3 videos	MP4, MOV	Duration 1–30 seconds; wan2.7 requires width/height 240–4096 px and aspect ratio 1:8–8:1	≤ 100MB
First-frame image (wan2.7 `first_frame` only)	At most 1	Same as reference image	Same as reference image	≤ 20MB
Reference audio (wan2.7 `reference_voice` only)	1 per asset	WAV, MP3	Duration 1–10 seconds	≤ 15MB

Billing Notes

Billing is based on usage.duration in the query result: duration = input reference video duration + output video duration. That is, when a reference video is provided, its duration also counts toward the billed duration (e.g. a 5-second input reference video + 10-second output is billed as 15 seconds). With image-only reference input, input_video_duration is 0.

Parameters that affect cost: resolution (wan2.7's resolution / wan2.6's size; 1080P costs more than 720P), duration, reference assets (wan2.6's reference_urls), and audio (wan2.6-r2v-flash only; with-audio and silent are priced differently).

Request Example — wan2.7-r2v

curl --request POST \
  --url 'https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan2.7-r2v",
    "input": {
      "prompt": "The woman from Image 1 strolling gracefully through a garden, her dress swaying gently in the breeze",
      "media": [
        {
          "type": "reference_image",
          "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
        }
      ]
    },
    "parameters": {
      "resolution": "1080P",
      "duration": 5
    }
  }'

Request Example — wan2.6-r2v

curl --request POST \
  --url 'https://platform.dataeyes.ai/ali/api/v1/services/aigc/video-generation/video-synthesis' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan2.6-r2v",
    "input": {
      "prompt": "The person from character1 strolling along a path covered with autumn leaves",
      "reference_urls": [
        "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260424/mvzfud/hh-v2v-girl.jpg"
      ]
    },
    "parameters": {
      "size": "1280*720",
      "duration": 5
    }
  }'

Response Example

Success:

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

Failed:

{
  "code": "InvalidParameter",
  "message": "please provide reference_video_urls or reference_urls",
  "request_id": "7438d53d-xxxx"
}

Response Fields

Field	Type	Description
`output.task_id`	string	Task ID, used for polling; valid for 24 hours
`output.task_status`	string	Task status, `PENDING` on successful creation
`request_id`	string	Unique request identifier
`code` / `message`	string	Error code and details, returned only when creation fails

Query Task

Poll the task status with the task_id returned by task creation; once successful, get the video URL from output.video_url:

GET https://platform.dataeyes.ai/ali/api/v1/tasks/{task_id}

See 09-Query-Task for details.

03-Reference-to-Video

Reference-to-Video#

Prompt Reference Syntax#

Create Task#

Request Headers#

Request Body — wan2.7-r2v (new protocol)#

Request Body — wan2.6-r2v (legacy protocol)#

Reference Asset Constraints#

Billing Notes#

Request Example — wan2.7-r2v#

Request Example — wan2.6-r2v#

Response Example#

Response Fields#

Query Task#