How to Use Imagen 4 API: First Image in 5 Minutes

TL;DR

• Imagen 4 (imagen-4.0) is a text-to-image model at $0.06 per image: one prompt, one aspect ratio, one image — built for portrait photography, natural close-ups, and product stills. Try it on the model page; new accounts get 200 free credits.
• The series has two more tiers: imagen-4.0-fast at $0.03 for high-volume drafting, and imagen-4.0-ultra at $0.09 for finished-detail output.
• Everything runs on the HiAPI /v1/tasks endpoint: submit for a taskId, poll for the result, then download from output[0].url.

What it does

• Text to image, no reference needed: the prompt describes the whole frame, and aspect_ratio is required (1:1, 16:9, 9:16, 3:4, 4:3, auto).
• Three tiers, one family: Fast for drafts, standard for everyday production, Ultra for detail — three model IDs you can stage across one project.
• One image per call: no batch count, pixel size, or output format parameters; change the seed to reroll.

Here's a real output from the standard tier:

Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography

imagen-4.0, 16:9, 1280×720, $0.06.

Try this prompt →

Three tiers: which to use

	imagen-4.0-fast	imagen-4.0 (standard)	imagen-4.0-ultra
Per image	$0.03	$0.06	$0.09
Role	High-volume drafts, picking directions	Everyday production	Finished detail, materials, lettering
$10 yields	333 images	166 images	111 images
Best for	Brainstorms, sketch rounds	Regular delivery	Final assets, detail-critical frames

Budget reference: all-standard at 1,000 images a month runs about $60.00; the more drafting volume you move to Fast, the lower the bill, while finals stay on Ultra.

The calling convention is identical across the three — change only the model field; the parameter structure matches too, except the seed type (see the table). There's a dedicated guide for each sibling: Imagen 4 Fast API guide and Imagen 4 Ultra API guide. For scene-by-scene recipes, see the prompt guide; full tier pricing and budgets are on the pricing page, and the same-prompt match-up with Nano Banana 2.1 is in the comparison.

Two ways to start

Browser, 3 steps: open the model page → paste the prompt and pick an aspect ratio → generate. A standard image is $0.06. For the first run, generate one image in the browser to confirm the style before writing code.

API, 3 steps: POST /v1/tasks to submit → take the taskId → GET /v1/tasks/<taskId> until success, then download.

curl: your first image

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-key-001" \
  -d '{
  "model": "imagen-4.0",
  "input": {
    "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
    "aspect_ratio": "16:9"
  }
}'

Switch tiers by changing model to imagen-4.0-fast or imagen-4.0-ultra. The response carries the taskId you'll poll with.

Python: submit, poll, download

import time, uuid, requests

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

payload = {
    "model": "imagen-4.0",
    "input": {
        "prompt": "Sunlit Scandinavian living room with linen sofa; oak shelves and a monstera plant; editorial interior photography",
        "aspect_ratio": "16:9",
    },
}

# Submit: the Idempotency-Key makes network retries safe
resp = requests.post(
    BASE,
    headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())},
    json=payload,
    timeout=30,
)
resp.raise_for_status()
task_id = resp.json()["taskId"]

# Poll: queued -> handling -> archiving -> success / fail
while True:
    task = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()
    print(task["status"])
    if task["status"] in ("success", "fail"):
        break
    time.sleep(3)

if task["status"] == "success":
    image_url = task["output"][0]["url"]   # temporary URL — download promptly
    img = requests.get(image_url, timeout=60)
    with open("output_image", "wb") as f:  # name the extension to match the actual format
        f.write(img.content)
    print("saved")

Parameters

Field	Required	Values	Notes
prompt	yes	1–5,000 chars	What the frame contains
aspect_ratio	yes	1:1 / 16:9 / 9:16 / 3:4 / 4:3 / auto	Output aspect, required
negative_prompt	no	≤5,000 chars	What to keep out
seed	no	standard & Ultra: string (≤500 chars); Fast: integer	Same inputs + same seed reproduce the image

All three models share this table. Any field outside it returns a 400.

Errors you'll actually hit

Status	Meaning	What to do
400 INVALID_REQUEST	Malformed body (missing prompt or aspect_ratio, bad enum value, unknown field)	Fix the payload against the parameter table
402 INSUFFICIENT_QUOTA	Out of credits (no charge)	Top up and retry
429 RATE_LIMITED	Rate limited	Slow your submission rate
409 / 422 IDEMPOTENCY_KEY_*	Same idempotency key resubmitted (processing / payload mismatch)	Generate a fresh key
415 UNSUPPORTED_MEDIA_TYPE	Wrong request format	Check Content-Type: application/json

Terminal failures use codes like CONTENT_POLICY_VIOLATION, TASK_FAILED, and TASK_TIMEOUT; failed tasks refund in full.

Before you ship

• Callbacks: pass "callback": {"url": "https://..."} at the request top level and HiAPI notifies your service at the terminal state.
• Persist outputs: output[0].url is temporary — download it into your own storage right away.
• Be explicit about aspect: aspect_ratio is required; pick 9:16 deliberately for vertical social content.
• Seed types differ by tier: Fast takes an integer, standard and Ultra take strings — convert when reusing a composition across tiers.

FAQ

Do the three models share one calling convention?

Yes — change only the model field.

Can I set pixel size or output format?

No. There are no pixel-size or format parameters; aspect_ratio sets the frame and each call returns one image.

Do failures cost anything?

No. Credits held at creation are refunded in full at the terminal failure state.

Is the rendered text reliable?

Zoom in and check. Poster-style images occasionally gain or lose a letter — inspect the lettering at full size before publishing.

Can I mix images from the three tiers in one project?

Yes. Prompts and aspect-ratio logic carry across the three tiers.

Next: copy the living-room prompt above and generate a test image, then batch-produce from the scene templates in the prompt guide.