Searching for “pixverse video reference api” mostly returns pages about reference images: upload up to seven tagged photos, cite them with @ref_name, and get a consistent-subject video. That is real PixVerse functionality, but it is not the API this guide covers. PixVerse V6 also accepts reference videos through its Fusion path — you upload a clip, the model reads its subjects, motion, scene, camera movement, and visual style, and you can re-create or modify that motion with a prompt.
This guide walks the complete video-reference integration: upload the reference video, submit a V6 Fusion request with video_references, poll the job to a terminal state, and price it against the official credits ×2 table. The workflow facts below were read from PixVerse’s official platform documentation on August 3, 2026. Modellix is an API aggregator with a commercial interest in this topic; the guide describes the official PixVerse Platform path as the neutral baseline and shows where a Modellix route fits — without claiming the aggregator is cheaper.
What the PixVerse video reference API does
The official V6 Fusion documentation states that V6 “can understand and reference subjects, actions, scenes, camera movements, and visual styles from input videos,” and that prompts can drive effects such as subject replacement, video recreation, and motion imitation. The official Fusion integration guide is the authoritative source for the field-level contract used in this article.
The distinction from image-reference mode matters for product design. The standard Fusion reference-to-video guide builds a video from up to several reference images (subjects and backgrounds composed via prompt); the V6 video-reference path instead accepts reference video clips. An image reference pins appearance; a video reference additionally pins motion, timing, and camera behavior. If your use case is “make this character do a different action with the same look,” image references may be enough. If it is “match this camera move and this actor’s motion,” you need the video-reference path.
That combination maps to concrete jobs: e-commerce teams reuse a product shot’s motion and camera for multiple ad variants, brand and IP teams keep a character’s movement consistent across scenes, and film teams use reference footage for pre-visualization and action matching. The rest of this guide stays API-first, but those are the workflows the video-reference input was built for.
This API belongs to PixVerse Platform, not to consumer-facing products. It is also distinct from PixVerse Growth Studio, which is a separate marketing-video workflow on PixVerse’s own site and is not part of the reference-to-video API surface. Treat the two as different products when you read pricing or documentation.
V6 is the only model that accepts video references
The single most decision-relevant fact in this topic: video references are supported only by the V6 model, and only when reference_mode is set to omni. The official guide states this explicitly. C1, V5, V4.5, and older generations do not accept video_references, even though their pages often rank for “pixverse video reference api” queries.
That explains the version confusion in current search results: aggregator model cards for V3.5, V4.5, and V5 rank alongside the official V6 documentation, and several describe “reference-to-video” as image-reference-only. If your integration must accept a reference video as input, the model field in your request must be v6 — the PixVerse V6 reference-to-video model page on Modellix is a convenient place to compare the V6 route’s documented input fields at a glance.
The V6 Fusion request contract for video references
A video-reference request combines the standard V6 Fusion fields with video_references. The official constraints are not optional tuning; the platform rejects requests that violate them.
| Constraint | Official rule |
|---|---|
| Model | v6 only; reference_mode must be "omni" |
| Reference videos per request | Maximum 2 |
| Total reference duration | Maximum 15 seconds across all reference videos |
duration field |
Must be 0 when using video references; output duration auto-matches the longest reference video |
| Omni reference budget | Up to 10 reference images + 2 reference videos per request |
aspect_ratio |
Omni supports "auto" to retain the source composition |
A minimal request body follows this shape (field names per the current official guide):
1 | { |
The media_id values are not invented by you: they are returned by the media upload operation, described next. Do not hard-code endpoints or response field names from this article — copy the current request contract from the official guide before production. For the broader request surface (authentication, endpoints, general parameters), our PixVerse API integration guide covers the complete developer workflow.
Step by step: upload, submit, poll
The documented video-reference workflow has three stages, matching the general PixVerse async pattern (submit → poll → retrieve).
The verified video-reference call sequence: upload returns media_id; the Fusion request carries it in video_references; polling the returned video_id moves the job from status 5 to 1. Illustrative Modellix diagram, August 3, 2026.
1. Upload the reference video and keep the media_id
Send the reference video to the media upload operation. On success, PixVerse returns a media_id (plus media_type and a url). Persist that ID; it is the reference you pass in video_references. The official guide shows the upload response shape as ErrCode: 0, ErrMsg: "success", and Resp.media_id.
Validate before uploading: enforce the two-video and 15-second combined limits in your own service so users get an immediate, actionable error instead of a provider rejection. Also enforce the format and size limits documented for media upload — they are part of the same official contract.
2. Submit the Fusion generation
Send the request body from the previous section with your uploaded media_id values in video_references. Authentication follows the standard Platform rules: every request carries your API key in the header, and each unique request needs its own Ai-trace-id — the API overview notes that reusing the same Ai-trace-id does not generate a new video.
A successful submission returns a video_id. Treat generation as asynchronous: return your own internal job ID to the caller and let a worker poll, rather than holding an HTTP request open.
3. Poll status until terminal
Poll the video status endpoint with the returned video_id until status changes from 5 (waiting for generation) to 1 (success), then retrieve the generated video from the returned url. The official status contract defines 1 = generation successful, 5 = waiting for generation, 7 = content moderation failure, and 8 = generation failed; it recommends polling at intervals of 3–5 seconds while a job is in status 5. Use exponential backoff, a maximum attempt count, and explicit handling for failure and moderation outcomes — a status that never reaches 1 is not “still running” forever.
1 | def poll_until_terminal(video_id, max_attempts=30, base_delay=2): |
What video references cost: the credits ×2 rule
PixVerse Platform bills video generation in credits per second. Using video references changes the rate: the official pricing page publishes separate tables for Fusion requests with and without video_references, and the with-video-reference rates are exactly double the image-reference rates at every quality tier. The official page also gives a unit anchor: $1 = 5 videos (v6, 720p, 5s, no audio, with Starter pack) — use that only as a sanity check, because package, membership, and audio options change the effective rate.
| Quality | Fusion, no video_references (per second, no audio / with audio) | Fusion, with video_references (per second, no audio / with audio) |
|---|---|---|
| 360p | 5 / 7 credits | 10 / 14 credits |
| 540p | 7 / 9 credits | 14 / 18 credits |
| 720p | 9 / 12 credits | 18 / 24 credits |
| 1080p | 18 / 23 credits | 36 / 46 credits |
Source: PixVerse Platform official pricing and Fusion documentation, accessed August 3, 2026. Rates are PixVerse Platform credits per second, not Modellix USD pricing.
PixVerse’s official V6 Fusion reference-to-video guide, captured August 3, 2026: the left column lists the video_references constraints; the tables show billing per second without and with video references.
Two billing cautions. First, these are Platform credits, not a dollar amount you can compare directly with any aggregator’s USD price — a credit-to-dollar conversion depends on the active package. Second, audio adds a meaningful premium at every tier — roughly +28–40% per the table above — and with 1080p + audio + video references you are at 46 credits per second. For budget controls, compute an estimate from the current official table and display its assumptions next to it. Our PixVerse credit pricing breakdown goes deeper into how credits convert to effective per-second costs across plans.
Direct Platform access versus an aggregator route
Use PixVerse Platform directly when you need the official product surface — the console, the media upload flow, and the exact video_references contract — and you are willing to track a credit balance and per-request Ai-trace-id yourself.
An aggregator route makes sense when your product deliberately integrates multiple media providers behind one account, one key, and one billing surface. Modellix’s PixVerse provider page lists its PixVerse model catalog; the v6-r2v model page documents reference-image inputs (1–7 items with subject/background roles and ref_name) and per-second USD pricing, with a separate c1-r2v page for the C1 variant. Modellix displays these routes billed per second in USD, e.g. v6-r2v at $0.0575/s (360p, no audio) up to $0.2645/s (1080p, with audio), as shown on the model page on August 3, 2026.
That description is deliberately narrow. The Modellix model page documents image-reference input; the official video-reference (video_references) workflow lives in PixVerse’s Platform documentation. If your integration requires reference-video input specifically, verify the current Modellix model page and API documentation for whether that route accepts video input before committing — do not assume either way. This is not a claim that Modellix is cheaper: Platform credits and aggregator USD are different billing units, and the honest comparison requires matching model, quality, audio, and duration on both sides.
Common errors when integrating video references
- More than two reference videos. The platform caps
video_referencesat two entries per request. Validate the count client-side. - Reference videos totaling more than 15 seconds. Combined duration is capped at 15 seconds; trim or re-encode before upload.
durationset to anything other than 0. With video references,durationmust be 0; the output length follows the longest reference video. A fixed-duration request will be rejected.reference_modemissing or notomni. The video-reference path requires omni mode; older or default modes do not accept video input.- Wrong model. C1 and older generations reject
video_references. Route video-reference jobs tov6. - Reused
Ai-trace-id. The same trace ID does not produce a new video — generate a unique ID per request. - Status stuck at 5 or ending in 7/8. The official status contract defines 1 = generation successful, 5 = waiting, 7 = content moderation failure, and 8 = generation failed, with 3–5 second polling recommended while a job is at 5. Poll with backoff and a timeout; statuses 7 and 8 need operator handling, not infinite polling.
Frequently asked questions about the PixVerse video reference API
What is the PixVerse video reference API?
It is the V6 Fusion path that accepts reference videos as input. The model reads subjects, actions, scenes, camera movement, and visual style from uploaded clips, then generates a new video that reuses them under prompt control — for subject replacement, video recreation, or motion imitation.
Which PixVerse model supports video references?
Only V6, and only with reference_mode: "omni". C1, V5, and older models do not accept video_references, even though their model pages sometimes rank for video-reference queries.
How do I pass a reference video to the PixVerse API?
Upload the video through the media upload operation and keep the returned media_id. Then include it in the Fusion request as video_references: [{"media_id": ...}] with model: "v6", reference_mode: "omni", and duration: 0.
Why must duration be 0 for video references?
The official contract requires it. Output duration auto-matches the longest reference video, so the model derives length from your input rather than a fixed value.
How many reference videos can I use, and how long can they be?
Up to two reference videos per request, with a combined duration of 15 seconds or less. Omni mode also allows up to 10 reference images alongside the two videos.
How much does a video-reference generation cost?
In Platform credits per second, Fusion with video references costs 10/14/18/36 credits at 360p/540p/720p/1080p without audio, and 14/18/24/46 with audio — double the image-reference rate at each tier. The effective dollar cost depends on your credit package; see the official pricing page.
Can I use video references through Modellix?
Check the current Modellix model page and API documentation for the exact input contract of the route you need. Modellix’s v6-r2v page documents image-reference input with per-second USD pricing; the official video_references workflow is documented on PixVerse Platform. Verify before relying on either path.
Does the PixVerse video reference API work with Growth Studio?
No. Growth Studio is a separate PixVerse marketing-video workflow with its own product and API surface. The reference-to-video API described here is part of PixVerse Platform’s V6 Fusion offering.
PixVerse capability and pricing details reflect official documentation accessed August 3, 2026 and change frequently. 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 PixVerse 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 PixVerse product screenshot or source evidence.
