Skip to content
HiAPI Docs
HiAPI
Playground Get API Key
English
English 中文

GPT Image 2 Image-to-Image

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

GPT Image 2 Image-to-Image generates new images from references, useful for reference rewriting, product cleanup, and multi-ratio delivery.

Production guidance

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 pro route delivers higher quality (resolution limited to 1K/2K, other fields unchanged); ext unlocks multi-ratio 4K. Each route is priced differently.

route

Request parameters

Route

Default route: full 1K/2K/4K resolutions and 16 aspect ratios (including auto, default auto).

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. At least one image is required. 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

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"
  }
}
Pro route refinement

Pass route: "pro" at the top level for the quality route. Note the pro route supports 1K/2K only.

Request body
{
  "model": "gpt-image-2/image-to-image",
  "route": "pro",
  "input": {
    "prompt": "Enhance the reference into a premium hero shot with soft studio lighting",
    "input_urls": [
      "https://example.com/reference.png"
    ],
    "aspect_ratio": "3:2",
    "resolution": "2K"
  }
}
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

  1. The response returns a taskId immediately without waiting for generation to finish.
  2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
  3. When status=success, download the generated image from output[].url.
  4. 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?

Three routes. Standard: resolution supports 1K/2K/4K. Pro: resolution is limited to 1K/2K, other fields unchanged. Ext: a multi-ratio 4K route with different parameter names — image_urls replaces input_urls, and quality/resolution are required; see the ext tab under request parameters. Each route is priced differently — check the live HiAPI pricing page.

How do I call the pro route?

Pass the base model name with a top-level route parameter, e.g. route: 'pro', or model gpt-image-2/image-to-image@pro — the two are equivalent.

Next steps