GPT Image 2 Text-to-Image (Multi-ratio 4K) API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	gpt-image-2/text-to-image@ext
Type	Image generation (text-to-image)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

The high-resolution multi-ratio line of GPT Image 2: freely combine 16 aspect ratios (including 5:4, 4:5, 2:1 and 21:9) with 1K/2K/4K resolutions and three quality tiers, up to 3840x2160 output — built for posters, banners and print assets that demand exact framing and finish.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

5:4 / 4:5 at high resolution

The standard GPT Image 2 line does not support 5:4 or 4:5 at 2K/4K. This line offers all 16 ratios at every resolution tier — built for print, framed art and album layouts with fixed framing.

aspect_ratioresolution

Banners and ultra-wide formats

Ultra-wide ratios like 2:1, 3:1 and 21:9 suit website banners, storefront signage and panoramic posters; 9:21 and 1:3 verticals work for mobile splash screens and roll-up banners.

aspect_ratio

Tiered output by budget

Iterate drafts on the low tier, then re-run the chosen composition at medium/high for final delivery. Quality and resolution are priced independently, so volume work and fine output never conflict.

qualityresolution

4K commercial delivery

The 4K tier reaches 3840x2160 (16:9) or 3216x2576 (5:4). Combined with the high quality tier, output is ready for commercial asset delivery.

resolutionquality

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "a jade teapot pouring glowing amber tea, macro detail, dramatic lighting",
    "aspect_ratio": "5:4",
    "resolution": "1K",
    "quality": "low"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "a jade teapot pouring glowing amber tea, macro detail, dramatic lighting",
    "aspect_ratio": "5:4",
    "resolution": "1K",
    "quality": "low"
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "a jade teapot pouring glowing amber tea, macro detail, dramatic lighting",
    "aspect_ratio": "5:4",
    "resolution": "1K",
    "quality": "low"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value gpt-image-2/text-to-image@ext.

example gpt-image-2/text-to-image@ext

input object required

Business parameters. Put GPT Image 2 Text-to-Image (Multi-ratio 4K)-specific configuration here.

prompt string required

Image generation prompt, up to 20000 characters.

aspect_ratio enum optional

Output aspect ratio. All 16 ratios (including 5:4, 4:5 and 2:1) are available at every resolution tier.

default 1:1 enum: auto1:13:22:34:33:45:44:516:99:16 +6

resolution enum required

Resolution tier: 1K is ~1024px, 2K is ~2048px, 4K goes up to 3840x2160. Exact pixels depend on the aspect ratio.

default 1K enum: 1K2K4K

quality enum required

Quality tier, affects pricing: low is clean and sharp for volume work, medium adds visible detail, high delivers a cinematic finish.

default low enum: lowmediumhigh

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

5:4 high-resolution product still

The core use case: a product-grade still life at 5:4 and 2K, with the medium tier balancing finish and cost.

Request body

{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "an ornate crystal perfume bottle with art-deco brass filigree on dark velvet, amber liquid glowing from within, luxury still life photography",
    "aspect_ratio": "5:4",
    "resolution": "2K",
    "quality": "medium"
  }
}

2:1 panoramic banner

Ultra-wide framing for website banners and panoramic posters; the low tier is enough for everyday web use.

Request body

{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "a sweeping panoramic view of terraced rice fields at sunrise with morning mist rolling between emerald layers, cinematic composition, high dynamic range",
    "aspect_ratio": "2:1",
    "resolution": "2K",
    "quality": "low"
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated image from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

How is this different from the standard gpt-image-2/text-to-image?

Ratio coverage. The standard line does not support 5:4, 4:5, 3:1, 1:3 or 9:21 at 2K/4K; this line offers all 16 ratios at every resolution tier, plus a three-level quality selector. Choose this line when you need those ratios at high resolution.

How is pricing calculated?

Billed by quality x resolution (9 tiers). Aspect ratio does not affect price. The low tier suits volume work; the high tier costs more but delivers a visibly finer finish. See the live pricing page for current rates. View live pricing

How big is the visual gap between quality tiers?

Low is clean and sharp with a slightly digital look — fine for everyday and batch work. Medium adds visible gains in skin texture, material detail and depth of field, suitable for client delivery. High delivers cinematic lighting, but the gain over medium is smaller than the price gap, so reserve it for showcase-grade output.

Why are quality and resolution required?

Both parameters directly determine the billing tier. Making them required prevents accidental charges from implicit defaults — a request missing either returns a 400 error without creating a task or charging anything.