GPT Image 2 Image-to-Image

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

Image, video, and audio 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/image-to-image
Type	Image generation (image-to-image)
Routes	default / ext
Endpoint	POST /v1/tasks
Model & Playground	GPT Image 2 Image-to-Image model page
Pricing guide	GPT Image 2 API pricing and cost per image

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

Reference rewriting

Use one or more reference images and change style, scene, or commercial polish through the prompt.

input_urlsprompt

Product image cleanup

Turn rough assets into cleaner product photos, poster heroes, or commerce visuals.

promptresolution

Multi-ratio delivery

Keep the reference subject while producing the ratios required by each placement.

aspect_ratio

Detailed constraints

Constrain material, background, lighting, composition, and text requirements in one prompt.

prompt

Multiple routes

The ext route unlocks multi-ratio 4K with separate reference-image and quality fields.

route

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": "Turn the reference image into a clean product photo",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}'

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": "Turn the reference image into a clean product photo",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}
''')

# 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": "Turn the reference image into a clean product photo",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

Route

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. Pass 1–6 images. SVG is not supported.

aspect_ratio enum optional

Generated image aspect ratio. Default auto. Note: 5:4, 4:5, 3:1, 1:3, and 9:21 support 1K images only.

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

resolution enum optional

Image resolution. Note: 1:1 cannot be generated at 4K; auto or an unspecified aspect ratio can only be generated at 1K, otherwise the task cannot be created.

default 1K enum: 1K2K4K

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 ext multi-ratio 4K route: references go in image_urls (1-6 images), resolution and quality are required, priced by quality tier, and all 16 aspect ratios are available at every tier. Pass route: "ext" at the top level.

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 array, 1-6 images; public URLs and data URIs can be mixed. Up to 20 MB per image, 256 MB total. Note the ext route field name is image_urls (the standard route 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

Resolution tier: 1K ≈ 1024px, 2K ≈ 2048px, 4K up to 3840×2160; actual pixels vary by 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

Example requests

Productize a reference

Restyle a reference image into a clean product visual.

Request body

{
  "model": "gpt-image-2/image-to-image",
  "input": {
    "prompt": "Turn the reference image into a clean commercial product photo on a white acrylic surface",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}

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",
  "input": {
    "prompt": "Restyle this product photo as a premium catalog image",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "4:5",
    "resolution": "1K"
  },
  "callback": {
    "url": "https://your-domain.com/hiapi/callback",
    "when": "final"
  }
}

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

Which routes does gpt-image-2/image-to-image offer, and how do the parameters differ?

Two routes. Both Standard and ext routes support up to 6 reference images. Standard uses input_urls and supports 1K/2K/4K resolution. Ext is a multi-ratio 4K route that uses image_urls and requires quality and resolution. See the route tabs under request parameters for the complete fields. Route prices may differ; use the pricing guide linked in Model summary for current per-image costs.