Tutorial
How to Call gemini-omni-1.1-flash via the HiAPI API: curl and Python Guide
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
POSTto the endpoint path taken from the API reference, prefixed by your base URL. Authorizationheader — carries the bearer token. A missing or empty variable here is the single most common cause of a 401.Content-Typeheader — must beapplication/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.dumpsrather than relying on form encoding, which will not produce the nestedinputobject 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
- Model swaps are one line. When a newer model arrives, you change the constant and the default parameters; call sites are untouched.
- Optional parameters are handled correctly. Omitted values are not sent, which avoids the null-rejection problem described earlier.
- Polling is invisible. Callers get a result or an exception, never a job ID they must manage themselves.
- Testing gets easy. You can stub
post_jsonandwait_for_jobindependently, 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 →-
Tutorial
kling-image-4.0 Real-World Use Cases: 5 High-Value Applications and Integration Essentials
-
Tutorial
How to Use qwen-image-2.0-pro via the HiAPI API: curl, Python, and a Working Request
A hands-on integration walkthrough for developers: first successful call, request anatomy, and troubleshooting
8 min read -
Tutorial
How to Call the veo-3.1 Text-to-Video API: curl and Python Examples
A hands-on integration walkthrough for developers
8 min read