Black Forest Labs

FLUX.2

flux-2/image-to-image

Black Forest Labs' family of image generation and editing models, supporting reference-image-based style transfer and multi-reference image fusion, while preserving the original composition and subject placement as much as possible during editing

flux-2/image-to-image flux-2/text-to-image

Try flux-2/image-to-image

Input

Showcases

View all showcases

Output

image

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

Pricing

flux-2/image-to-image per image

Specifications	Unit Price
1K	$0.035
2K	$0.050

Positioning Overview

The FLUX.2 image editing pipeline accepts 1 to 8 reference images plus an editing instruction, performing style replacement and detail adjustments while preserving the original composition and subject placement as much as possible. It suits developers who need to transform existing assets into new visuals, such as style transfer, multi-image fusion, and creative prototype iteration. Called through the unified HiAPI.ai interface, output image resolution can be set to 1K or 2K, and aspect ratio supports common ratios as well as an auto mode that follows the first image.

Key Highlights

Prioritizes preserving the original composition and subject placement during editing — changes style and details per the instruction rather than regenerating an unfamiliar image, reducing downstream alignment effort.
Accepts 1 to 8 reference images in a single call — images can be referenced in order within the prompt, enabling asset replacement and multi-image element fusion.
Controllable output ratio and resolution — specify 1K or 2K and various aspect ratios; auto mode directly inherits the composition of the first input image.

Capabilities

Instruction-driven image editing: Pass in reference images and an editing instruction to get a modified image, suited to targeted adjustments on existing assets rather than generating from scratch.

Multi-image referencing and element combination: Up to 8 input images, and the prompt can reference each image by index, making it easy to place elements from one image into another image's scene.

Composition and ratio inheritance: When aspect ratio is set to auto, it matches the first input image, preserving the original layout while changing content, which facilitates batch replacement of assets with the same dimensions.

Selectable output resolution: Supports two output resolutions, 1K and 2K, to choose per display requirements, balancing preview and final-use purposes.

Use Cases

Designers applying style transfer to existing photos — input an original photo and a style description to get a stylized version that preserves subject placement, for mood boards and preliminary drafts.
Element replacement in marketing assets — pass in a product image and a scene image, replace content per instruction, and produce uniformly sized ad images for multi-channel delivery.
Style consistency across multiple reference images — input multiple existing visual assets and generate derivative images in a consistent style, for serialized extension of campaign visuals.

Limitations and Selection Advice

Only image-to-image is supported; at least one reference image is required, and pure text-to-image is not possible. Prompts are limited to 3 to 5000 characters; input images must be jpeg/png/webp and no larger than 10MB each; SVG is not supported. Resolution is limited to two tiers, 1K and 2K. When an image needs to be conceived from scratch, the text-to-image pipeline in the same family should be used instead; for scenarios requiring non-commercial licensing or local deployment, licensing and deployment conditions must be verified separately.

What's new

View changelog →

New model New models: flux-2-klein-4b/text-to-image for cost-efficient… Jul 27, 2026
New model New image-editing models Jul 27, 2026

Frequently asked questions

View all FAQs →

How many references does FLUX.2 [pro] Image to Image accept?

It accepts 1 to 8 JPEG, PNG, or WebP references under 10MB each. Assign each image a clear role in multi-image prompts.
What does the auto ratio do?

auto follows the first reference image. Choose an explicit ratio for a fixed landscape, portrait, or square output.
How are 1K and 2K billed?

1K and 2K use separate per-image tiers, while reference count adds no separate fee. See the live page price for current amounts.
How do I reduce subject or logo drift?

Assign each reference a role and state the subject, text, material, position, and lighting that must remain unchanged.

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: flux-2/image-to-image

routestringOptional

Current fixed value: default

inputobjectRequired

Business parameters for flux-2/image-to-image and route default — see the parameter table below.

promptstringRequiredminLength 3maxLength 5000

Editing instruction describing the desired output effect, 3-5000 characters long. Input images must be referenced in order, for example "place the jar from image 1 into the capsule in image 2".

image_urlsarrayRequiredminItems 1maxItems 8

Array of input reference images, containing 1-8 images, each a publicly accessible URL, supporting jpeg/png/webp formats, maximum 10MB per image; SVG is not supported.

Array [ string ]

resolutionstringRequiredDefault: "1K"

Output image resolution, defaults to 1K.

Options:1K2K

aspect_ratiostringRequiredDefault: "1:1"

Aspect ratio of the generated image, defaults to 1:1; when set to auto, matches the aspect ratio of the first input image.

Options:1:14:33:416:99:163:22:3auto

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": "flux-2/image-to-image",
  "input": {
    "prompt": "…",
    "image_urls": "…",
    "resolution": "1K",
    "aspect_ratio": "1:1"
  }
}'

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: "flux-2/image-to-image",
    input: {
      "prompt": "…",
      "image_urls": "…",
      "resolution": "1K",
      "aspect_ratio": "1:1"
    }
  }),
});
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": "flux-2/image-to-image",
        "input": {
          "prompt": "…",
          "image_urls": "…",
          "resolution": "1K",
          "aspect_ratio": "1:1"
        }
    },
)
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"
    }
  }
}