Blog

Tutorial

How to Use gemini-omni-flash/text-to-video via the HiAPI API: curl and Python Guide

Nov 12, 2026 12 min read
Cover image: layered beige paper sheets spread out in a staggered arrangement, accented by a single ochre-red page, forming a restrained rhythm of strata.
On this page

What this endpoint does and when to use it

gemini-omni-flash/text-to-video is a generation endpoint on HiAPI that turns a text prompt — optionally anchored to a first-frame image — into a short video clip. You send one request, HiAPI returns a task you can poll, and when the job finishes you get back a video URL you can download or stream.

Reach for this endpoint when you need:

  • Fast concept clips. Short marketing teasers, storyboard previews, or social cutaways generated straight from a sentence or two of description.
  • Image-guided motion. You already have a still frame — a product shot, a character design, an illustration — and want it to move rather than start from nothing.
  • Batch generation inside a pipeline. Because generation is asynchronous, you can fire off many jobs from a backend worker and collect results later without holding a request open.

It is not the right tool for long-form video, frame-accurate editing, or deterministic reproduction of a specific shot. Think of it as a fast generative first draft: cheap to iterate on, good enough to review, and scriptable end to end.

Everything below goes through the same HiAPI interface — one API key, one base URL, one request shape — so the code you write here transfers to other generation endpoints without relearning auth or polling.

Before you send your first request

Four things need to be in place before your first call succeeds.

1. An API key

Create a key in your HiAPI account and keep it in an environment variable rather than in source code:

export HIAPI_API_KEY="your_key_here"

2. The base URL and endpoint path

All requests go to the HiAPI base URL with the model identifier in the path. Treat the base URL as a single constant in your code so you only change it in one place:

export HIAPI_BASE_URL="https://api.hiapi.ai"

3. JSON request bodies

Requests are POST with Content-Type: application/json and a bearer token in the Authorization header. There is no form encoding and no multipart upload unless you are supplying a first-frame image by URL.

4. A first frame, if you want one

If you plan to guide generation with an image, have it accessible at a public HTTPS URL before you start. Local filesystem paths will not work — the API fetches the image server-side.

One practical note on cost awareness: this endpoint is billed by the output you generate — resolution tier and clip duration both factor in. Current per-unit pricing lives on the HiAPI pricing panel, so check there before you scale a batch job. The important habit is to prototype at the smallest settings and only raise them once the prompt is producing what you want.

Building the generation request

A request has three conceptual parts: the model path, the prompt (and optional image), and the generation options. Structurally it looks like this:

{
  "prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
  "image": "https://your-bucket.example.com/first-frame.jpg",
  "resolution": "720p",
  "duration": 5,
  "audio": false
}

The prompt

The prompt field carries the description of the shot. Write it like a director's note: subject, camera behavior, lighting, and mood. Concrete motion verbs ("slow dolly-in", "camera pans left", "steam curls upward") steer the result far more reliably than adjectives alone.

The optional first frame

The image field is optional. Omit it and the model generates the whole clip from text. Include it and the clip begins from that frame, with the prompt describing what should happen next. This is the single biggest lever on consistency: a text-only prompt will reinvent the scene each run, while a fixed first frame keeps composition stable across iterations.

If you supply both, make sure they agree. A first frame of a desert landscape paired with a prompt about a rainy city street produces a confused result — the model has to reconcile two contradictory instructions.

Where options live

resolution, duration, and audio sit at the top level of the same JSON body alongside prompt and image. There is no nested options object to remember. Keep the body flat and readable — it makes logging and diffing requests much easier when you are debugging a batch.

Choosing resolution and duration

Two parameters dominate both the look of your output and what the job costs: resolution tier and clip duration.

Resolution tiers

HiAPI exposes the endpoint at more than one resolution tier. The lower tier is the right default during prompt development — it renders faster and lets you iterate on wording without paying for detail you are about to throw away. Once a prompt reliably produces the composition you want, move up a tier for the final render.

A useful workflow:

  1. Draft the prompt at the lowest tier.
  2. Generate two or three variants and compare.
  3. Lock the prompt, then re-render at the higher tier.

Clip duration

Duration is specified in seconds and the endpoint is designed around short clips. Keep durations modest: short clips keep individual jobs fast, make failures cheap to retry, and let you stitch several clips into a longer sequence later if you need one. If a shot needs eight seconds of screen time, two four-second generations are usually easier to control than one long one.

How this maps to budget

The endpoint is billed by the output you produce — higher resolution and longer duration both increase the billable output of a single job. Because pricing is per generated unit and tiers change over time, read the live numbers on the HiAPI pricing panel rather than hardcoding expectations. The planning rule that survives any price change: multiply your expected job count by your output size, prototype at the smallest setting, and scale resolution last.

Controlling native audio

The audio flag decides whether the returned video carries a native audio track generated alongside the visuals.

{
  "prompt": "Rain hammering a tin roof, a door creaks open slowly",
  "audio": true
}

What changes when it is on

With audio: true, the model produces sound matched to the scene described in your prompt — ambience, environmental texture, and sound events implied by the action. The output video arrives with an audio stream attached, so the file you download is already complete and does not need a separate sound pass.

What changes when it is off

With audio: false, you get a silent video. This is the right choice when:

  • You will lay your own music or voiceover over the clip in an editor.
  • The clip is a background element in a larger composition.
  • You are iterating on visuals only and do not want audio generation in the loop.

Prompting for audio

If audio is enabled, describe the soundscape the way you describe the picture. Sound cues in the prompt — rain, footsteps, machinery, a specific room tone — give the audio model something to work with. A purely visual prompt still produces audio, but it will be generic ambience rather than something that matches the shot.

One caveat worth testing early: audio changes the character of a clip significantly. Generate the same prompt with the flag on and off once, watch both, and decide which mode your project actually needs before you build a batch around it.

Handling the async job lifecycle

Video generation takes longer than a typical HTTP request should stay open, so the endpoint is asynchronous. Every call follows the same three-step loop.

Step 1: Submit

POST your JSON body to the endpoint. A successful submission returns immediately with a job identifier — typically a task id — and a status indicating the job is queued or processing. Nothing has been rendered yet at this point.

Step 2: Poll

Take the task id and query the task status endpoint at a fixed interval. Each poll returns the current state: queued, processing, completed, or failed. You need to handle all four. A simple exponential backoff — start around a couple of seconds, cap the interval — keeps you from hammering the API on long jobs while still catching fast ones quickly.

Step 3: Fetch

When the status reports completion, the response carries the URL of the finished video along with the metadata for that job. Download it, store it, or hand the URL to your frontend. If the status reports failure, capture the error message from the response and decide whether to retry with a modified prompt or surface the failure.

Guardrails to build in

  • A timeout ceiling. Cap total polling time (for example, a few minutes) and fail the job in your own code rather than looping forever.
  • A maximum poll count. Prevents runaway loops if a status ever stays ambiguous.
  • Persist the task id. Write it to your database or logs the moment you receive it. If your process crashes mid-poll, you can resume rather than regenerate and pay twice.
  • Idempotent submission. Do not resubmit on a network hiccup before confirming the first request failed; a duplicate job costs real output.

Get this loop right once and it works for every asynchronous endpoint on HiAPI.

Runnable curl and Python examples

curl: submit, poll, fetch

Set your key and base URL from the environment, then submit:

curl -sS -X POST "$HIAPI_BASE_URL/v1/models/gemini-omni-flash/text-to-video" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A slow dolly-in on a glass coffee cup as steam curls upward, morning light, shallow depth of field",
    "image": "https://your-bucket.example.com/first-frame.jpg",
    "resolution": "720p",
    "duration": 5,
    "audio": false
  }'

The response contains a task id. Capture the status endpoint from the response and poll it:

curl -sS "$HIAPI_BASE_URL/v1/tasks/<TASK_ID>" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Repeat until the status is completed, then take the video URL from the response body and download it:

curl -sS -o clip.mp4 "<VIDEO_URL>"

Python: the same loop, wrapped

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}


def generate_video(prompt, image_url=None, resolution="720p",
                   duration=5, audio=False, timeout=300):
    payload = {
        "prompt": prompt,
        "resolution": resolution,
        "duration": duration,
        "audio": audio,
    }
    if image_url:
        payload["image"] = image_url

    resp = requests.post(
        f"{BASE}/v1/models/gemini-omni-flash/text-to-video",
        headers=HEADERS, json=payload, timeout=30,
    )
    resp.raise_for_status()
    task_id = resp.json()["id"]
    print(f"submitted: {task_id}")

    deadline = time.time() + timeout
    interval = 2
    while time.time() < deadline:
        status_resp = requests.get(
            f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30
        )
        status_resp.raise_for_status()
        data = status_resp.json()
        state = data.get("status")

        if state == "completed":
            return data["video_url"]
        if state == "failed":
            raise RuntimeError(f"job failed: {data}")

        time.sleep(interval)
        interval = min(interval * 1.5, 10)

    raise TimeoutError(f"job {task_id} did not finish in {timeout}s")


if __name__ == "__main__":
    url = generate_video(
        "A slow dolly-in on a glass coffee cup as steam curls upward, "
        "morning light, shallow depth of field",
    )
    print("video ready:", url)

The script submits a text-only job, polls with backoff, enforces a timeout ceiling, and returns the finished URL. Pass image_url= to anchor generation to a first frame, or set audio=True to include native sound. From here you can drop generate_video into a worker queue, a FastAPI route, or a batch loop — the function is self-contained and stateless apart from the job id it creates.

Common failure points and how to avoid them

Most failed integrations hit one of these five issues.

Invalid parameters rejected at submit

The most common cause is a body the API cannot parse: a missing prompt, a duration outside the supported range, or an unsupported resolution string. Check the endpoint reference for the accepted values and validate on your side first. A small helper that asserts allowed values before the call saves a round trip and a confusing error.

An unreachable first-frame image

The API fetches image server-side, so a URL that works in your browser may still fail — private buckets, expiring signed links, and hotlink protection all cause this. Use a publicly readable HTTPS URL and verify it resolves from outside your network before submitting.

Abandoned polling

Two variants of the same mistake: giving up on the first processing response and assuming failure, or polling so aggressively that you hit rate limits. Fix both with the backoff-plus-ceiling loop shown above: poll on a schedule, treat non-terminal states as normal, and raise only on explicit failure or timeout.

Losing the task id

If the process dies after submission but before the result is saved, the job is paid for and unreachable. Write the task id to durable storage immediately after submission, and on startup check for any ids still in flight before submitting new work.

Oversized outputs at scale

Generating a large batch at high resolution and long duration multiplies output volume quickly, and the generated files are large to store and slow to serve. Prototype small, render finals once, and keep your storage lifecycle rules in place. Because billing is tied to generated output, the cheapest fix is almost always a smaller prototype iteration loop.

Work through this list once in a staging environment and your production path will be smooth.

Related articles

View all articles →

Start building with persistent AI artifacts

Get your API key and call image, video and audio models through one task-based API.

Read the API docs