Blog

Tutorial

How to Use gemini-omni-flash for Video Generation via the HiAPI API

Text-to-video and image-to-video request paths, model selection, and a working integration checklist

Nov 9, 2026 11 min read
A geometric cover of split prisms in sage and deep pine tones, marking the article's cover.
On this page

Why gemini-omni-flash Has Two Video Endpoints

Before you write a single line of code, the most important decision is which of the two video endpoints you actually need. gemini-omni-flash is exposed on HiAPI as two separate models, not one endpoint with a mode flag:

  • gemini-omni-flash/text-to-video — generates a video from a text prompt alone.
  • gemini-omni-flash/image-to-video — generates a video using a supplied source image as the visual anchor, guided by a text prompt.

The split exists because the two tasks have different inputs, different validation rules, and different failure modes. Text-to-video only has to validate a prompt string. Image-to-video additionally has to fetch and decode your source image, so it has an extra class of errors (unreachable URL, unsupported format, oversized asset) that simply cannot occur on the text path.

As a rule of thumb: if you already have a still image — a product shot, a storyboard frame, a photo — use image-to-video, because the model starts from your visual content instead of inventing it. If you are starting from an idea with no reference material, use text-to-video.

Keep the two model IDs distinct in your codebase from day one. Treating them as one "video" concept and bolting on an if has_image flag later is how integrations end up with tangled payloads and confusing bugs.

What stays the same

Both endpoints share the same authentication scheme, the same base URL, the same general request/response conventions, and the same billing model (video is billed by generated output, not by request count). That shared surface is what makes a single request builder viable — more on that later.

What differs

Only the payload shape and the input validation differ. That is a small enough delta that you can support both endpoints without duplicating your whole integration.

Prerequisites and API Setup

You need three things before your first call.

1. An API key

Create a key in your HiAPI account and store it as an environment variable rather than hardcoding it:

export HIAPI_API_KEY="your_key_here"

Every request authenticates with a bearer token in the Authorization header. There is no separate signing step and no per-request nonce.

2. The base URL and model naming convention

All calls go to the single HiAPI base URL, and the model is selected by the model field in the request body. Model IDs follow a family/variant pattern, which is why the video models read as gemini-omni-flash/text-to-video and gemini-omni-flash/image-to-video. You swap endpoints by changing one string, not by changing hosts.

3. A tool to make requests

curl is enough to verify connectivity, and Python (with requests) is enough to build the real integration. Neither requires a vendor-specific SDK — the API is plain JSON over HTTPS.

Sanity check

Before generating any video, confirm your key works and your network path is clean by hitting a lightweight endpoint (for example, listing available models). If that fails, you are debugging credentials or connectivity, not video generation — and knowing which one saves a lot of time.

A quick checklist:

  • Key exported in the shell that will run the request.
  • Base URL noted and used consistently (no trailing-slash drift between scripts).
  • Content-Type: application/json set on every POST.
  • A way to view raw JSON responses without truncation.

Making a Text-to-Video Request

Start with the smallest request that can possibly succeed. Resist the urge to fill in every optional parameter on the first attempt — if a minimal request fails, you know the problem is structural; if it succeeds, every parameter you add afterwards is an isolated change you can attribute a regression to.

Minimal shape

A text-to-video request sends a model ID and a prompt:

{
  "model": "gemini-omni-flash/text-to-video",
  "prompt": "A slow push-in on a rain-soaked neon street at night, reflections on wet asphalt, cinematic"
}

That is the whole payload. Send it, confirm you get a successful response object back, and only then start enriching it.

Evolving the request

Once the minimal call works, add parameters one at a time and re-verify after each addition. Typical additions on the text path:

  • Prompt detail — subject, motion, camera behavior, lighting, and mood. Vague prompts produce vague motion; describe what moves and how the camera behaves.
  • Duration / output length — video is billed by generated output, so length directly affects cost. Pin it explicitly rather than relying on a default you have not checked.
  • Aspect ratio or resolution, if the model exposes it, to match your downstream player or social format.

Prompt-writing notes that actually matter

Text-to-video quality is dominated by prompt specificity. Three habits help:

  1. Describe motion, not just content. "A paper boat drifting down a gutter" gives the model something to animate; "a paper boat" does not.
  2. State the camera. Static, pan, push-in, handheld — camera language resolves a lot of ambiguity.
  3. Keep it to one scene. Multi-shot descriptions in a single short clip tend to produce mush.

When a text-to-video result is poor, change the prompt before you touch any technical parameter.

Making an Image-to-Video Request

The image path is structurally identical to the text path with one addition: the source image. Everything you learned about minimal-first testing applies here too.

Minimal shape

{
  "model": "gemini-omni-flash/image-to-video",
  "prompt": "Gentle handheld drift, subject turns slightly toward camera, soft window light",
  "image": "https://your-cdn.example.com/source-frame.jpg"
}

The prompt now describes motion and camera behavior relative to the image, not the scene content — the image already supplies the content. This is the single most common conceptual mistake: people write a full scene description and then wonder why the output ignores their source frame.

How the source image is supplied

The image is passed as a reference the service must be able to fetch. Two practical consequences:

  • The asset must be publicly reachable by the service, not behind your localhost, a VPN, or an auth-walled bucket. A signed URL with a short expiry is fine as long as it is still valid when the request runs.
  • The format and size must be supported. Stick to common web formats and reasonable dimensions. A 40 MB TIFF is a debugging session waiting to happen.

If your images live in a private store, generate a short-lived signed URL at request time rather than trying to make the bucket public.

Practical differences from the text path

  • Prompt role shifts from describe the scene to describe the motion.
  • Validation grows an asset-fetch step, so an entirely new failure class appears (see the debugging section).
  • Output framing is constrained by the source image's aspect ratio, which affects how you plan downstream layout.

Test the image URL in a browser first. If it does not load cleanly for you, it will not load for the service either.

Calling the API from curl and Python

Get the same request working in two places: the terminal (for fast iteration and raw visibility) and your codebase (for real use).

curl

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-flash/text-to-video",
    "prompt": "A slow push-in on a rain-soaked neon street at night, cinematic"
  }'

Swap the model string to gemini-omni-flash/image-to-video and add the image field to hit the other endpoint — nothing else changes.

Use -sS so errors are not silently swallowed, and pipe through a JSON formatter when inspecting responses so nested fields are readable.

Python

import os
import requests

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
    "Content-Type": "application/json",
}

payload = {
    "model": "gemini-omni-flash/text-to-video",
    "prompt": "A slow push-in on a rain-soaked neon street at night, cinematic",
}

resp = requests.post(BASE_URL, headers=HEADERS, json=payload, timeout=300)
resp.raise_for_status()
print(resp.json())

Two details worth copying: read the key from the environment, and set a generous timeout. Video generation is not an instant request — a 10-second default timeout will produce spurious failures that look like API errors but are just your client giving up early.

For image-to-video, add one line:

payload["model"] = "gemini-omni-flash/image-to-video"
payload["image"] = "https://your-cdn.example.com/source-frame.jpg"

Always print or log the raw response body on non-2xx status codes before raising. The error text usually names the offending field directly.

Structuring Your Integration Code

Once both paths work in isolation, the temptation is to leave two near-identical functions in the codebase. A slightly better structure costs almost nothing and pays off the moment you add a second video model.

Two shared pieces

A request builder. One function that takes intent-level arguments and returns a payload dict:

def build_video_payload(prompt, image_url=None, duration=None):
    if image_url:
        payload = {
            "model": "gemini-omni-flash/image-to-video",
            "prompt": prompt,
            "image": image_url,
        }
    else:
        payload = {
            "model": "gemini-omni-flash/text-to-video",
            "prompt": prompt,
        }
    if duration:
        payload["duration"] = duration
    return payload

The endpoint choice becomes a consequence of "do I have an image?", which mirrors the actual product decision. Callers never touch model IDs directly.

A response handler. One function that separates transport errors from payload errors from model-level failures, and returns a normalized result object (status, video reference, raw body for logging). Every caller goes through it, so error semantics stay consistent across both endpoints.

Why this earns its keep

  • One place to change model IDs. When you move to a different video model, you edit the builder, not fifteen call sites.
  • Consistent error handling. Image-fetch failures and prompt-validation failures get surfaced to your UI the same way.
  • Testable without network calls. The builder is pure; you can unit-test payload shapes cheaply.
  • Billing visibility. Because video is billed by generated output, a single handler is the natural place to log duration and output size for cost tracking.

Keep the builder thin. Business logic about what to generate belongs in the caller; the builder should only know how to express that intent in the API's shape.

Debugging Common Request Failures

Nearly every early failure falls into one of three buckets. Isolate the bucket first, then fix.

Bucket 1: Request shape

Symptoms: immediate 4xx, error message mentioning a missing or unknown field, or a malformed-JSON complaint.

Checks, in order:

  1. Valid JSON? Paste the body into a linter. A single trailing comma from hand-editing a payload is a classic.
  2. Exact model ID? gemini-omni-flash/text-to-video is not the same string as gemini-omni-flash-text-to-video. Typos here produce "model not found" errors that read like auth problems.
  3. Headers complete? Authorization and Content-Type: application/json both present.
  4. Wrong endpoint for the model? Sending an image field to the text endpoint will not do what you want — the field is either rejected or ignored, and either way you get the wrong result.

Bucket 2: Input asset (image path only)

Symptoms: the request is accepted but fails during processing, or errors mention fetching or decoding the image.

Checks:

  1. Open the image URL in a private browser window with no cookies. If it does not load, the service cannot load it either.
  2. Confirm the URL is not a localhost address, a private-network host, or an expired signed link.
  3. Confirm the format is a common web format and the file size is sane.
  4. Confirm the response is actually an image — a CDN that returns an HTML error page with a 200 status is a surprisingly common trap.

Bucket 3: The model call itself

Symptoms: valid request, reachable asset, but generation fails or is rejected — often content-policy or capacity related.

Checks:

  1. Reduce to the minimal prompt and retry. If that works, your prompt is the variable.
  2. Check that your client timeout is long enough — a client-side timeout looks identical to a server failure in logs unless you check whether a response ever arrived.
  3. Enable full request/response logging (with the key redacted) so you can tell these three buckets apart at a glance.

A debugging order that works

Minimal payload → verify → add the image → verify → add optional parameters one by one → verify. When something breaks, the last change you made is the culprit. Most integration pain disappears simply by refusing to debug more than one variable at a time.

Start from the smallest working call for each endpoint, wrap it in the shared builder and handler, and expand from there — that path keeps both text-to-video and image-to-video predictable as your integration grows.

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