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.

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

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.