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

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

FLUX.2 pro-tier image editing: multi-reference composition (up to 8 images), background replacement, style and material edits with strong subject consistency; 1K/2K, billed per image.

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

Multi-reference composition

Up to 8 reference images per request — combine subjects, logos and materials, referencing each image by order in the prompt.

image_urlsprompt
Background replacement

Keep the subject, swap the scene: lighting and reflections adapt to the new environment automatically.

prompt
Style & material edits

Photo to watercolor or 3D, objects to gold or glass — composition stays consistent.

prompt
Predictable per-image pricing

Flat 1K/2K tiers per image, independent of how many reference images you send.

resolution

Request parameters

model string required

Fixed value flux-2/image-to-image.

example flux-2/image-to-image
input object required

Business parameters. Put FLUX.2 Image to Image-specific configuration here.

prompt string required

Editing instruction describing the desired output. 3-5000 characters. Reference input images by order, e.g. 'the jar in image 1 filled with capsules from image 2'.

image_urls string[] required

Input reference images (1-8). Public URLs; jpeg/png/webp (SVG not supported), max 10MB each.

aspect_ratio enum required

Aspect ratio of the generated image. 'auto' matches the first input image ratio.

default 1:1 enum: 1:14:33:416:99:163:22:3auto
resolution enum required

Output image resolution.

default 1K enum: 1K2K
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

Watercolor style transfer

Tested with one reference and auto aspect: photo to soft watercolor.

Request body
{
  "model": "flux-2/image-to-image",
  "input": {
    "prompt": "Turn this scene into a delicate watercolor illustration with soft pastel tones and visible paper texture, keep the original composition",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/07/7ec4868888f6156f.png"
    ],
    "aspect_ratio": "auto",
    "resolution": "1K"
  }
}
Two-image composite (2K)

Tested composite: subject from image 1 placed into the scene of image 2 with unified lighting.

Request body
{
  "model": "flux-2/image-to-image",
  "input": {
    "prompt": "Place the glowing translucent grand piano from image 1 onto the wooden desk scene from image 2, keep the moody neon studio lighting and cinematic color grade, seamless composite",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/07/564b6163a46a3dc4.png",
      "https://static.hiapi.ai/gallery/2026/07/2494abb7645b98f8.png"
    ],
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }
}
Material edit (24k gold)

Tested material edit: record player turned to engraved gold, scene and lighting preserved.

Request body
{
  "model": "flux-2/image-to-image",
  "input": {
    "prompt": "Transform the record player into polished 24k gold with engraved art-deco patterns, keep the studio scene and lighting, photorealistic product shot",
    "image_urls": [
      "https://static.hiapi.ai/gallery/2026/07/2494abb7645b98f8.png"
    ],
    "aspect_ratio": "auto",
    "resolution": "1K"
  }
}

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

How does it relate to flux-2/text-to-image?

Same FLUX.2 pro-tier family: generate from text with flux-2/text-to-image; edit or compose from references with this endpoint.

How many reference images, and how do I reference them?

1-8 images (jpeg/png/webp, up to 10MB each). Reference them by order in the prompt, e.g. "the subject from image 1 in the scene of image 2".

Does the number of references affect the price?

No. Billing is per output image, tiered by 1K/2K resolution, independent of reference count.

What does aspect_ratio 'auto' do?

The output matches the aspect ratio of the first reference image — ideal for edits that change content but keep framing.

Next steps