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

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
Canonical routed ID gpt-image-2/image-to-image@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

Send model=gpt-image-2/image-to-image to POST /v1/tasks to edit images from 1–6 references. This reference covers input fields, route differences, callbacks, polling, and code examples.

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.
Submission, pricing, and output retention
  • If a submission may be retried after a network timeout, reuse one Idempotency-Key for the same logical job to prevent duplicate tasks and duplicate charges.
  • Standard-route price varies by resolution. Ext combines a quality × resolution base price with dynamic reference-image pricing for image_urls. Use live pricing and do not hard-code a per-image total.
  • For polling, wait 2–3 seconds before the first lookup, then poll every 3–5 seconds and stop on success or fail.
  • On success, download data.output[].url before expireAt. Handle synchronous 4xx responses separately from asynchronous status=fail, and do not blindly retry invalid schemas.

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

Route

Default route. Its canonical model ID is gpt-image-2/image-to-image. Pass 1–6 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. Pass at least 1 and at most 6 images.

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"
  }
}
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"
  }
}
Ext multi-reference edit

Ext uses image_urls and a top-level route selector. Reference count participates in dynamic pricing.

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"
  }
}

Getting the result

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

FAQ

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

Two routes. Both Standard and ext support 1–6 references. Standard uses input_urls. Ext uses image_urls and requires quality and resolution. Ext cost combines a quality × resolution base price with dynamic reference-image pricing; use the live pricing source.

Next steps