How to use gpt-image-2-beta via the hiapi API: parameters, code, and a working example

gpt-image-2-beta is the stripped-down, flat-priced route into GPT Image 2 on hiapi: two input fields, one price, no aspect-ratio or quality knobs. This guide shows the smallest working example, the exact parameter schema (confirmed by probing the live endpoint), and how it compares to the default gpt-image-2/text-to-image route so you know when to reach for which.

Prerequisites

You need an API key from the API Keys page in your hiapi dashboard — keys start with sk-. Current per-image pricing is on the gpt-image-2-beta model page and the pricing page.

Like every image model on hiapi, this one runs on the unified async task endpoint:

• POST https://api.hiapi.ai/v1/tasks — create a generation task
• GET https://api.hiapi.ai/v1/tasks/{taskId} — poll task status

What's different about the beta route

gpt-image-2/text-to-image (the default route) takes aspect_ratio + resolution and prices by resolution tier ($0.03 at 1K, up to $0.06 at 4K). gpt-image-2-beta collapses all of that into a single flat $0.02-per-image price and a single optional size field — a literal pixel dimension string like "1024x1024" or "1600x900", not a ratio. If you omit size entirely, the model falls back to its own default output dimensions.

The tradeoff: you give up fine-grained ratio/resolution control in exchange for a lower, simpler price. It's a good fit when you just need "an image, cheaply" and don't care about exact framing.

Minimal working example (curl)

# 1. Create the task
curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-beta",
    "input": {
      "prompt": "a paper airplane launching off a stack of documents, flat vector illustration",
      "size": "1024x1024"
    }
  }'
# => {"code":200,"data":{"taskId":"tk-hiapi-01..."},"message":"success"}

# 2. Poll until status == "success"
TASK_ID="tk-hiapi-01..."
curl -s "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-YOUR_KEY"
# => {"code":200,"data":{"status":"success","output":[{"url":"https://..."}], ...}}

The finished image is at data.output[0].url. That URL comes with a short expireAt window — download it right away and re-host it on your own storage; don't link to it directly from production content.

A sample image generated by the curl call above (with a different prompt), using size: "1024x1024".

Python: create + poll + save to disk

import os
import time
import requests  # pip install requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
TOKEN = os.environ["HIAPI_API_KEY"]  # sk-...

def create_task(prompt: str, size: str | None = None) -> str:
    input_fields = {"prompt": prompt}
    if size:
        input_fields["size"] = size  # e.g. "1024x1024", "1600x900"
    r = requests.post(
        API_BASE,
        json={"model": "gpt-image-2-beta", "input": input_fields},
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=60,
    )
    r.raise_for_status()
    body = r.json()
    if body.get("code") != 200:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]

def wait_task(task_id: str, timeout_s: int = 300, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}",
                          headers={"Authorization": f"Bearer {TOKEN}"}, timeout=30)
        r.raise_for_status()
        task = r.json()["data"]
        if task["status"] == "success":
            return task
        if task["status"] == "fail":
            raise RuntimeError(f"task failed: {task.get('error')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

def save_image(url: str, path: str) -> None:
    resp = requests.get(url, timeout=60)
    resp.raise_for_status()
    with open(path, "wb") as f:
        f.write(resp.content)

if __name__ == "__main__":
    tid = create_task("a red panda mascot reading a book, flat pastel illustration", size="1024x1024")
    task = wait_task(tid)
    save_image(task["output"][0]["url"], "output.jpg")
    print("saved output.jpg")

Parameter reference

gpt-image-2-beta's input object accepts exactly two fields — the schema has additionalProperties: false, so anything else is rejected outright, not silently ignored.

Field	Type	Required	Notes
prompt	string	yes	Text description of the image to generate.
size	string	no	Literal pixel dimensions, e.g. "1024x1024", "1600x900". Not an aspect-ratio keyword. Omit for the model's default output size.

What's NOT supported (and the error you'll get)

The beta schema doesn't accept any of the fields the default gpt-image-2/text-to-image route or the OpenAI Images API use — aspect_ratio, resolution, quality, background, moderation, output_format, output_compression, n, user, or style. Sending any of them returns an HTTP 400 immediately, for example:

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

If you're porting code from the default route or from OpenAI's Images API, strip it down to prompt + size before pointing it at gpt-image-2-beta.

Pricing: beta vs default vs @ext

Route	Price	Control
gpt-image-2-beta	$0.02/image flat	size (pixel dimensions) only
gpt-image-2/text-to-image (default)	$0.03 (1K) / $0.04 (2K) / $0.06 (4K)	aspect_ratio + resolution
gpt-image-2/text-to-image@ext	$0.007–$0.76, by quality × resolution	16 aspect ratios, quality tiers

Check the pricing page before committing to a route in production — pricing on any given model can change.

Tips for building on a beta route

• Treat the field list above as the current contract, not a permanent one. Beta routes are more likely to have their schema or pricing adjusted than the default route — re-check the model page periodically if you depend on this in production.
• Since size is optional, always pass it explicitly if your layout depends on a specific dimension — don't rely on the current default staying the same.
• Handle status: "fail" the same way you would for any other hiapi image model: read task.error.code / task.error.message and retry with backoff rather than assuming every failure is transient.

FAQ

Is gpt-image-2-beta the same model as gpt-image-2/text-to-image? Same underlying GPT Image 2 model, different API route — the beta route trades parameter control for a flat, lower price.

Can I request a specific aspect ratio? Not directly. Pick a size string with the width:height ratio you want (e.g. "1600x900" for 16:9) instead of an aspect_ratio enum.

What happens if I don't pass size at all? The task still succeeds — the model uses its own default output dimensions.

Related reading

For the full-featured route with explicit aspect-ratio and resolution control, see how to use gpt-image-2/text-to-image via the hiapi API. Ready to try it yourself? Grab a key from the API Keys page and run the curl example above.