imagen4-fast API: A Working Text-to-Image Request

Imagen 4 Fast is Google's speed tier in the Imagen 4 family, and on hiapi it runs text-to-image through the same unified async task API as every other image model. This guide gives you one request that actually works — a real curl call, a Python poll loop, the exact closed input schema, and the error cases verified against a live run. Everything below was executed against the production endpoint before publishing; the sample taskId and output URL come from that run.

What you'll build

A single call that turns a text prompt into a finished image: submit a task to POST /v1/tasks, poll until it's done, and read the image URL. You need a hiapi API key (create one from your dashboard and keep some pay-as-you-go credits on the account — see pricing). No SDK is required; every example here is plain HTTP.

Minimal working request (curl)

Create the task. The model id is imagen4-fast, and aspect_ratio is required on this tier (more on that below):

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "imagen4-fast",
    "input": {
      "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
      "aspect_ratio": "16:9"
    }
  }'

The create call returns only a task handle — not the image:

{ "code": 200, "data": { "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A" }, "message": "success" }

Poll for the result (Python)

Take the taskId and poll GET /v1/tasks/<id> until the status is terminal. This is the loop I actually ran:

import os, time, requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

# 1. create the task
created = requests.post(API, headers=HEADERS, json={
    "model": "imagen4-fast",
    "input": {
        "prompt": "Colorful isometric city block with tiny cars and trees; playful 3D illustration",
        "aspect_ratio": "16:9",
    },
}).json()
task_id = created["data"]["taskId"]

# 2. poll until the task reaches a terminal state
while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS).json()["data"]
    status = data["status"]
    if status == "success":
        print(data["output"][0]["url"])   # the finished image
        break
    if status == "fail":
        raise RuntimeError(data)
    time.sleep(3)

On my run the status moved handling → archiving → success in about 12 seconds, and the terminal payload looked like this:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M5D4ZD2X353AHHW3SW8X8N0A",
    "model": "imagen4-fast",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M5D4ZD2X353AHHW3SW8X8N0A-0.webp",
        "expireAt": 1793121346
      }
    ]
  },
  "message": "success"
}

One task returns one WebP image. The archiving state is normal — it sits there briefly before flipping to success.

The input schema (what the server actually accepts)

The input object is a closed schema. These are the only fields it takes:

There is no resolution or size field on this model — output dimensions follow aspect_ratio. Any field outside this table is rejected.

Verified error cases (the gotchas)

These aren't guesses — each is a real 400 response captured against the live endpoint.

1. Missing aspect_ratio. This is the #1 trap when you copy a snippet from the base Imagen 4 or Ultra tier, where aspect_ratio defaults to 1:1. On Fast it has no default:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: aspect_ratio: missing required field \"aspect_ratio\"; prompt: minLength: got 0, want 1" }

2. seed sent as a string. Pass it as a number:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: seed: got string, want integer" }

3. An unknown field (here resolution) — the closed schema rejects anything extra:

{ "code": 400, "error_code": "INVALID_REQUEST",
  "message": "invalid input: <root>: additional properties 'resolution' not allowed" }

Note the shape: validation failures are HTTP 400 with error_code: "INVALID_REQUEST", no taskId, and a message that aggregates every field error into one ;-separated string — so read the whole thing, not just the first clause.

Fast vs the rest of the Imagen 4 family

hiapi hosts three Imagen 4 tiers on the identical task API; only the model id changes, so the request body above is portable across all of them:

• imagen4-fast — the speed tier (model page) and the lowest-cost option in the family. Pick it for prompt iteration, concept exploration, and batch direction-finding where you generate many candidates and keep a few.
• Google-Imagen4 — the standard Imagen 4 tier.
• imagen4-ultra — the highest-detail tier, for delivery-grade finals.

A practical workflow: prototype on Fast, then swap the model string to imagen4-ultra for the final render without touching any other code. Compare current per-image rates on the pricing page.

Production notes

• Polling vs. webhook. The loop above polls. For production, hiapi's task API also supports a webhook: add a top-level callback object (a sibling of model/input) with a url and when: "final", and hiapi POSTs the task detail when it reaches a terminal state. See the async API docs for the delivery and retry contract before you rely on it.
• Don't resubmit on a flaky network. Creating a task returns a fresh taskId every time — there's no dedupe on prompt. If a poll request fails transiently, re-poll the taskId you already saved; only re-POST when you never received one.
• Output URLs expire. The output[].url lives on temp.hiapi.ai with an expireAt roughly 7 days out (the sample above expires 2026-10-28). Download the bytes to your own storage right away; don't hotlink.

Related

• Imagen 4 Fast model page
• Imagen 4 Ultra — highest-detail tier, same request shape
• Imagen 4 (base)
• Unified async task API docs
• Pricing

FAQ

Do I need a different endpoint or SDK for Imagen 4 Fast? No. It's POST /v1/tasks with "model": "imagen4-fast" — the same endpoint every hiapi image and video model uses. Switch tiers by changing the model id.

Why did my request 400 with "missing required field aspect_ratio"? Fast has no default aspect ratio (unlike the base and Ultra tiers). Always send aspect_ratio from the enum 1:1 | 16:9 | 9:16 | 3:4 | 4:3 | auto.

Can I set the resolution or image size? No — there's no resolution or size field on this model; output dimensions follow aspect_ratio. Sending resolution returns additional properties 'resolution' not allowed.

Is seed a string or a number? A number. "seed": 7 works; "seed": "7" returns seed: got string, want integer.

How long is the output URL valid? About 7 days (expireAt). Download and store it immediately.