GPT Image 2 Image-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/image-to-image@ext
Type	Image generation (image-to-image)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

The image-to-image line of the GPT Image 2 high-resolution multi-ratio family: blend and edit with up to 16 reference images, across 16 aspect ratios x 1K/2K/4K x three quality tiers — precise control of output framing and finish for editing, style transfer and multi-image fusion.

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

Editing and style transfer

Upload an image plus one instruction to restyle, relight or swap elements. Leave aspect_ratio as auto and the output follows the input framing without distortion.

promptimage_urls

Multi-image fusion

Blend up to 16 reference images in one call: compose product shots into scenes, or merge multiple subjects into a poster. Price is independent of image count.

image_urls

Fixed-frame high-resolution remakes

Remake existing assets into exact ratios like 5:4, 4:5 or 2:1 at 2K/4K — ideal for turning social media images into print material.

aspect_ratioresolution

Tiered cost control

Run batch edits on the low tier and switch to medium/high for client delivery. The 9 quality x resolution tiers are priced independently of reference image count.

qualityresolution

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",
  "route": "ext",
  "input": {
    "prompt": "make it a night scene with lanterns",
    "image_urls": [
      "https://static.hiapi.ai/model-assets/gpt-image-2-ext/2026/07/02/1782989773168-fd7b2316f1a92a9f-i2i-input-apple.webp"
    ],
    "aspect_ratio": "auto",
    "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/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "make it a night scene with lanterns",
    "image_urls": [
      "https://static.hiapi.ai/model-assets/gpt-image-2-ext/2026/07/02/1782989773168-fd7b2316f1a92a9f-i2i-input-apple.webp"
    ],
    "aspect_ratio": "auto",
    "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/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "make it a night scene with lanterns",
    "image_urls": [
      "https://static.hiapi.ai/model-assets/gpt-image-2-ext/2026/07/02/1782989773168-fd7b2316f1a92a9f-i2i-input-apple.webp"
    ],
    "aspect_ratio": "auto",
    "resolution": "1K",
    "quality": "low"
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

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

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

input object required

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

prompt string required

Image edit instruction, up to 20000 characters.

image_urls string[] required

Reference images, 1-16 items; public URLs and data URIs can be mixed. Max 20 MB per image, 256 MB total.

aspect_ratio enum optional

Output aspect ratio. Defaults to auto (follows the input image); set explicitly to force a ratio.

default auto 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

Turn day into night

Single-image edit: keep the subject, restyle the scene into a lantern-lit night (the sample input/output in this doc comes from this exact request).

Request body

{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "make it a night scene with lanterns",
    "image_urls": [
      "https://static.hiapi.ai/model-assets/gpt-image-2-ext/2026/07/02/1782989773168-fd7b2316f1a92a9f-i2i-input-apple.webp"
    ],
    "aspect_ratio": "5:4",
    "resolution": "2K",
    "quality": "medium"
  }
}

Two-image poster fusion

Fuse two reference images into a 4:5 vertical poster for social placements.

Request body

{
  "model": "gpt-image-2/image-to-image",
  "route": "ext",
  "input": {
    "prompt": "fuse these two images into a cinematic poster, dramatic lighting",
    "image_urls": [
      "https://example.com/photo-a.jpg",
      "https://example.com/photo-b.jpg"
    ],
    "aspect_ratio": "4:5",
    "resolution": "2K",
    "quality": "medium"
  }
}

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/image-to-image?

This line supports all 16 ratios at 1K/2K/4K (the standard line lacks 5:4, 4:5 and others at 2K/4K), accepts up to 16 reference images (vs 5), and adds a three-level quality selector.

Does the number of reference images affect the price?

No. Billing is by quality x resolution (9 tiers); one image or sixteen costs the same. See the live pricing page for current rates. View live pricing

What is the difference between auto and an explicit aspect_ratio?

With auto (the default) the output follows the input image framing — best for in-place edits. An explicit ratio forces that output frame — best for remaking assets into a fixed layout.

What are the reference image limits?

Public URLs and base64 data URIs can be mixed, 1-16 images per request; max 20 MB per image and 256 MB in total.