WAN 3.0 is LIVE — 30s in one shot | Try in Video Generator →
Home/Explore/PixVerse/Pixverse C1/Reference To Video

pixverse/

PixVerse C1 Reference-to-Video generates videos from reference images with subject and background consistency. Use @ref_name in prompts to reference uploaded images. Supports 360p to 1080p resolutions, 1-15 second duration, multiple aspect ratios, and optional audio generation. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

image-to-video
Input
Enable Safety Checker

Idle

$0.05per run·~20 / $1

Next:

ExamplesView all

@woman1 gently picked up the scarf1, admired it, and put it on.

Related Models

README

PixVerse C1 Reference-to-Video

PixVerse C1 Reference-to-Video generates cinematic video guided by reference images. Upload up to 7 reference images as characters, objects, or backgrounds — then describe the scene in your prompt using @ref_name to refer to each reference — and the model produces a cohesive, identity-consistent video that brings your references to life.

Why Choose This?

  • Multi-reference image support Upload 1 to 7 reference images — characters, objects, or backgrounds — and combine them into a single generated scene.

  • Subject and background control Tag each reference as subject (character or object) or background (scene or environment) for more precise compositing.

  • @ref_name prompt referencing Reference specific images directly in your prompt using @ref_name for precise control over which element appears where.

  • Character-consistent output The model preserves the visual identity of referenced subjects throughout the generated clip.

  • Optional native audio generation Enable generate_audio_switch to produce synchronized ambient sound alongside the video.

  • Four resolution tiers Generate from 360p up to 1080p to match your quality and delivery requirements.

Parameters

ParameterRequiredDescription
promptYesText description of the scene. Use @ref_name to reference specific images.
imagesYesList of 1–7 reference images. Each entry requires image_url, type, and ref_name.
aspect_ratioNoOutput aspect ratio. Options: 16:9 (default), 4:3, 1:1, 3:4, 9:16, 2:3, 3:2, 21:9.
resolutionNoOutput resolution: 360p, 540p, 720p (default), or 1080p.
durationNoClip length in seconds. Range: 1–15. Default: 5.
generate_audio_switchNoWhether to generate native audio for the video. Default: off.

Image Entry Fields

Each image in the images list requires:

FieldDescription
image_urlURL of the reference image.
typeReference type: subject (character or object) or background (scene or environment).
ref_nameA short name for this reference. Use @ref_name in your prompt to refer to this image.

How to Use

  1. Write your prompt — describe the scene and use @ref_name to reference specific images (e.g. "@hero is running through @city_bg at night.").
  2. Add reference images — provide 1 to 7 images, each with an image_url, type, and ref_name.
  3. Select aspect ratio — choose the format that fits your target platform.
  4. Select resolution — 360p for fastest/lowest cost, 720p for standard, 1080p for highest quality.
  5. Set duration — choose between 1 and 15 seconds.
  6. Enable audio (optional) — check generate_audio_switch to generate synchronized native audio.
  7. Submit — generate, preview, and download your video.

Pricing

ResolutionWithout AudioWith Audio
360p$0.030/s$0.040/s
540p$0.040/s$0.050/s
720p$0.050/s$0.065/s
1080p$0.095/s$0.120/s

Billing Rules

  • Billing is calculated per second of video generated
  • Duration range: 1–15 seconds
  • Examples: 10s at 720p (no audio) = $0.50 — 10s at 1080p (no audio) = $0.95

Best Use Cases

  • Character-driven storytelling — Place consistent characters from reference images into entirely new scenes.
  • Brand & product videos — Generate new scenes featuring consistent brand characters or products from reference imagery.
  • Social media content — Produce short-form video clips with consistent visual identity from reference photos.
  • Creative concepting — Rapidly prototype multi-character or multi-element scenes for pitching and storyboarding.
  • Style-consistent series — Maintain a unified visual style across multiple video generations using the same reference set.

Pro Tips

  • Assign clear, memorable ref_names (e.g. hero, bg, product) and use them naturally in your prompt.
  • Tag environment or scene images as background and characters or objects as subject for the most accurate compositing.
  • Use clear, well-lit reference images with distinct subjects for the best identity preservation.
  • Use 360p to rapidly test your scene composition before committing to a higher-resolution render.
  • Enable audio for scenes with strong ambient environments like outdoor settings, crowds, or action sequences.

Notes

  • Both prompt and images are required fields; all other parameters are optional.
  • Each image entry must include image_url, type, and ref_name.
  • Ensure image URLs are publicly accessible.
  • Please follow PixVerse's content usage policies when crafting prompts.

Related Models

Note:This website uses AI models provided by third parties. Documentation prices are for reference and may be outdated. The Generate button shows an estimate; the final task charge prevails.

Pixverse C1 Reference To Video API — Quick start

Grab a WaveSpeedAI API key, then call POST https://api.wavespeed.ai/api/v3/pixverse/pixverse-c1/reference-to-video with your input as JSON. The endpoint returns a prediction id. Start polling the result endpoint around every 2 seconds, increase the interval for long-running tasks, and stop on any terminal status. On completed, read output values from data.outputs. Examples for Pixverse C1 Reference To Video below.

HTTP example
set -euo pipefail

: "${WAVESPEED_API_KEY:?Set WAVESPEED_API_KEY}"

REQUEST_BODY=$(cat <<'JSON'
{
    "prompt": "A cinematic shot of a city at sunset, soft golden light",
    "images": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
    ],
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio_switch": false
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/pixverse/pixverse-c1/reference-to-video" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" \
  -d "$REQUEST_BODY")

TASK=$(printf '%s' "$SUBMIT_RESPONSE" | jq 'if has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "$TASK" | jq -r '.id')
if [ -z "$PREDICTION_ID" ] || [ "$PREDICTION_ID" = "null" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/$PREDICTION_ID/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body "$RESULT_URL" \
    -H "Authorization: Bearer $WAVESPEED_API_KEY")
  RESULT=$(printf '%s' "$RESPONSE" | jq 'if has("data") then .data else . end')
  STATUS=$(printf '%s' "$RESULT" | jq -r '.status')
  case "$STATUS" in
    completed) printf '%s\n' "$RESULT" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "$RESULT" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done
Node.js example
const submitUrl = "https://api.wavespeed.ai/api/v3/pixverse/pixverse-c1/reference-to-video";
const apiKey = process.env.WAVESPEED_API_KEY;
if (!apiKey) throw new Error('Set WAVESPEED_API_KEY');

async function requestJson(url, options = {}) {
  const response = await fetch(url, options);
  if (!response.ok) throw new Error(await response.text());
  return response.json();
}

// 1. Submit the prediction.
const body = await requestJson(submitUrl, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
        "prompt": "A cinematic shot of a city at sunset, soft golden light",
        "images": [
                "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
        ],
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "duration": 5,
        "generate_audio_switch": false
}),
});
const task = body.data ?? body;
if (!task.id) throw new Error("Submission response did not contain a prediction id");
const resultUrl = `https://api.wavespeed.ai/api/v3/predictions/${task.id}/result`;

// 2. Poll until the prediction finishes.
while (true) {
  const resultBody = await requestJson(resultUrl, {
    headers: { "Authorization": `Bearer ${apiKey}` },
  });
  const result = resultBody.data ?? resultBody;
  if (result.status === "completed") {
    console.log(result.outputs);
    break;
  }
  if (["failed", "cancelled", "timeout", "deleted"].includes(result.status)) throw new Error(JSON.stringify(result));
  await new Promise(resolve => setTimeout(resolve, 2000));
}
Python example
import json
import os
import time
from urllib.request import Request, urlopen

api_key = os.environ["WAVESPEED_API_KEY"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
payload = {
    "prompt": "A cinematic shot of a city at sunset, soft golden light",
    "images": [
        "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
    ],
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio_switch": False
}

def request_json(url, data=None):
    request = Request(url, data=data, headers=headers, method="POST" if data else "GET")
    with urlopen(request) as response:
        return json.load(response)

# 1. Submit the prediction.
body = request_json("https://api.wavespeed.ai/api/v3/pixverse/pixverse-c1/reference-to-video", json.dumps(payload).encode())
task = body.get("data", body)
if not task.get("id"):
    raise RuntimeError("Submission response did not contain a prediction id")
result_url = f"https://api.wavespeed.ai/api/v3/predictions/{task['id']}/result"

# 2. Poll until the prediction finishes.
while True:
    result_body = request_json(result_url)
    result = result_body.get("data", result_body)
    status = result.get("status")
    if status == "completed":
        print(result.get("outputs", []))
        break
    if status in {"failed", "cancelled", "timeout", "deleted"}:
        raise RuntimeError(result)
    time.sleep(2)

Pixverse C1 Reference To Video API — Frequently asked questions

What is the Pixverse C1 Reference To Video API?

Pixverse C1 Reference To Video is a Pixverse model for video generation from images, exposed as a REST API on WaveSpeedAI. PixVerse C1 Reference-to-Video generates videos from reference images with subject and background consistency. Use @ref_name in prompts to reference uploaded images. Supports 360p to 1080p resolutions, 1-15 second duration, multiple aspect ratios, and optional audio generation. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing. You can call it programmatically or try it from the playground above.

How do I call the Pixverse C1 Reference To Video API?

POST your input parameters to the model's REST endpoint (shown in the API tab of this playground) with your WaveSpeedAI API key in the Authorization header. Submission returns a prediction ID. Poll the result endpoint starting around every 2 seconds, increase the interval for long-running tasks, and stop on any terminal status. The playground generates production-oriented Python, JavaScript, and cURL examples with timeouts, transient-error handling, and safe GET retries. Full request/response shape is documented at https://wavespeed.ai/docs/docs-api/pixverse/pixverse-pixverse-c1-reference-to-video.

How much does Pixverse C1 Reference To Video cost per run?

Pixverse C1 Reference To Video starts at $0.050 per run. That figure is the base price — the final charge scales with the parameters you set in the form (output size, length, count, references, or whatever knobs this model exposes), so a higher-quality or larger output costs more than a minimal one. The exact cost for your current input is shown live next to the Generate button before you submit, and the actual per-call charge is recorded on the prediction afterwards.

What inputs does Pixverse C1 Reference To Video accept?

Key inputs: `prompt`, `images`, `aspect_ratio`, `resolution`, `duration`, `generate_audio_switch`. The full JSON schema (types, defaults, allowed values) is rendered above the Generate button and mirrored in the API reference at https://wavespeed.ai/docs/docs-api/pixverse/pixverse-pixverse-c1-reference-to-video.

How long does Pixverse C1 Reference To Video take to generate?

Median end-to-end generation time on WaveSpeedAI is around 176 seconds per request, based on recent successful runs. Queue time varies with global demand; live status is visible in the prediction record.

Can I use Pixverse C1 Reference To Video outputs commercially?

Commercial usage rights depend on the model's license, set by its provider (Pixverse). The license summary appears on the model card above; see WaveSpeedAI's Terms of Service for platform-level conditions.

Pixverse C1 Reference to Video | Fast Image-to-Video API on WaveSpeedAI