Guide
Building Short-Form Video with veo-3.1-lite/text-to-video on the HiAPI API
A practical developer workflow for storyboarded text-to-video, native audio, and aspect-ratio choices
On this page
Why short-form video breaks naive text-to-video prompts
The instinct when you first touch a text-to-video model is to write one long, cinematic prompt and expect a finished clip back. For a 30-second short-form piece, that approach almost always disappoints, and the reason is structural rather than a matter of prompt polish.
A single prompt asks the model to hold continuity across an entire narrative arc: character consistency, camera movement, pacing, and audio all have to stay coherent for the full duration. Short-form video, though, is not one continuous take — it is a sequence of beats. A hook, a setup, a turn, a payoff. Each beat wants a different framing, a different energy, and often a different subject position. Cramming them into one prompt makes the model average them out, and averaging is exactly what kills short-form retention.
The other failure mode is iteration cost. When one prompt produces one long clip and the third beat is wrong, you regenerate everything and hope the parts you liked survive. That is a slow loop with no reliable control.
The workflow this guide uses instead is shot-based: decompose the script into discrete shots, give each shot its own generation request, and keep continuity in your own metadata rather than in the prompt. Every section that follows builds on that decomposition — request structure, aspect ratio, audio, and iteration all assume you are working shot by shot.
This is also where veo-3.1-lite/text-to-video fits naturally. A lighter text-to-video model is well suited to many short, individually regenerable clips, which is precisely the shape of a short-form pipeline.
The mental model shift
Stop thinking of the model as a director that returns a finished film. Treat it as a shot renderer: you supply a well-scoped shot description, it returns a clip, and your pipeline owns sequencing, audio mixing, and pacing. Once that division of labor is clear, most of the remaining decisions become engineering decisions rather than prompt-writing ones.
Planning a shot list before you call the API
The shot list is the contract between your script and your generation calls. Write it as data, not prose, so your pipeline can loop over it.
Start from the script and cut it into beats. A practical rule for short-form: one shot per sentence or per visual idea, whichever is shorter. If a sentence needs two camera setups to read clearly, it is two shots. If three sentences share one continuous visual, they can be one shot — but only if the duration still fits comfortably in a single generation.
For each shot, record at minimum:
- Shot ID — stable, human-readable, used for caching and retries.
- Prompt — the visual description, self-contained enough that the shot makes sense in isolation.
- Duration — how long this shot should run in the final cut.
- Aspect ratio — per channel, decided before generation.
- Audio intent — native ambience, silence to be replaced, or a placeholder for voiceover.
- Continuity notes — character wardrobe, lighting, location, and screen direction.
Keep continuity out of the prompt where you can
Continuity notes belong in your metadata, not repeated verbatim in every prompt. Prompts that carry long reused descriptions tend to drift in emphasis — one shot over-weights the wardrobe, the next under-weights it. A cleaner pattern is a short, stable descriptor block per character or location that you, the pipeline author, assemble into each prompt, so the wording is identical across shots even though the prompt itself is not.
Size shots for one request each
Each shot should be generatable in a single call. If a shot needs more time than one generation comfortably covers, split it at a natural cut point — a reaction, a camera move, a beat of silence — rather than stretching the request. Shorter shots are also cheaper to regenerate when one goes wrong, which is the whole point of the decomposition.
Keep the shot list in version control alongside the script. When the script changes, the diff tells you exactly which shots need re-rendering.
Structuring a generation request in your pipeline
With the shot list as data, the request layer becomes a thin wrapper: read a shot, build a request for veo-3.1-lite/text-to-video, call the HiAPI API, store the result keyed by shot ID.
At a high level, a generation call carries the same information as the shot record: the prompt text, the intended duration, and the aspect ratio. The exact parameter names and accepted values are defined by the model's API reference on HiAPI, so treat the endpoint documentation as the source of truth and keep your wrapper's defaults aligned with it rather than hard-coding assumptions in many places.
A reusable wrapper
The shape below is intentionally language-neutral pseudocode — the value is in the structure, not the syntax:
function renderShot(shot, attempt):
request = {
model: "veo-3.1-lite/text-to-video",
prompt: buildPrompt(shot),
duration: shot.duration,
aspect_ratio: shot.aspectRatio
}
response = hiapi.generate(request)
save(shot.id, attempt, response)
return response
Three properties make this wrapper worth having:
- Every call is keyed by shot ID and attempt number. When shot 4 goes wrong, you know exactly which artifact to replace and which attempts failed.
- The prompt is built, not pasted.
buildPromptmerges the shot's own description with the stable character and location descriptors from your metadata, so continuity wording stays consistent across shots. - Nothing downstream depends on the call succeeding first time. The wrapper returns an artifact reference; the stitcher reads whatever is currently approved for each shot.
Generation is asynchronous in practice
Treat generation as a long-running job, not a synchronous call inside a request handler. Submit, persist the job reference, and poll or await completion in a worker. This keeps retries, concurrency limits, and partial failures inside your control instead of tangled with your application's request lifecycle.
Stitching is a separate stage
Do not generate and stitch in one step. Render all approved shots, store them, then run a separate assembly pass: order by shot ID, concatenate, apply transitions if any, and mux audio. Keeping assembly separate means a re-render of one shot only requires re-running assembly, not re-generating anything.
Choosing aspect ratio and clip length per channel
Aspect ratio and duration should be decided from the distribution channel inward, before any generation happens — not adjusted after the fact. Cropping a finished clip to a different frame is the most common way to waste renders.
Aspect ratio
Pick one primary frame per channel and hold it for the entire piece. Mixed aspect ratios inside a single short break the viewing experience on every platform.
- Vertical — the default for feed-scrolling short-form surfaces. Compose for a tall frame: subjects centered or slightly high, safe margins top and bottom for UI overlays.
- Landscape — for embedded players, site hero videos, and presentations where the viewer is stationary.
- Square — occasionally useful for grid-based placements; treat it as a deliberate choice, not a fallback.
The practical consequence for your shot list: vertical framing changes what fits in the frame. A wide establishing shot that reads well in landscape may be unreadable when squeezed to a tall frame. Decide the ratio first, then write shots that are composed for it.
Clip length
Clip length is driven by pacing, not by what the model can maximally produce. A few guidelines:
- Hooks are short. The first shot usually earns attention or loses it; keep it tight and visually unambiguous.
- One idea per clip. If a shot contains two distinct visual events, split it. Shorter clips also give you finer control over final pacing in the edit.
- Leave trims on the table. Generate a little more than your target cut point and trim in assembly. Trimming is free; regenerating is not.
- Aggregate against the platform. Total runtime is the sum of your shots. Add up the planned durations before generating and check that the sequence fits the channel's typical consumption window — much easier to rebalance the shot list than to re-render.
Generate once per ratio
If you genuinely need the same piece in two frames, treat them as two separate deliverables with two shot lists. Shared prompts are fine; shared renders are not, because the composition differs. Encoding the aspect ratio in the shot's metadata makes this explicit and prevents an accidental cross-channel reuse.
Combining native audio with voiceover
veo-3.1-lite/text-to-video can produce native audio alongside the picture, and that audio is genuinely useful — ambience, environmental texture, and simple diegetic sound give a clip presence that silence lacks. The mistake is letting native audio and your own voiceover both try to carry the same role.
The division of labor that works: native audio provides the world, voiceover provides the message. If the native track already contains speech-like content or a strong musical bed, you will fight it during the mix. Decide per shot which track leads.
Ordering the mix
- Lay the voiceover first. Narration timing is fixed by the script; everything else adapts to it.
- Bring the native audio underneath. Where the native track is ambience or texture, keep it audible but subordinate.
- Duck, don't delete. Lower the native track under narration rather than cutting it out entirely — abrupt silences between lines sound unnatural. Smooth gain transitions across each shot boundary.
- Normalize at the end. Mixing per shot and concatenating produces level jumps. Run a final pass across the assembled piece.
When to mute the native track
Mute it — or regenerate the shot with a clearer audio intent — when:
- The native audio contains intelligible speech that competes with your narration.
- The texture is wrong for the scene (for example, an indoor ambience on an outdoor shot).
- You are scoring the whole piece with a single continuous music bed and the native track's own rhythm fights it.
These are usually detectable per shot, which is another argument for keeping shots independent: you can regenerate one shot's audio without touching the rest.
Write audio intent into the shot list
Add an explicit audio field to each shot: native_ambience, silent, or voiceover_covered. It forces the decision before generation and tells your assembly stage which shots need ducking and which simply need the native track dropped.
Keeping quality and cost under control across takes
Iteration discipline is what separates a pipeline that converges from one that burns renders. The good news is that shot-based generation makes the right habits natural.
Regenerate single shots, never sequences
When one beat is wrong, replace that shot. Your wrapper keys results by shot ID and attempt, so the fix is a new attempt for one ID and a re-run of assembly. If you find yourself re-rendering multiple shots to fix one, the shot list is probably too coarse — split it further.
Cache approved clips aggressively
Once a shot is approved, treat it as immutable and store it durably, keyed by shot ID plus a hash of its prompt and parameters. Re-running the pipeline then skips anything unchanged. This matters most during audio and pacing work, where you iterate on the mix while the picture stays fixed.
Change one variable per attempt
When a shot misses, adjust one thing — prompt specificity, duration, or framing — and regenerate. Changing three variables at once tells you nothing about which fix worked, and you will re-learn the same lesson on the next shot.
Fix the recipe before scaling takes
Get one full sequence to a state you are happy with, then use it as the template for variations: alternate hooks, different CTAs. Because the shot list is data, a variant is a small diff, not a new project.
Budget by shot count, not by finished minutes
The unit of work is the shot, so the unit of iteration is the shot. Before generating a batch, count the shots and the expected number of takes per shot. That number, combined with the model's billing basis, is your planning figure — check the current rates on the HiAPI pricing panel rather than carrying stale assumptions.
Review at final size
Check each shot in the actual aspect ratio and on the kind of screen it will be viewed on. Problems that are invisible at desktop landscape size are obvious in a vertical feed. Catching them at review is far cheaper than catching them after publication.
Troubleshooting common generation problems
When a shot comes back unusable, work through these checks in order. They cover the large majority of failures, and the first two resolve most of them.
1. Prompt specificity
Is the prompt self-contained? Does it describe subject, action, framing, and lighting, or does it rely on context from neighboring shots? A shot prompt must stand alone — the model sees only what you send. Vague subject descriptions produce drift; overloaded prompts produce mush. Aim for one clear subject and one clear action per shot.
2. Shot length
Is the shot doing too much for its duration? If a prompt implies several visual events in a short clip, the model compresses them. Split the shot or lengthen it. Conversely, a shot with too little content for its duration tends to meander — trim it.
3. Aspect ratio mismatch
Did you compose the prompt for the frame you actually requested? Wide, horizontal descriptions in a vertical frame produce awkward crops and dead space. Check that the shot's visual description matches its aspect ratio, and that no other stage in the pipeline silently re-crops.
4. Audio conflicts
If the picture is fine but the result feels off, listen to the native track alone. Competing speech, wrong ambience, or a strong rhythm under narration is usually an audio problem, not a visual one. Fix it by muting the native track or adjusting the shot's audio intent, then re-mix — no picture regeneration needed.
5. Pipeline and parameter mistakes
If generation fails outright or returns something inconsistent with the request, verify the parameters against the endpoint documentation on HiAPI: model identifier spelled correctly, duration and aspect ratio values within accepted ranges, prompt non-empty. These errors are boring but common in wrappers that hard-code defaults in several places — which is the argument for keeping request construction in one function.
6. Continuity drift across shots
If each shot looks fine but the sequence does not hold together, the problem is metadata, not generation. Compare the assembled prompt text per shot: if character or location descriptors differ in wording, align them in your shared descriptor block and regenerate only the divergent shots.
Work the list in order and log which check resolved each failure. After a few sequences you will know which checks dominate for your content, and the troubleshooting pass becomes a quick scan rather than a rebuild. You can start rendering shots against veo-3.1-lite/text-to-video through the HiAPI API and let the pricing panel cover the numbers while you focus on the sequence.
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