Get API Key Get API
Docs

Wan2.7-R2V Reference-to-Video

- Alibaba Cloud Wanxiang 2.7 reference-to-video model

  • Generate a new video with consistent style, characters, and scenes based on one or more reference images/videos
  • Supports character consistency, style transfer, and multi-asset combination
  • Supports reference voice (reference_voice) to control character voice

Request example

curl --request POST \
  --url https://api.openveer.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "wan2.7-r2v",
    "prompt": "This person walks down the street surrounded by heavy traffic",
    "image_with_roles": [{"url": "https://cdn.example.com/character.jpg", "role": "reference_image"}],
    "resolution": "1080P",
    "duration": 8
  }'

Response example

{
  "code": 200,
  "data": [
    {
      "status": "submitted",
      "task_id": "task_01J9HA7JPQ9A0Z6JZ3V8M9W6PZ"
    }
  ]
}

Authorization

Authorization string

All API endpoints require Bearer Token authentication

Get your API Key:

Visit the API Key Management Page to get your API Key

Add it to the request header:

Authorization: Bearer YOUR_API_KEY

Request Parameters

model string

Video generation model name, fixed as wan2.7-r2v

nsfw_check boolean

Whether to run content moderation before submitting the video task.

  • true: use omni-moderation-latest to review prompts and input images
  • false or omitted: do not send a moderation request, adding no moderation cost or latency (default)
prompt string

Video content description, up to 5000 characters

For multiple images/videos, use "image 1", "image 2", "video 1", etc. to reference the corresponding reference assets (in order of input)

Example: "The character in image 1 enters the scene in image 2 and looks around"

image_with_roles string

">
Image array with roles; at least one of this and video_urls must be provided

Fields for each object:

  • url (string): image URL
  • role (string): image role
    • reference_image - reference image (default)
    • first_frame - specified first frame (when provided, size is ignored and the aspect ratio follows the first-frame image)
  • reference_voice (string, optional): voice sample audio URL for that reference character, used to control the character's voice in the generated video

Example:

[
  {
    "url": "https://cdn.example.com/character.jpg",
    "role": "reference_image",
    "reference_voice": "https://cdn.example.com/voice_sample.mp3"
  },
  { "url": "https://cdn.example.com/start.jpg", "role": "first_frame" }
]
video_urls string

">
Reference video URL array, up to 5 videos (total images + videos ≤ 5)

At least one of this and image_with_roles must be provided

Note



Video constraints:

* Format: mp4, mov
* Duration: 1–30s
* Resolution: width and height in the range \[240, 4096] pixels
* Aspect ratio: 1:8 – 8:1
* File size: up to 100MB

negative_prompt string

Negative prompt describing unwanted content, up to 500 characters

resolution string

Video resolution

Options:

  • 720P - Standard
  • 1080P - High definition (default)
duration integer

Video duration (seconds)

Supported range: 2 \~ 15 seconds

Default: 5

Warning



When the reference assets include a video: an integer between [2, 10].

When the reference assets do not include a video: an integer between \[2, 15].

size string

Aspect ratio

Supported formats:

  • 16:9 - Landscape widescreen (default)
  • 9:16 - Portrait
  • 1:1 - Square
  • 4:3 - Landscape
  • 3:4 - Portrait

Warning



When first_frame is provided via image_with_roles, this parameter is ignored and the aspect ratio follows the first-frame image

prompt_extend boolean

Whether to enable intelligent prompt rewriting

Significantly improves results for short prompts, but increases processing time

Default: true

watermark boolean

Whether to add "AI Generated" watermark to the generated video

  • true: add watermark
  • false: no watermark (default)
seed integer

Seed integer used to control the randomness of generated content

Value range: integer ≥0

Note



* For identical requests, the model generates different results when receiving different seed values (e.g., omitting seed)

* For identical requests, the model generates similar results when receiving the same seed value, but exact consistency is not guaranteed

Response

code integer

Response status code, 200 on success

data array
Response data array
status string

Task status, submitted when initially submitted

task_id string

Unique task identifier

Use Cases

Case 1: Single Reference Image (Simplest)

{
  "model": "wan2.7-r2v",
  "prompt": "This person walks down the street surrounded by heavy traffic",
  "image_with_roles": [
    { "url": "https://cdn.example.com/character.jpg", "role": "reference_image" }
  ]
}

Case 2: Multiple Reference Images

{
  "model": "wan2.7-r2v",
  "prompt": "The character in image 1 enters the scene in image 2 and mimics the pose in image 3",
  "image_with_roles": [
    { "url": "https://cdn.example.com/person.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/background.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/pose.jpg", "role": "reference_image" }
  ],
  "resolution": "1080P",
  "duration": 8,
  "size": "16:9"
}

Case 3: Generation Based on Reference Video

{
  "model": "wan2.7-r2v",
  "prompt": "Generate a beach sunset scene in the style of the reference video",
  "video_urls": ["https://cdn.example.com/style_reference.mp4"],
  "resolution": "720P",
  "duration": 8
}

Case 4: Specified First Frame + Reference Image

{
  "model": "wan2.7-r2v",
  "prompt": "The reference character starts from this position and walks forward",
  "image_with_roles": [
    { "url": "https://cdn.example.com/character.jpg", "role": "reference_image" },
    { "url": "https://cdn.example.com/start.jpg", "role": "first_frame" }
  ],
  "resolution": "1080P",
  "duration": 8
}

Case 5: Reference Image + Reference Voice (Precise)

{
  "model": "wan2.7-r2v",
  "prompt": "This person walks down the street while speaking",
  "image_with_roles": [
    {
      "url": "https://cdn.example.com/character.jpg",
      "role": "reference_image",
      "reference_voice": "https://cdn.example.com/voice_sample.mp3"
    }
  ],
  "resolution": "1080P",
  "duration": 10
}

Image Reference Rules

With multiple reference images, use numeric indices in the prompt to refer to them:

  • 1st image → "image 1" or "the first image"
  • 1st video → "video 1" or "the first video"
Note

Query Task Results

Video generation is an async task that returns a task_id upon submission. Use the Get Task Status endpoint to query generation progress and results.

This documentation is built and hosted on Mintlify, a developer documentation platform.