GPT Image 2 Image-to-Image

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/image-to-image to POST /v1/tasks to edit images from 1–16 references. This reference covers input fields, route differences, callbacks, polling, and code examples.

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/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}
''')

# 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/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

Route

Default route. Its canonical model ID is gpt-image-2/image-to-image. Pass 1–16 references in input_urls; price varies by resolution.

model string required

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

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

route string optional

Omit for the default route, or pass default explicitly.

example default

input object required

Business parameters for references and generation settings.

prompt string required

Text prompt, up to 20000 characters.

input_urls string[] required

Reference image URL array, 1 to 16 images. PNG, JPEG/JPG, and WebP are supported; SVG, GIF, BMP, and TIFF are not. Each image must be at most 20 megapixels and 30 MB, served from a publicly reachable, directly downloadable http(s) URL. Data URIs are also accepted.

aspect_ratio enum optional

Generated image aspect ratio. 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: 3:11:39:21

default 1K enum: 1K2K4K

background enum optional

Background is supported only at 1K; omit this field for 2K/4K.

enum: autoopaquetransparent

callback object optional

Optional callback configuration. In production, pass callback.url so HiAPI can notify your service when the task reaches a terminal state.

url string required

HTTPS URL that receives terminal task notifications.

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/image-to-image@ext. Pass 1–6 references in image_urls; resolution and quality are required, and reference count participates in dynamic pricing. 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/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}
''')

# 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/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

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

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

route string required

Fixed value ext.

example ext

input object required

Business parameters.

prompt string required

Image edit instruction, up to 20000 characters.

image_urls string[] required

Reference image URL array, 1 to 6 images; count participates in ext dynamic pricing. PNG, JPEG/JPG, and WebP are supported; SVG, GIF, and other formats are not. Each image must be at most 20 MB, and 20 megapixels or less is recommended. URLs must be publicly reachable and directly downloadable http(s) links; data URIs are also accepted. The ext field is image_urls, while Standard uses input_urls.

aspect_ratio enum optional

Output aspect ratio; default auto follows the input image, an explicit value forces that ratio.

default auto 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. In production, pass callback.url so HiAPI can notify your service when the task reaches a terminal state.

url string required

HTTPS URL that receives terminal task notifications.

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

Productize a reference

Restyle a reference image into a clean product visual.

Request body

{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Keep the main subject and remove the background.",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K",
    "background": "transparent"
  }
}

Production request with callback

Create the task, then wait for callback.url to receive the terminal notification.

Request body

{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "Keep the product unchanged and replace the background with a premium studio set",
    "image_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K",
    "quality": "medium"
  }
}

Success response

Response body

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

Pass 1–16 reference images per request. More than 16 returns a synchronous 400 (maxItems).
PNG, JPEG/JPG, and WebP are supported. SVG is rejected with a synchronous 400; GIF, BMP, TIFF, and other formats fail the task. Animated WebP uses only its first frame and is not recommended.
Each reference image must be at most 20 megapixels (about 4472×4472) and 30 MB. Limits apply per image; there is no per-request total.
URLs must be publicly reachable, directly downloadable http or https links; login-protected and hotlink-protected URLs are not supported. Data URIs are accepted. A 404, an HTML page instead of an image, or a corrupted file does not fail synchronously; the task ends with status=fail.
The ext route uses image_urls with 1–6 images per request, the same format rules, at most 20 MB per image, and 20 megapixels or less recommended.

Getting the result

A successful submission returns data.taskId immediately without waiting for generation to finish.
In production, prefer the top-level callback.url for terminal delivery. For local debugging, poll GET /v1/tasks/:id.
On status=success, download data.output[].url and retain it before expireAt.
For synchronous 4xx responses, fix authentication, balance, or schema errors. For asynchronous status=fail, log data.error and do not blindly retry invalid input.