Guide
Vidu Q3 Ad reference-to-video Getting Started Guide: Capability Boundaries, API Integration, and Cost Estimation
On this page
What problem does this model solve
When building video products, teams often run into a gap: the creative side already has a visually distinctive image, but turning that image into usable motion footage requires the entire chain of modeling, storyboarding, and compositing in between. Text-to-video can fill part of this gap, but it struggles to reliably reproduce the composition, subject relationships, and visual tone of the reference image you already have.
Vidu Q3 Ad's reference-to-video capability targets exactly this gap: it takes reference material and a text description as input and directly produces a video. For developers, it's more like a "generation interface with controllable visual conditions" — what you provide is not an abstract description, but a visual anchor.
A typical call pattern can be abstracted into three steps: prepare reference material, construct the prompt, and initiate a generation request to get the video result. In the context of HiAPI.ai's unified interface, this is still the standard "submit task, poll or callback, retrieve output" flow — no need to learn a new integration paradigm.
It suits teams that already know exactly what visuals they want and just need to bring them to life: ad creative variations, e-commerce showcases, social media short content, and atmospheric clips in games or apps. Understanding this is important — it's not a tool that conceives creative ideas from scratch for you, but an execution layer that converts existing visual intent into video at scale.

Capability boundaries and applicable scenarios
Before starting integration, clearly distinguishing "what it can do" from "what it doesn't guarantee" can save a lot of rework.
What you can expect
- Reference-driven visual continuity: Given reference material and a prompt, the model generates dynamic content around the visual characteristics of the reference — suitable for series assets that need consistent style.
- One video per request: The input-output relationship is direct, making it easy to encapsulate as a retryable job unit.
- Works together with prompts: The reference material sets the tone, while the prompt supplements action, camera, and pacing descriptions — both jointly constrain the result.
What needs careful evaluation
- No guarantee of frame-by-frame pixel-level consistency: The reference is a "guide" rather than a "copy" — don't treat the reference image as a strict first frame or precise texture template.
- Limited text and detail reproduction: Small text, complex logos, and fine UI elements in the frame are typically not strengths of this type of model; key copy in promotional materials should be overlaid in post-production.
- Weak at long shots and complex narratives: A single generation is better suited for short clips; multi-segment narratives require multiple calls combined with editing.
- Generation is stochastic: Re-running the same set of inputs may produce different results, so the product side needs to design a "pick one from many" or "manual selection" step.
Scenarios that fit and don't fit
Fits: bulk asset variations, style-consistent series of short films, proof-of-concept and proposal previews, rapid trial-and-error for ad materials.
Doesn't fit: final materials requiring precise brand-compliant rendering, projects requiring strict character consistency across a long film, and scenarios with hard requirements on on-screen text accuracy. Handing these to deterministic post-production tools will be more cost-effective than repeatedly retrying generation.

Key API parameters before integration
When integrating a new model, what really determines the amount of rework is often not the model itself, but the request design. Here are the dimensions to confirm in advance when calling reference-to-video.
Required and optional inputs
The core inputs are reference material and the prompt. Before integration, confirm: what formats and sizes the reference material supports, whether multiple references are supported, and what resolution requirements the material has. The prompt should clearly describe both "what's in the frame" and "how it moves" — for example, how the subject moves, whether the camera pushes in or pans, and whether the overall pacing is fast cuts or slow motion.
Duration and output specifications
This type of model is typically billed by duration, so the duration parameter directly determines cost. During integration, duration should be exposed as an explicit configuration item to the upper-layer business logic, not hardcoded; also confirm whether the output resolution, frame rate, and container format satisfy the downstream playback pipeline, avoiding the need for transcoding after generation.
Asynchronous task model
Video generation is not a millisecond-level call. By design, it should follow an asynchronous flow of "submit task → get task ID → poll or callback → download output," and maintain a state machine for each task: queued, generating, succeeded, failed, timed out. Don't rely on synchronous requests with forced timeouts — that makes retry logic and billing reconciliation hard to track.
Idempotency and retries
Attach a business-side unique request identifier to each submission, ensuring that duplicate submissions caused by network anomalies don't lead to duplicate charges or duplicate files. The retry strategy should distinguish retryable errors (timeouts, rate limiting) from non-retryable errors (invalid parameters, non-compliant reference material).
Alignment with the unified interface
Encapsulate model calls in an internal adapter layer, expose your own parameter structure externally, and map internally to specific API fields. This way, when switching or adding models later, business code doesn't need to change — only the adapter layer needs adjustment.
Per-second billing cost estimation
The model is billed by the seconds of output video. To estimate the budget, simply convert "duration per clip × number of clips" into total seconds, then multiply by the unit price. For real-time pricing, refer to the site's pricing panel; here we only cover the conversion method.
How to calculate per-clip cost
Suppose you want to generate a 5-second clip. The calculation path is: 5 seconds × per-second unit price = per-clip cost. The same applies to batch scenarios: generating 100 clips of 5 seconds each gives a total duration of 500 seconds, and the cost is 500 × unit price. The only key variables here are three — duration, number of clips, and the extra generation count caused by retries or multiple sampling.
Factor "uncertainty" into the budget
Generative models are stochastic, and in practice you often need to generate multiple candidates for the same input and then select. If you do 3 samples per asset, the actual cost is 3 times the target number of clips. When budgeting, the sampling multiplier should be an explicit parameter:
- Target output count: N
- Average sampling count: K
- Duration per clip: T seconds
- Total generation seconds ≈ N × K × T
There's also the overhead of failure retries. It's recommended to reserve a certain proportion of buffer in the budget, with the specific proportion based on your observed failure rate rather than guesswork.
Four levers for budget control
- Validate with short durations first: Use 2–3 second short clips to tune the prompt and reference material, and only extend after confirming the direction.
- Layered sampling: First use low-cost parameters for multi-candidate screening, then do high-quality generation for selected candidates after choosing a direction.
- Limit retry counts: Set a retry cap for the same input to avoid failed tasks looping indefinitely and burning budget.
- Reconcile by seconds: Use generated seconds as the internal cost accounting unit, consistent with finance, making it easy to trace the true cost of each asset.
As long as "seconds" is treated as the sole cost unit, the estimation logic for single clips and batches is the same and won't become distorted as business scale changes.
Typical usage and combination suggestions
Integrating the model is only the first step; the production patterns you can combine around it determine the actual value of this integration.
Pattern 1: Bulk content production
Use a templated prompt plus a batch of reference material, and generate in bulk via a queue. Suitable for scenarios like multi-SKU e-commerce showcases and daily social media content — "high volume, per-clip requirements not extreme." On the engineering side, focus on three things: task queue and concurrency control, output storage and naming conventions, and automatic re-entry of failed tasks.
Pattern 2: Multi-version comparison and A/B assets
The same reference material paired with different prompts, or the same prompt sampled multiple times, produces a set of candidates. This pattern suits pre-campaign asset testing: hand candidates to the ad delivery system for small-traffic validation and use real data to decide the main version. In engineering design, treat the "generation batch" as a traceable unit and record the parameters for each candidate for retrospective analysis.
Pattern 3: Chained with manual review
Generated results are not published directly, but enter a manual selection or compliance review queue. This is a relatively stable deployment approach: machines handle capacity, humans handle judgment. Automated pre-screening (such as duration, resolution, black frame detection) can be inserted into the pipeline to block obviously unqualified outputs before human review.
Pattern 4: As a creative proposal tool
Before formal production, use reference material to quickly generate dynamic previews, helping clients or decision-makers form expectations. This usage has low consistency requirements and high speed requirements, which falls right into the model's sweet spot.
Combination suggestions
The above patterns are not mutually exclusive. A typical production pipeline is: short-duration pilot validation → bulk generation → automated pre-screening → manual review → ad delivery testing → data feedback into the prompt library. Each stage produces reusable data, and the quality of prompts and reference material gradually improves with iteration.
Common issues and troubleshooting
Most failures during integration fall into a few categories. Following the order below usually locates the problem within a few rounds.
Generated results differ greatly from expectations
This is the most common complaint. First check whether the prompt only describes the static frame without motion, then check whether the reference material is clear and the subject is well-defined. If the reference material itself has a cluttered composition, it's hard for the model to extract effective features. It's recommended to first do a baseline test with minimalist reference material and a short prompt, confirm the pipeline works, then gradually increase complexity.
Reference features are not reflected
First confirm whether the format, size, and content of the reference material meet the interface requirements, then confirm there's no description in the prompt that conflicts with the reference material. When the reference material and prompt give contradictory instructions, the result often resembles neither.
Tasks take too long or time out
Check the implementation of the asynchronous flow: whether the polling interval is too dense causing rate limiting, whether the callback URL is reachable, and whether task state is correctly persisted. Don't do long-connection waiting on the client side — task state should be persisted on the server.
Duplicate charges or duplicate outputs
Almost always caused by missing idempotency. Confirm each submission carries a unique request identifier and the server deduplicates identical identifiers. Also check whether the retry logic unconditionally fires new requests after a timeout.
Output cannot be played
Confirm the output format is compatible with the downstream player, focusing on container format, codec, and frame rate. If generation succeeds but playback fails, the problem is most likely in the download or transfer stage, not the generation stage.
Cost exceeds expectations
Look back at the sampling multiplier and retry count. Most overspending is not due to unit price, but unbounded retries and excessively high sampling multipliers. Setting hard caps on these two parameters is the most direct way to stop the bleeding.
Pre-launch checklist
Confirm the following items one by one, and you can basically determine whether this model is suitable for integrating into your product.
Requirement matching
- It's clear that this capability is "reference-driven" rather than "precise reproduction," and product copy is aligned with user expectations.
- Confirmed that the target scenario falls under short clips and style continuity, not long narratives or strong consistency requirements.
- Determined that key text and logos in the frame will be overlaid in post-production, not relying on model generation.
Interface design
- Format, size, and quantity requirements for reference material have been confirmed and written into validation logic.
- Cost-affecting parameters such as duration and resolution are exposed as configuration items, not hardcoded.
- The asynchronous task flow is complete: submission, state persistence, polling or callback, output download.
- Idempotency identifiers and retry strategies are implemented, with retryable and non-retryable errors distinguished.
- Model calls are encapsulated in an internal adapter layer, facilitating future replacement or addition of models.
Cost and budget
- Stage budgets have been estimated based on "seconds × sampling multiplier × number of clips," with failure buffer reserved.
- Hard caps on sampling count and retry count have been set.
- An internal cost accounting standard based on seconds has been established, traceable to each asset.
- Real-time unit price and billing details are based on the site's pricing panel, and this standard has been communicated within the team.
Quality and compliance
- A multi-candidate selection or manual review step has been designed; outputs are not published directly.
- Copyright and authorization for reference material have been confirmed.
- Automated pre-screening rules are prepared to filter out obviously unqualified outputs.
Launch pace
- First run the end-to-end pipeline with short durations and small batches, then gradually scale up.
- The parameters and results of the first batch of generations have been recorded as a baseline for future optimization.
Running through this checklist before deciding whether to integrate directly or start with a small-scale pilot will be much safer than launching based on intuition. Vidu Q3 Ad's reference-to-video is available on HiAPI.ai via a unified interface and is well-suited as an execution-layer component in the video asset production pipeline.
Related articles
View all articles →-
Guide
gpt-6.2-sol Getting Started Guide: Capability Boundaries, API Integration, and Token Pricing Essentials
Integration decisions and practical essentials for engineering teams
-
Guide
gpt-6.2-astra Getting Started Guide: Text Model Capability Boundaries, Integration Essentials, and Cost Control
-
Guide
Tripo H3.1 Getting Started Guide: Choosing Among Three Input Modes, Parameters, and Pricing
A practical guide for developers on 3D generation integration decisions and cost control