Veo 3.1 ref2v API: Transform Existing Videos with AI Style Prompts
You have a rough prototype clip — maybe a screencast walkthrough, a drone shot, or an animated storyboard — and you need to transform it into a polished output: different visual style, different rendering, same motion and composition. Re-generating from text means starting over and losing the motion structure you already have. Image-to-video (i2v) only uses the first frame, not the full motion sequence.
Veo 3.1's reference-video (ref2v) mode takes the full video as input alongside a text prompt and returns a new video that follows the motion structure of the reference while applying the style and content described in the prompt. This guide shows how to call the ref2v endpoint on GenRelay, handle async job polling, and understand where ref2v fits versus t2v and i2v.
What Is Veo 3.1 ref2v and How Is It Different from i2v?
Veo 3.1 supports three generation modes:
| Mode | Input | What the model uses |
|---|---|---|
| t2v (text-to-video) | Text prompt only | Generates motion and content from scratch |
| i2v (image-to-video) | First frame image + prompt | Animates from a static starting image |
| ref2v (reference-video-to-video) | Full video + prompt | Follows the reference video's motion structure while applying the prompt's style and content |
ref2v is the correct mode when motion fidelity matters: the reference video defines camera movement, subject motion, and timing. The text prompt drives the visual treatment — style, lighting, rendering, color grade. You get the composition of the reference with the aesthetic of the prompt.
Common use cases:
- Prototype animation → polished cinematic output
- Rough drone footage → stylized aerial b-roll
- Wireframe screen recording → product demo with clean UI rendering
- Low-budget shoot → professional grade footage transfer
How Do I Set Up Authentication?
Authentication is the same Bearer token pattern used across all GenRelay endpoints:
import os
import requests
import time
API_KEY = os.environ["GENRELAY_API_KEY"]
BASE_URL = "https://genrelay.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
Get your API key from the GenRelay console. The same key works for all video and image model endpoints.
How Do I Submit a ref2v Job to the Veo 3.1 API?
The ref2v job goes to the same /v1/videos/generations endpoint used for t2v and i2v, with the mode field set to "ref2v" and a video parameter containing the reference video encoded as base64.
Step 1 — Submit the job:
import base64
def submit_ref2v_job(
video_path: str,
prompt: str,
resolution: str = "720p",
duration: int = 8
) -> str:
"""Submit a Veo 3.1 ref2v job and return the job ID."""
with open(video_path, "rb") as f:
video_b64 = base64.b64encode(f.read()).decode("utf-8")
response = requests.post(
f"{BASE_URL}/videos/generations",
headers=HEADERS,
json={
"model": "veo-3.1",
"mode": "ref2v",
"prompt": prompt,
"video": video_b64,
"resolution": resolution,
"duration": duration
}
)
response.raise_for_status()
job = response.json()
print(f"Submitted ref2v job: {job['id']}")
return job["id"]
Supported parameters:
| Parameter | Values | Notes |
|---|---|---|
model |
"veo-3.1" |
Fixed for Veo 3.1 |
mode |
"ref2v" |
Selects reference-video mode |
prompt |
String | Describes the target style, rendering, content |
video |
Base64 string | MP4 or WebM, ≤50MB recommended |
resolution |
"720p", "1080p" |
Billing varies by resolution |
duration |
Integer (seconds) | Match or approximate the reference clip length |
How Do I Poll for Completion?
Veo 3.1 ref2v jobs are async — generation takes 30–120 seconds depending on clip length and resolution. Poll the job status endpoint until status is "completed" or "failed":
def poll_ref2v_job(job_id: str, poll_interval: int = 15, timeout: int = 300) -> str:
"""Poll until the ref2v job completes and return the output video URL."""
elapsed = 0
while elapsed < timeout:
response = requests.get(
f"{BASE_URL}/videos/generations/{job_id}",
headers=HEADERS
)
response.raise_for_status()
data = response.json()
status = data["status"]
if status == "completed":
url = data["output"]["url"]
print(f"ref2v complete: {url}")
return url
elif status == "failed":
raise RuntimeError(f"ref2v job failed: {data.get('error', 'unknown error')}")
else:
print(f"[{elapsed}s] Status: {status} — waiting {poll_interval}s")
time.sleep(poll_interval)
elapsed += poll_interval
raise TimeoutError(f"ref2v job {job_id} did not complete within {timeout}s")
Full end-to-end example:
import os
import requests
import base64
import time
API_KEY = os.environ["GENRELAY_API_KEY"]
BASE_URL = "https://genrelay.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def veo_ref2v(video_path: str, prompt: str, resolution: str = "720p", duration: int = 8) -> str:
# Submit
with open(video_path, "rb") as f:
video_b64 = base64.b64encode(f.read()).decode("utf-8")
r = requests.post(
f"{BASE_URL}/videos/generations",
headers=HEADERS,
json={"model": "veo-3.1", "mode": "ref2v", "prompt": prompt,
"video": video_b64, "resolution": resolution, "duration": duration}
)
r.raise_for_status()
job_id = r.json()["id"]
print(f"Job submitted: {job_id}")
# Poll
for attempt in range(40): # up to ~10 minutes
time.sleep(15)
status_r = requests.get(f"{BASE_URL}/videos/generations/{job_id}", headers=HEADERS)
status_r.raise_for_status()
data = status_r.json()
if data["status"] == "completed":
return data["output"]["url"]
if data["status"] == "failed":
raise RuntimeError(data.get("error", "generation failed"))
print(f"[attempt {attempt+1}] {data['status']}")
raise TimeoutError("Job timed out after 10 minutes")
# Usage
output_url = veo_ref2v(
"rough_prototype.mp4",
"Cinematic drone footage, golden hour warm light, subtle lens flare, 4K film grain",
resolution="1080p",
duration=8
)
print(f"Output: {output_url}")
How Does Veo 3.1 ref2v Handle Prompt Writing?
In ref2v mode, the prompt describes the target visual style rather than the scene content — the reference video already defines what happens. Effective ref2v prompts focus on:
- Rendering style: "photorealistic", "watercolor animation", "cinematic film grain", "clean product demo"
- Lighting treatment: "golden hour warm light", "soft studio diffusion", "dramatic chiaroscuro"
- Color grade: "desaturated with teal-orange grade", "warm vintage palette", "clean neutral white-balance"
- Camera feel: "handheld documentary", "smooth gimbal stabilized", "locked-off static"
Avoid re-describing the motion or content already present in the reference — the model uses the reference for that. Prompts that contradict the reference motion ("zooming in slowly" when the reference has a pan) will produce inconsistent results.
What Does Veo 3.1 ref2v Cost?
Pricing follows the same per-second structure as Veo 3.1 t2v and i2v:
| Resolution | Price per second |
|---|---|
| 720p | $0.060 / second |
| 1080p | $0.120 / second |
Workload examples:
| Clip length | Resolution | Cost per clip |
|---|---|---|
| 5 seconds | 720p | $0.30 |
| 8 seconds | 720p | $0.48 |
| 8 seconds | 1080p | $0.96 |
| 15 seconds | 720p | $0.90 |
| 15 seconds | 1080p | $1.80 |
For a 30-clip batch at 8 seconds, 720p: 30 × $0.48 = $14.40.
For comparison — transforming the same clip at 1080p: 30 × $0.96 = $28.80.
Use 720p for iteration and draft review. Switch to 1080p for final delivery.
Veo 3.1 Mode Comparison
| Dimension | t2v | i2v | ref2v |
|---|---|---|---|
| Input | Text prompt | Image + prompt | Video + prompt |
| Motion source | Model-generated | Model-generated (anchored to first frame) | Reference video |
| Style source | Prompt | Prompt | Prompt |
| Best for | Original content creation | Animating static images | Transforming existing clips |
| Pricing | Same | Same | Same |
The pricing structure is identical across modes. The mode you choose depends entirely on what input you have and how much control you need over the motion.
For i2v details, see the Veo 3.1 image-to-video API guide. For the full tutorial covering all three modes with audio generation, see the Veo 3.1 API tutorial.
FAQ
What video formats does the ref2v endpoint accept?
MP4 (H.264) and WebM are the most reliable formats. Keep input files under 50MB — for longer source clips, transcode to a lower bitrate before sending. Passing very large files through base64 encoding significantly increases request size and processing time.
Does the ref2v output exactly match the reference video's length?
The duration parameter controls output length. Setting it to match the reference clip length produces the most coherent transformation. If you set a shorter duration than the reference, the model will use the opening segment of the reference for structure.
Can I use ref2v with a computer-generated or animated reference clip?
Yes. ref2v works with any valid video input — live footage, motion graphics, 3D renders, screen recordings. The model treats the reference as a motion guide regardless of its origin.
What happens if the reference video quality is low?
Low-resolution or heavily compressed reference videos produce less stable motion transfer. If your source is under 480p, upscale it to 720p before submission for better results.
Is there an upper limit on how many ref2v jobs I can run concurrently?
Standard GenRelay accounts support a limited number of concurrent video generation jobs. Check the AI video API rate limits guide for current quotas and backoff patterns for batch video workflows.
Summary
Veo 3.1 ref2v on GenRelay is the right tool when you need to preserve the motion structure of an existing video while applying a new visual style. Submit the job with "mode": "ref2v" and a base64-encoded reference video, poll every 15 seconds, and download the output URL on completion. At $0.060/second for 720p and $0.120/second for 1080p, ref2v shares the same pricing tier as t2v and i2v — the mode choice is driven by your input, not your budget.