Grok Text to Video API: Call grok-imagine Video Models via hiapi

Why route Grok video generation through an aggregation API

Video generation is rarely a single-model problem. You start with one idea, then quickly need a cheaper variant for drafts, a higher-fidelity model for the final pass, and a fallback when a provider has a rough day. Wiring each of those directly means maintaining separate credentials, request shapes, and error semantics — work that has nothing to do with the video you want to produce.

hiapi gives you one unified interface for Grok text-to-video models. You keep a single credential and a single request contract while grok-imagine/text-to-video and grok-imagine-1.5-lite sit behind the same endpoint family. Switching variants becomes a model-name change rather than an integration rewrite, and your prompt templates, retry logic, and asset handling stay intact.

There is also an operational argument. Aggregated access means model availability and deprecations are handled upstream, so a new grok-imagine variant can enter your pipeline without a redeploy. For teams shipping video features into a product, that reduces the surface area you own: you own the prompt and the product experience, not the provider plumbing.

Meet the model variants: grok-imagine/text-to-video and grok-imagine-1.5-lite

Two Grok text-to-video variants are available through hiapi, and they occupy different points on the fidelity-versus-throughput curve.

grok-imagine/text-to-video

This is the general-purpose text-to-video model. Reach for it when output quality is the priority: hero clips, marketing assets, concept pitches, and any case where a human will scrutinize the motion. It is the safer default when you do not yet know how a prompt will behave, because you are evaluating the model at its strongest.

grok-imagine-1.5-lite

The lite variant targets lower latency and lighter resource consumption. Use it for iteration loops — prompt exploration, storyboard previews, batch generation of candidate clips — where you want to converge on a prompt before spending the expensive pass. In production it can also serve high-volume, low-stakes surfaces where a fast response matters more than a perfect frame.

How to decide

A useful rule: draft on grok-imagine-1.5-lite, finalize on grok-imagine/text-to-video. Because both share the same request contract on hiapi, you can parameterize the model name in your client and swap it per job tier. If a lite draft already looks right, promote the same prompt to the full model for the deliverable. If it does not, you saved the cost of a slow, expensive attempt.

Anatomy of a text-to-video request

Every text-to-video call you make through hiapi is built from a small set of parts. Understanding them separately makes debugging much faster.

The model field

The model identifier selects the variant (grok-imagine/text-to-video or grok-imagine-1.5-lite). Treat it as configuration, not a hardcoded string buried in a function — you will want to route by tier later.

The prompt

The prompt is the primary creative input. It should describe subject, action, setting, and style in that order of importance. A scene without an action is an image; the action clause is what makes it video. We will cover prompt structure in depth later.

The motion mode

Motion mode steers how the model interprets camera and subject movement. It is the parameter most often ignored and most often responsible for output that “looks wrong” despite a good prompt. Align it with what your prompt describes rather than leaving it at a default.

Output and delivery

Video generation is asynchronous. The call returns a job you track to completion, then you retrieve the resulting asset by its reference. Because rendering takes real time, your client must handle the waiting period explicitly — polling or webhook-style completion checks — rather than assuming an inline response. Pricing follows output seconds, so keep duration intent in mind from the first draft.

Choosing motion modes that match your prompt

Motion mode is a strong prior. It tells the model what kind of movement to favor before it even parses the finer details of your prompt. When the mode and the prompt disagree, the output tends to split the difference and satisfy neither.

Match the mode to the dominant movement

If your prompt describes a camera move — a slow push-in, a lateral tracking shot, an orbit around a subject — choose a motion mode oriented around camera movement. If your prompt describes a subject moving through a mostly static frame — a person walking, smoke rising, water flowing — choose a mode oriented around subject motion. If the clip should feel like a locked-off shot with subtle life, choose the most restrained option.

Keep one dominant motion per clip

Clips that try to do a camera move, a subject action, and a scene transition in a few seconds usually read as chaotic. Pick the single most important motion, set the mode to support it, and let the prompt describe supporting detail without competing movement verbs. If you need a compound sequence, generate separate clips and edit them together.

Iterate on mode before rewriting the prompt

When a result feels off but the subject and style are right, change the motion mode first. It is a cheaper experiment than rewriting a long prompt, and it isolates whether the problem was movement interpretation or content description.

A working request, step by step

The flow below is the general shape of a Grok text-to-video job on hiapi. Parameter names in the payload follow the endpoint's request schema; consult the API reference for the exact field set before shipping.

Step 1: Build the payload

Start with a structured object rather than a loose string concatenation, so you can log and reuse it.

{
  "model": "grok-imagine/text-to-video",
  "prompt": "A red kite rising over a windswept beach at dusk, camera slowly tilting up, soft golden light",
  "motion_mode": "<mode matching an upward camera tilt>"
}

Step 2: Submit the job

Send the payload to the text-to-video endpoint with your hiapi credential in the authorization header. The response returns a job identifier and a status. Persist the identifier immediately — it is your handle for everything that follows.

curl -X POST "$HIAPI_BASE_URL/v1/video/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Step 3: Poll for completion

Rendering is asynchronous. Query the job status on an interval with backoff, and stop when the job reports a terminal state. Treat “pending” and “processing” as normal, not as errors.

Step 4: Retrieve the asset

Once the job completes, the response carries a reference to the generated video. Download it to your own storage rather than hotlinking a transient URL, so your product does not depend on the lifetime of a generation artifact.

Step 5: Record the inputs

Log the model, prompt, motion mode, and job id alongside the stored asset. When a clip is later judged good or bad, you need the exact inputs to reproduce or repair it.

Writing prompts the video model can actually execute

A video prompt is a shot description, not a mood board. The model needs concrete, physically plausible instructions it can animate across time.

Use a stable clause order

Subject, action, setting, camera, style. This order front-loads what matters and gives the model a clear hierarchy when it has to trade detail for coherence. Keep the same order across your templates so you can compare results meaningfully.

One action, stated as a verb

“A cyclist” is a still. “A cyclist pedaling uphill” is a clip. Name the action explicitly and keep it singular. If you want a secondary motion, add it as a supporting detail — “pedaling uphill, jersey fluttering” — rather than a second competing action.

Describe camera movement in plain terms

Say what the camera does: tilts up, tracks left, holds steady. Avoid ambiguous phrasing like “dynamic angles” that could mean anything. The clearer the camera instruction, the better it pairs with your chosen motion mode.

Constrain the style, not the specs

Describe lighting, palette, and texture (“soft golden light, muted colors, gentle grain”). Avoid inventing technical parameters the model does not expose — resolution and duration are request settings, not prompt content. Mixing the two confuses the model and the developer reading the log.

Keep a template library

Maintain a handful of prompt skeletons per use case — product shot, landscape, character moment — with slots for subject and action. Templates make outputs more consistent and make failures easier to attribute to a single changed variable.

Hardening the integration for production

The first successful call is the easy part. What separates a demo from a product is how the integration behaves when jobs are slow, prompts are rejected, or volume spikes.

Treat generation as a queue

Never block a user request on video rendering. Submit the job, return a job id to your client, and let a worker poll for completion and push the result when ready. This decouples your request latency from render latency and lets you retry without re-prompting users.

Retry with backoff, and only on retryable failures

Transient errors and timeouts deserve exponential backoff with jitter. Validation errors — a malformed prompt or an unsupported field — will fail identically every time; surface those to the caller instead of burning retries. Classify errors explicitly in your client code.

Tier your models

Route drafts to grok-imagine-1.5-lite and finals to grok-imagine/text-to-video. Because billing follows output seconds, the draft tier is where you control spend: converge on a prompt cheaply, then promote it. Cap concurrent jobs per user to prevent runaway generation loops.

Version your prompts

Store prompts with a version tag and log which version produced which asset. When you change a template, you can compare against prior output and roll back a regression instead of guessing.

Validate assets or discard them

Run a lightweight check on retrieved videos — file integrity, expected duration, non-empty content — before showing them to a user. A cheap validation step prevents broken players in front of customers and tells you when a model variant is behaving unexpectedly.

With one endpoint, two model tiers, and deliberate motion modes, the Grok text-to-video API fits cleanly into a production pipeline. Start with a single prompt on grok-imagine/text-to-video, get the loop working end to end, then add the lite tier for iteration.