Vidu Reference to Video: R2V API Guide

Search “vidu reference to video” and you mostly get product pages: Vidu’s official feature page, a few aggregator model cards, some social clips. Almost none of them tell an engineer what the R2V API actually accepts, which model to call, or what it costs per second. This guide fills that gap.

R2V (reference-to-video) is the Vidu capability that generates a new video from one or more reference images — or reference videos — plus a text prompt, while keeping the referenced subject recognizable. It is not a single product: the same capability ships as a consumer feature on vidu.com, as an enterprise API on Vidu’s platform, and through third-party aggregators, each with its own request contract and billing. All API details below were read from the cited official documentation and model pages on August 10, 2026. Modellix is an API aggregator with a commercial interest in this topic; the guide treats Vidu’s own surfaces as the neutral baseline and does not claim the aggregator route is cheaper.

What Vidu reference to video (R2V) actually does

Vidu’s official reference-to-video page describes the mechanism precisely: you upload one or more characters, objects, or scenes as references, add a text prompt describing what should happen, and Vidu generates a multi-shot video in which the referenced subjects stay consistent across scenes. A reference can capture character, style, composition, camera movement, scene, and effects. The consumer product supports up to seven references per generation, optionally drawing from Vidu’s RefHub library of pre-made references.

The distinction from image-to-video (I2V) matters when you design a feature. I2V animates a single start frame; R2V keeps a subject consistent while placing it in a new scene defined by the prompt. The official page frames it as: use R2V for storytelling, ads, and multi-scene workflows; use I2V when you just want to animate one image. The same boundary shows up in the API: an R2V request takes reference_images (plural, up to seven) rather than a single image, and the prompt drives the scene rather than describing a motion on top of a fixed frame.

That maps to concrete jobs: character-driven short films where an actor must stay recognizable, brand mascot and spokesperson videos, e-commerce teams reusing a product’s look across ad variants, and pre-visualization where a fixed subject performs new actions. If you are evaluating R2V generically, our reference-to-video AI overview covers the wider field of R2V models and vendors; the rest of this guide stays API-first on Vidu.

The R2V input contract: reference images (1–7) and a prompt in, a subject-consistent video out. Illustrative Modellix diagram, August 10, 2026.

Which Vidu model is the R2V model? Q1, Q2, or Q3

The most confusing part of this topic is that “the R2V model” does not exist — R2V is a capability that ships in successive Vidu generations, and each generation has its own routing, parameters, and price.

Generation	R2V status	Evidence (accessed 2026-08-10)
Q1	Introduced R2V; up to 7 image references	Civitai launch post for Vidu Q1 R2V, with pricing
Q2 / Q2 Pro	Q2 Pro R2V node; accepts images and reference videos	GMI Cloud node documentation
Q3	Current line: standard, Turbo, and Mix R2V	Modellix Vidu provider catalog

The Q2 generation is the one that quietly supports video references: the GMI Cloud node contract for Vidu Q2 Pro R2V documents image_urls (up to seven images) plus video_urls — one reference video of 8 seconds, or two videos of 5 seconds each — with duration from 1–8 seconds and a 2,000-character prompt cap. That matters if your use case is “match this character’s motion from a clip,” not just “keep this character’s face.”

The Q3 line is the current generation, exposed on Modellix with three R2V routes: vidu/viduq3-r2v (standard, cinematic), vidu/viduq3-turbo-r2v (faster, lower price), and vidu/viduq3-mix-r2v (blends features from multiple references, up to seven, for mixed-style consistency). Q3 R2V generates 3–16 second videos at 16:9, 9:16, or 1:1, at 540p/720p/1080p. If a model card says “reference to video 2.0” without a generation name, verify which generation it wraps — the parameters and the price both differ across Q1, Q2, and Q3.

What the R2V API request looks like

The request contract is small. A Vidu R2V call is: upload or reference images → submit an async job with a prompt → poll until the video is ready. The exact field names differ per route; the table below is the Vidu Q3 R2V contract from the API documentation and model page, which is representative of the family.

Field	Type	Required	Constraints
prompt	string	Yes	1–5,000 characters
reference_images	string[]	Yes	1–7 items; URLs or base64 data URIs
duration	integer	No	Minimum 3 seconds
aspect_ratio	string	No	16:9, 9:16, 1:1
resolution	string	No	540p, 720p, 1080p
seed	integer	No	Reproducibility

A minimal request body:

{
  "prompt": "the character from the reference image walks toward the camera in a rainy city street",
  "reference_images": [
    "https://cdn.example.com/character.jpg"
  ],
  "duration": 8,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}

Submission is asynchronous: POST to https://api.modellix.ai/api/v1/vidu/viduq3-r2v with a Bearer API key, and the response returns a task_id plus a get_result URL to poll until the task reaches a terminal state. The same submit-and-poll shape applies to most Vidu R2V routes; our image-to-video API guide walks the general async pattern in more depth.

import requests, time

API_KEY = "your-modellix-api-key"          # create one in the console
BASE = "https://api.modellix.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

resp = requests.post(
    f"{BASE}/vidu/viduq3-r2v",
    headers=HEADERS,
    json={
        "prompt": "the character walks toward the camera in a rainy city street",
        "reference_images": ["https://cdn.example.com/character.jpg"],
        "duration": 8,
        "aspect_ratio": "16:9",
        "resolution": "720p",
    },
)
resp.raise_for_status()
task_id = resp.json()["data"]["task_id"]

for _ in range(60):                       # poll with backoff in production
    state = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS).json()["data"]
    if state["status"] == "success":
        print(state["output"]["url"])     # generated video
        break
    time.sleep(5)

The vidu/viduq3-r2v model page on Modellix (captured August 10, 2026): the reference_images parameter accepts 1–7 portrait or subject images, and pricing is billed per second by resolution.

R2V pricing: per second, not per video

Vidu R2V is billed per second of output, and the per-second rate scales with resolution. The table below is the live pricing on the Vidu Q3 R2V model pages, read on August 10, 2026.

Route	540p	720p	1080p
vidu/viduq3-r2v	$0.0322/s	$0.0552/s	$0.0690/s
vidu/viduq3-turbo-r2v	$0.0184/s	$0.0460/s	$0.0598/s
vidu/viduq3-mix-r2v	—	$0.1104/s	$0.1219/s

To estimate a job: pick the route and resolution, multiply by duration. A 5-second, 720p clip on the standard route is 5 × $0.0552 = $0.28. The same clip at 1080p on the Mix route — the premium multi-reference option — is 5 × $0.1219 = $0.61. Turbo at 720p drops a 5-second clip to $0.23, which is why it is the default choice for iteration loops.

For context, other aggregators price Vidu R2V per run rather than per second: fal’s model page quotes $0.40 for a 4-second video (fal-ai/vidu/reference-to-video, ≈$0.10/s), and Atlas Cloud lists $0.20 per run for its Vidu Reference-to-Video 2.0. Those fixed prices bundle whatever resolution and duration the provider exposes, so they are not directly comparable to a per-second table — match route, duration, and resolution on both sides before comparing. For the mechanics of converting per-second prices into budgets, our PixVerse credit pricing breakdown shows the same analysis for another video vendor.

Official Platform, an aggregator, or Modellix: which route?

Three integration paths exist, and the right one depends on how many providers your product must support.

Route	What you get	What you manage
Vidu API Platform (platform.vidu.com)	Official console, upload flow, first-party contract and support	Vidu credit/balance, one vendor’s API, per-request key handling
Aggregator model pages (fal, Atlas Cloud, GMI Cloud, …)	Pay-per-run pricing, existing SDKs, one vendor’s Vidu models	One more vendor account; per-vendor request shapes and billing
Modellix	One API key across 12 providers, per-second pricing per model page, per-call logs with cost	One account, one billing surface

Choose the official platform when Vidu is your only video vendor and you want the first-party product surface. Choose an aggregator route when you are already on that platform. The Modellix case is different in one specific way: it exists to serve products that integrate multiple media providers — one key, one billing surface, and per-model pricing pages you can read before you commit. Its Vidu provider page lists the current Q3 R2V routes with parameter-level per-second pricing, and the catalog-wide video price starts at $0.0008 per second across providers. That last number is a catalog-wide starting point, not a Vidu R2V price — the R2V table in the previous section is the one to budget against.

Disclosure: Modellix is an API aggregator, and this section describes its own product. We are not claiming the aggregator route is cheaper or that it accepts every official parameter — verify the current model page and API documentation for the exact contract of the route you need before committing.

Common mistakes when integrating Vidu R2V

• Treating R2V as I2V. R2V creates a new scene from the prompt while preserving the subject; if you only want to animate a start frame, an I2V route is cheaper and faster.
• Passing more than seven references. The contract caps reference_images at seven (some routes, like Atlas Cloud’s, cap lower). Validate the count client-side so users get an immediate error instead of a provider rejection.
• Ignoring the duration floor. Q3 R2V requires a minimum of 3 seconds; a 2-second request is invalid.
• Picking the generation blindly. Q1, Q2, and Q3 R2V have different parameters, durations, and prices. Match the generation to the route you integrate — “reference to video 2.0” on one platform is not the same model as Q3 R2V on another.
• Not polling to a terminal state. Every R2V route is asynchronous. Treat pending as non-final, poll with backoff, set a timeout, and handle failure states explicitly — a job that never reaches success is not “still running” forever.
• Budgeting from a per-run price. Fixed per-run prices hide the resolution and duration assumptions. Compute per-second where available, or state the assumptions next to the number.

Frequently asked questions about the Vidu R2V API

What is Vidu reference to video?

R2V is the Vidu capability that generates a new video from one or more reference images (or reference videos) plus a text prompt, preserving the referenced subject’s identity — character, style, objects, scenes — across shots.

Can Vidu R2V take reference videos, or only images?

Both, depending on the generation. Q2 Pro R2V documents video_urls (one 8-second video or two 5-second videos) alongside image references. The consumer page also accepts reference videos. The Q3 R2V routes document image references; check the route’s contract for video input.

Which Vidu model should I call for reference to video?

For current-generation routing, the Q3 line: vidu/viduq3-r2v for standard quality, vidu/viduq3-turbo-r2v for faster and cheaper iteration, and vidu/viduq3-mix-r2v when blending features from multiple references. Older Q1/Q2 R2V routes still exist on some platforms.

How much does Vidu R2V cost?

Per second of output, by resolution. On the per-second routes (August 10, 2026): standard Q3 R2V at $0.0322/s (540p), $0.0552/s (720p), $0.0690/s (1080p); Turbo cheaper; Mix premium. Some aggregators bill per run instead — fal quotes $0.40 per 4-second video, Atlas Cloud $0.20 per run.

How do I pass reference images to the API?

Submit them as reference_images in the request body — up to seven, as URLs or base64 data URIs — together with a prompt, then poll the returned task until the video is ready.

Is Vidu free to use?

Vidu’s consumer site offers free-to-create credits; the API routes are paid per generation or per second. Vidu is developed by Shengshu Technology, a Chinese AI company, which is a relevant due-diligence data point for teams with data-residency requirements.

How do I get started with the R2V API?

Pick a route, read its model page for the exact contract and per-second pricing, then run one request. On Modellix, registration takes about 30 minutes to first output, with $10–30 of free credit and no card required.

---

Vidu capability, generation, and pricing details reflect official documentation and model pages accessed August 10, 2026 and change frequently — Vidu ships new generations often. Validate against the live provider documentation and billing pages before committing volume or budget. Modellix is an API aggregator for image and video models, not the Vidu vendor; this guide is not a claim that the aggregator route is cheaper or that it accepts every official parameter.

Cover image: illustrative Modellix artwork; it is not a Vidu product screenshot or source evidence.