HiAPI
Blog

Tutorial

How to Call gemini-omni-1.1-flash via the HiAPI API: curl and Python Guide

Nov 17, 2026 10 min read
Abstract architectural-style cover image: warm gray concrete planes interlock under raking daylight, with slate-blue shadows and narrow sage-colored seams.
On this page

What you need before your first request

Before writing any code, confirm four things. Each of them will save you a debugging round trip later.

An API key

Every request to HiAPI is authenticated with an API key. Generate one in your account dashboard and keep it out of source control. The examples below read it from an environment variable so the key never appears in shell history or a committed file:

export HIAPI_API_KEY="your_key_here"

The base URL and endpoint path

The base URL is the same for all HiAPI models; only the model identifier changes. Take the endpoint path and request method from the API reference rather than from a blog post, because paths are versioned and can move. Keep the base URL as a single constant in your client so a future change is a one-line edit.

The model identifier

gemini-omni-1.1-flash is passed as a string in the request payload. Copy it exactly — hyphens and the version suffix matter. If you mistype it, the error is usually a validation failure rather than a routing failure, which can be confusing; see the debugging section later.

The model page bookmarked

The gemini-omni-1.1-flash model page is the source of truth for which parameters exist, what values they accept, and how the response is shaped. Treat it as the reference you check before each change, not something you read once.

Once those four are in place, you are ready to make a call.

Send a minimal request with curl

Start with the smallest possible request. Its purpose is not to produce a good result — it is to prove that your key, the endpoint, and the payload shape all line up. Once that works, every later change is incremental.

curl -X POST "$HIAPI_BASE_URL/<endpoint-path>" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "input": {
      "prompt": "A slow dolly-in on a ceramic cup on a wooden table, soft morning light"
    }
  }'

Here is what each piece does:

  • Method and URL — the call is a POST to the endpoint path taken from the API reference, prefixed by your base URL.
  • Authorization header — carries the bearer token. A missing or empty variable here is the single most common cause of a 401.
  • Content-Type header — must be application/json. Without it the server may not parse the body at all.
  • model — the exact model identifier string.
  • input — an object holding the generation parameters. The prompt lives here; resolution and duration are added here too, as covered below.

If the call returns a job identifier or an accepted-status response rather than the finished output, that is expected — generation is asynchronous. Keep the identifier; you will need it in the polling step.

Port the same call to Python

The Python version should send the exact same JSON body. Keeping the payload identical is what makes the port trustworthy: if curl worked and Python does not, the bug is in your Python code, not in your understanding of the API.

import json
import os
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
ENDPOINT = f"{BASE_URL}/<endpoint-path>"

payload = {
    "model": "gemini-omni-1.1-flash",
    "input": {
        "prompt": "A slow dolly-in on a ceramic cup on a wooden table, soft morning light"
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

response = requests.post(ENDPOINT, headers=headers, data=json.dumps(payload), timeout=30)
response.raise_for_status()
print(response.json())

A few habits worth adopting immediately:

  • Build the URL from constants, not string concatenation scattered through the code.
  • Set an explicit timeout. Without one, a stalled request can hang a worker indefinitely.
  • Call raise_for_status() so an error response surfaces as an exception instead of being silently parsed as a success body.
  • Serialize with json.dumps rather than relying on form encoding, which will not produce the nested input object correctly.

With this working, you have a reusable request shape. The next two sections add the parameters that actually control the output.

Configure resolution and duration in the request

Resolution and duration are ordinary fields inside the input object, alongside the prompt. Conceptually the payload looks like this:

{
  "model": "gemini-omni-1.1-flash",
  "input": {
    "prompt": "...",
    "resolution": "<supported-value>",
    "duration": "<supported-value>"
  }
}

The critical rule: do not hardcode these values from memory or from a tutorial you read months ago. Supported values change as models are updated, and an unsupported value produces a validation error that looks like a payload bug. Always confirm the current accepted values on the model page before setting them.

A practical pattern

Keep the values in configuration rather than in code:

payload = {
    "model": "gemini-omni-1.1-flash",
    "input": {
        "prompt": prompt,
        "resolution": settings.resolution,
        "duration": settings.duration,
    },
}

This gives you three benefits. You can change output quality without touching logic. You can run cheap low-resolution tests during development and only raise it for final renders. And when the platform adds a new supported value, you update one config field instead of hunting through the codebase.

Two quieter pitfalls are worth calling out. First, resolution and duration usually interact with cost — billing is typically tied to the output produced, so a longer, higher-resolution clip is not free. Second, if a field is optional, omit it rather than sending an empty string or null; some validators reject explicit nulls even when the field itself is optional.

Handle async generation: submit, then poll

Generation takes time, so the API follows a submit-then-poll pattern. Your client must treat these as two distinct operations with different retry semantics.

Step 1: submit

The submit call is the request you already built. It returns an identifier for the job — a job ID, task ID, or similar field depending on the endpoint. Parse it defensively:

created = response.json()
job_id = created.get("id") or created.get("job_id")
if not job_id:
    raise RuntimeError(f"No job identifier in response: {created}")

Step 2: poll

Then poll a status endpoint with that identifier until the job reaches a terminal state. A robust loop has four properties: a maximum wait, a backoff, a terminal-state check, and a failure check.

import time

def wait_for_job(job_id, timeout=600, initial_delay=2, max_delay=30):
    deadline = time.time() + timeout
    delay = initial_delay
    while time.time() < deadline:
        status = fetch_status(job_id)          # GET on the status endpoint
        state = status.get("status")
        if state in ("succeeded", "completed"):
            return status
        if state in ("failed", "error", "cancelled"):
            raise RuntimeError(f"Job {job_id} ended in state {state}: {status}")
        time.sleep(delay)
        delay = min(delay * 2, max_delay)
    raise TimeoutError(f"Job {job_id} did not finish within {timeout}s")

Why the details matter

  • Exponential backoff keeps you from hammering the status endpoint while a job that takes a minute to render is still queued.
  • A hard deadline prevents a stuck job from blocking a worker forever. Log the job ID on timeout so you can inspect it manually.
  • Explicit terminal states mean you never loop on a status you did not anticipate. Treat unknown states as "keep waiting" but log them once.
  • Separate retry policies: retrying a submit call is riskier than retrying a status call, because it may create a duplicate job. Retry the poll freely; retry the submit only on clear transport errors.

Debug the common failure modes

Most failures fall into a small number of buckets. Work through them in this order, because a later symptom is often caused by an earlier problem.

Authentication errors

Symptom: 401 or 403. First thing to check: is the key actually present in the environment where the process runs? Printing len(API_KEY) catches the classic case of an unset variable producing an empty bearer token. Then confirm the header format is Bearer <key> with a single space, and that the key has not been revoked or scoped to a different project.

Malformed payloads

Symptom: 400 with a complaint about the body or a missing field. First thing to check: compare your body against the working curl request. Common causes are a missing Content-Type: application/json header, sending form-encoded data instead of JSON, a flat input object where the API expects nesting (or the reverse), and an accidentally cast field — a numeric duration sent as a quoted string can fail validation.

Unsupported parameter values

Symptom: 400 or 422 naming a specific field such as resolution or duration. First thing to check: the model page, where the currently supported values are listed. This is almost always a stale hardcoded value rather than a code bug. If a value that used to work now fails, assume the model was updated and re-read the docs before assuming an outage.

Model identifier typos

Symptom: a validation or not-found error that does not mention your prompt. First thing to check: print the model string and compare it character by character against the docs. A trailing space or a swapped version number is easy to miss.

Timeouts and transient failures

Symptom: connection timeouts, 429s, or 5xx responses. First thing to check: whether you sent a timeout at all. Add one, then add bounded retries with backoff for 429 and 5xx only — do not retry 4xx errors other than 429, since the request will fail identically every time. For long jobs, remember the eventual result is retrieved by polling; a timeout on the submit call is not the same as a failed generation.

Results that are technically valid but wrong

The request succeeds but the output misses the mark. This is a prompt problem, not an API problem. Make prompts specific about subject, camera movement, lighting, and pacing, and change one variable at a time so you can attribute the difference.

Wrap it in a reusable client function

The goal of the wrapper is simple: your business logic should never contain the model identifier, a parameter name, or a polling loop. Everything model-specific lives in one place.

def generate_video(prompt, *, resolution=None, duration=None, timeout=600):
    payload = {
        "model": "gemini-omni-1.1-flash",
        "input": {"prompt": prompt},
    }
    if resolution is not None:
        payload["input"]["resolution"] = resolution
    if duration is not None:
        payload["input"]["duration"] = duration

    created = post_json(ENDPOINT, payload)
    job_id = created.get("id") or created.get("job_id")
    if not job_id:
        raise RuntimeError(f"No job identifier: {created}")

    return wait_for_job(job_id, timeout=timeout)

What this buys you

  1. Model swaps are one line. When a newer model arrives, you change the constant and the default parameters; call sites are untouched.
  2. Optional parameters are handled correctly. Omitted values are not sent, which avoids the null-rejection problem described earlier.
  3. Polling is invisible. Callers get a result or an exception, never a job ID they must manage themselves.
  4. Testing gets easy. You can stub post_json and wait_for_job independently, testing payload construction and polling logic in isolation.

Layer the pieces

Keep the structure flat and explicit: a transport layer (HTTP, headers, timeouts, retries), a model layer (payload construction for gemini-omni-1.1-flash), and a job layer (submit and poll). The single generate_video function composes them, and each layer remains small enough to reason about when something breaks.

Start with curl to confirm the wiring, move to Python for real work, read the model page whenever parameters change, and keep the polling loop behind an interface so it never leaks into your application code.

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