OpenAI

GPT Image 2.5

gpt-image-2.5-flare/image-to-image

OpenAI's two-tier image generation and editing models: Flare focuses on speed, Sunburst pursues precision, covering both text-to-image and multi-turn image refinement

Route

default pro

gpt-image-2.5-flare/image-to-image gpt-image-2.5-flare/text-to-image gpt-image-2.5-sunburst/image-to-image gpt-image-2.5-sunburst/text-to-image

Try gpt-image-2.5-flare/image-to-image

Input

Showcases

View all showcases

Output

image

Fill in the parameters and run — results show up here.

Pricing

gpt-image-2.5-flare/image-to-image per image

Specifications	Unit Price
1K	$0.050
2K	$0.080
4K	$0.120

Positioning Overview

gpt-image-2.5-flare/image-to-image is an interface for image editing within the OpenAI image model family. It takes one to sixteen reference images and an editing instruction as input, and outputs a single generated image. Compared with Sunburst, Flare focuses more on balancing speed and image quality, making it suitable for applications that require fast image generation or batch processing. Developers can call it through the unified HiAPI.ai interface, choosing between 1K to 4K resolutions and a variety of aspect ratios. It also supports transparent background output, making it suitable for image transformation tasks such as e-commerce assets, brand visuals, and design refinement.

Core Highlights

Multi-reference image input, up to 16 images — A single request can carry up to 16 source or reference images, making it easy to blend multiple assets or lock in the subject and layout.
Transparent background limited to the 1K tier — Background mode offers three options: transparent, opaque, and auto, but is available only at 1K resolution; the parameter must be omitted for 2K and 4K.
Selectable resolution and aspect ratio — Output supports three tiers — 1K, 2K, and 4K — and thirteen aspect ratios, with auto ratio as the default; you can predefine the ratio based on the placement.
Flare emphasizes a balance between speed and quality — The same family also includes the precision-oriented Sunburst version; Flare is better suited to routine editing workflows with response-time requirements.

Capability Description

Multi-image reference editing: Accepts up to 16 JPEG, PNG, or WebP images, along with an instruction description of up to 20,000 characters specifying the transformation goal; suitable for redrawing an image while preserving the reference subject and layout.

Resolution and aspect ratio control: You can specify 1K, 2K, or 4K output tiers and choose from ratios such as 1:1, 16:9, 9:16, and 21:9, reducing post-processing cropping costs and aligning output directly with placement dimensions.

Background mode switching: At 1K resolution, the background can be set to transparent, opaque, or auto. Transparent output makes it easy to go directly into compositing and layout workflows, reducing cutout steps.

Fine-grained instruction-based revision: Thanks to the relatively long prompt allowance and adherence to complex visual instructions, you can perform local replacement, style adjustment, and detail retouching on an existing image, making it suitable for iterative editing workflows.

Use Cases

E-commerce operations: batch transformation of assets based on product images — Input actual product photos and image-editing instructions to produce product visuals in multiple sizes and aspect ratios for detail pages, main images, and ad placement assets.
Brand marketing: compositing visual drafts from multiple reference images — Blend multiple reference images to generate style-consistent visual drafts for early validation of proposals, presentations, and website imagery.
Design collaboration: repeated refinement on an existing layout — Use an existing design draft as input and revise the subject, lighting, and background round by round to produce a final image that can go directly into subsequent layout work.
Asset production: transparent background image output — Generate transparent background element images at the 1K tier for icons, stickers, and composite asset libraries, eliminating extra cutout steps.

Limitations and Selection Advice

This interface performs image editing only and requires at least one source image; it cannot generate from text alone. Background mode works only at the 1K tier and must be omitted for 2K and 4K. Layouts involving large amounts of small text or complex legends are still prone to errors and require human review. If you need higher detail fidelity and can accept longer wait times, you can choose the Sunburst route; if you need pure text-to-image, switch to the corresponding text-to-image route. High-resolution output increases computation and wait overhead.

Create a generation task

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

Headers

AuthorizationstringRequired

Account API key. Required on every request. Example: Bearer YOUR_HIAPI_API_KEY. Get your API key

Content-TypestringOptional

The request body is always parsed as JSON; when sent, only application/json (optionally with charset) is accepted — any other value returns 415. Example: application/json.

Idempotency-KeystringOptional

Idempotency key, up to 255 bytes. Retries with the same key from the same account create the task only once; replays return the original taskId.

Idempotency key

On network timeouts or client retries, the same key creates the task only once — no double charges (scope: the API key's account). Use a business-unique identifier as the key (e.g. "order-42"); replays return the original taskId, and keys expire 24 hours after the first request. See the Unified Async API overview for the full scenario matrix.

Body

modelstringRequired

Current fixed value: gpt-image-2.5-flare/image-to-image

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for gpt-image-2.5-flare/image-to-image and route default — see the parameter table below.

promptstringRequiredminLength 1maxLength 20000

Generation or editing instruction describing what to generate or edit based on the source image, up to 20,000 characters.

backgroundstringOptional

Background mode, supported only at 1K resolution; omit this parameter when using 2K/4K resolution.

Options:transparentopaqueauto

image_urlsarrayRequiredminItems 1maxItems 16

Array of source images or reference images, supporting 1 to 16 images in JPEG, PNG, or WebP format.

Array [ string ]

resolutionstringOptionalDefault: "1K"

Output resolution tier, defaults to 1K; when background is auto, opaque, or transparent, only 1K is supported.

Options:1K2K4K

aspect_ratiostringOptionalDefault: "auto"

Output aspect ratio; defaults to auto when omitted.

Options:auto1:13:22:34:33:416:99:16

Show all (5)

21:927:1616:279:88:9

callbackobjectOptional

Terminal-state notification config. When omitted, no callback is delivered — poll the task yourself. See the callback note below.

Callbacks (Webhook)

Provide callback.url when creating a task and HiAPI POSTs to your service once the task reaches a terminal state — no polling needed. The callback payload mirrors the task detail structure; signature verification, delivery retries and idempotency are documented on the Unified Async API overview page.

urlstringRequired

Required when callback is present. A POST is sent to this URL once the task reaches a terminal state; must be a valid http(s) URL.

whenstringOptionalDefault: "final"

Only final is supported today — notified on both success and fail.

Options:final

storagestringOptionalDefault: "temp"

Artifact storage tier: temp (default, retained about 7 days) or persistent (long-term, billed by size). Insufficient balance or exceeding the storage cap silently downgrades to temp; the effective tier is shown in the task detail response.

Options:temppersistent

Request examples

# Submit an async task; returns a taskId immediately (no waiting for generation)
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "gpt-image-2.5-flare/image-to-image",
  "input": {
    "prompt": "…",
    "image_urls": "…",
    "resolution": "1K",
    "aspect_ratio": "auto"
  }
}'

const res = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HIAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2.5-flare/image-to-image",
    input: {
      "prompt": "…",
      "image_urls": "…",
      "resolution": "1K",
      "aspect_ratio": "auto"
    }
  }),
});
const task = await res.json();
// { code: 200, message: "success", data: { taskId } }

import os, requests

res = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare/image-to-image",
        "input": {
          "prompt": "…",
          "image_urls": "…",
          "resolution": "1K",
          "aspect_ratio": "auto"
        }
    },
)
print(res.json())  # { code, message, data: { taskId } }

200 OK

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

400 Bad Request

{
  "code": 400,
  "message": "invalid request",
  "data": null,
  "error_code": "INVALID_REQUEST"
}

Get task detail

GET https://api.hiapi.ai/v1/tasks/:id

Response fields

taskIdstringRequired

Task ID, always prefixed with tk-hiapi-.

modelstringRequired

Resolved full model name. Tasks submitted with the route parameter return base@route (e.g. gpt-image-2/text-to-image@ext); otherwise identical to the name passed at creation.

routestringOptional

Present only when the task was submitted with an explicit route parameter; echoes the submitted value.

statusstringRequired

Task status.

Status values

queued Queued, not started yet. handling Being processed. archiving Processing finished, artifacts being prepared. success Terminal: completed, artifacts available (output returned). fail Terminal: failed (error returned). After submission, check status: success and fail are terminal, everything else is non-terminal. Poll every 1–3 seconds until terminal. On success, download artifacts from output[].url and transfer them before expireAt; pass storage: "persistent" at creation time when long-term retention is needed.

creatednumberRequired

Task creation time (Unix seconds).

completednumberRequired

Unix seconds when the task reached a terminal state; fixed to 0 while not terminal.

outputarrayOptional

Present only when status == success. Artifact list — always an array; a single task may return multiple types at once (e.g. video + first_frame).

Array [ object ]

Array items

urlstringRequired

Artifact URL, directly downloadable.

typestringRequired

Current possible values: video, image, audio, first_frame, last_frame, thumbnail; more may be added later.

expireAtnumberRequired

Unix seconds until which the artifact remains accessible; download or transfer before it expires.

errorobjectOptional

Present only when status == fail.

codestringRequired

Business error code.

messagestringRequired

Error description.

Response examples

Success

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-01HZTQ8BX2N3GM3YFK4Z9D7VQR",
    "model": "happyhorse-1-0",
    "status": "success",
    "created": 1777282033,
    "completed": 1777282099,
    "output": [
      {
        "url": "https://cdn.hiapi.ai/tasks/.../video.mp4",
        "type": "video",
        "expireAt": 1777886899
      }
    ]
  }
}

Processing (non-terminal)

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "archiving",
    "created": 1777282033,
    "completed": 0
  }
}

Failed

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "tk-hiapi-...",
    "model": "happyhorse-1-0",
    "status": "fail",
    "created": 1777282033,
    "completed": 1777282099,
    "error": {
      "code": "TASK_FAILED",
      "message": "task failed"
    }
  }
}