GPT Image 2 API

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

Submit a text-to-image or image-to-image task, then query it with GET /v1/tasks/:id.

Send model=gpt-image-2/text-to-image to POST /v1/tasks to call GPT Image 2. This reference covers every request field, route difference, callback, polling step, and code example.

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",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}
''')

# 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",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

Route

Default route. Its canonical model ID is gpt-image-2/text-to-image. It supports 1K/2K/4K and 16 aspect ratios (including auto); price varies by resolution.

model string required

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

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

route string optional

Omit for the default route, or pass default explicitly.

example default

input object required

Business parameters. GPT Image 2 model-specific configuration lives here.

prompt string required

Text prompt, up to 20000 characters.

aspect_ratio enum optional

Aspect ratio of the generated image. Default auto.

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

resolution enum optional

Image output resolution.

Auto aspect ratio: Only 1K when aspect ratio is auto or unspecified
2K unavailable: 5:44:53:11:39:21
4K unavailable: 1:13:11:39:21

default 1K enum: 1K2K4K

background enum optional

The background parameter is supported only at 1K; omit this field for 2K/4K.

enum: autoopaquetransparent

callback object optional

Optional callback configuration. HiAPI sends a terminal notification to your service when the task finishes.

url string required

Required when callback is provided. HTTPS URL that receives the terminal task notification.

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

when enum optional

Callback trigger timing. Use final for terminal-state notifications.

default final enum: final

The beta route resolves to the canonical model ID gpt-image-2/text-to-image@beta. A size field replaces aspect_ratio and resolution. Prefer the base model plus route: "beta" at the top level.

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": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}'

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": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}
''')

# 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": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value gpt-image-2/text-to-image, combined with route to select the beta route.

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

route string required

Fixed value beta.

example beta

input object required

Business parameters.

prompt string required

Text prompt, up to 20000 characters.

size string optional

Output size, replacing aspect_ratio and resolution. Use auto or lowercase-x widthxheight with 3–5 digits per dimension, such as 1024x1024.

default auto example 1024x1024

callback object optional

Optional callback configuration. HiAPI sends a terminal notification to your service when the task finishes.

url string required

Required when callback is provided. HTTPS URL that receives the terminal task notification.

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

when enum optional

Callback trigger timing. Use final for terminal-state notifications.

default final enum: final

The HiAPI ext multi-ratio 4K route resolves to the canonical model ID gpt-image-2/text-to-image@ext. All 16 aspect ratios are available at 1K/2K/4K, and resolution and quality are required. Prefer route: "ext" at the top level.

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 clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "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 clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "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 clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "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, combined with route to select the ext route.

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

route string required

Fixed value ext.

example ext

input object required

Business parameters.

prompt string required

Text prompt, up to 20000 characters.

aspect_ratio enum optional

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

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

resolution enum required

HiAPI ext route resolution tier: 1K, 2K, or 4K. Actual pixel dimensions vary by aspect ratio.

default 1K enum: 1K2K4K

quality enum required

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

default low enum: lowmediumhigh

callback object optional

Optional callback configuration. HiAPI sends a terminal notification to your service when the task finishes.

url string required

Required when callback is provided. HTTPS URL that receives the terminal task notification.

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

when enum optional

Callback trigger timing. Use final for terminal-state notifications.

default final enum: final

Request example

Basic text-to-image

Minimum usable request with prompt, aspect ratio, and resolution.

Request body

{
  "model": "gpt-image-2/text-to-image",
  "input": {
    "prompt": "A red apple isolated on a transparent background.",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

Product image with transparent background

When you need transparency, pass background=transparent with 1K resolution.

Request body

{
  "model": "gpt-image-2/text-to-image",
  "route": "beta",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "size": "1024x1024"
  }
}

Square product creative

For product pages, social avatars, and square cover placements.

Request body

{
  "model": "gpt-image-2/text-to-image",
  "route": "ext",
  "input": {
    "prompt": "A clean product photo of a red apple on a white table",
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "quality": "low"
  }
}

Success response

Response body

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

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 image from data.output[].url and retain it before expireAt.
For a synchronous 4xx response from POST, fix authentication, balance, or request-schema errors. For status=fail while retrieving the task, log data.error and do not blindly retry the same invalid request.

Next steps

try GPT Image 2 in the playground