Image Editing API Reference

FLUX image editing API reference and live debugger — upload up to 8 reference images + instructions for single-image edits, multi-reference fusion. Works for FLUX.2 and FLUX.1 Kontext.

POST /v1/images/generations

Edit or fuse one or more reference images by instruction

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "flux-2-pro",
  "prompt": "Naturally blend these two images",
  "input_image": "https://static.apiyi.com/apiyi-logo.png"
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "flux-2-pro",
    "prompt": "Naturally blend these two images",
    "input_image": "https://static.apiyi.com/apiyi-logo.png"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'flux-2-pro',
    prompt: 'Naturally blend these two images',
    input_image: 'https://static.apiyi.com/apiyi-logo.png'
  })
};

fetch('https://api.apiyi.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'flux-2-pro',
    'prompt' => 'Naturally blend these two images',
    'input_image' => 'https://static.apiyi.com/apiyi-logo.png'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"flux-2-pro\",\n  \"prompt\": \"Naturally blend these two images\",\n  \"input_image\": \"https://static.apiyi.com/apiyi-logo.png\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"flux-2-pro\",\n  \"prompt\": \"Naturally blend these two images\",\n  \"input_image\": \"https://static.apiyi.com/apiyi-logo.png\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"flux-2-pro\",\n  \"prompt\": \"Naturally blend these two images\",\n  \"input_image\": \"https://static.apiyi.com/apiyi-logo.png\"\n}"

response = http.request(request)
puts response.read_body

200

{
  "created": 1776832476,
  "data": [
    {
      "url": "https://delivery-eu.bfl.ai/results/xxx/sample.jpeg?signature=..."
    }
  ]
}

Playground usage: enter your API Key in Authorization (format Bearer sk-xxx). Paste the public URL of reference image 1 into input_image; for multi-reference, fill the URLs of additional images into input_image_2 … input_image_8. Then fill prompt / model and send. The Playground only accepts URLs; for base64 data URL inputs, copy the code samples below and run them locally.

Use this page for “edit or fuse one or more reference images”. FLUX image editing supports two options:

• Option A (this page’s Playground, recommended): JSON + input_image to /v1/images/generations (shared with text-to-image — sending input_image triggers edit mode). Works for all FLUX models (including Kontext, verified), and supports multi-reference fusion (input_image_2 ~ input_image_8).
• Option B: the OpenAI-compatible multipart endpoint /v1/images/edits (see the “Option B” section below) — single-image editing, directly compatible with the OpenAI SDK’s client.images.edit().

For pure text-to-image, see the Text-to-Image endpoint.

⚠️ Key differences / notes (Option A)

• Endpoint path: /v1/images/generations (shared with text-to-image; an OpenAI-compatible single-image /v1/images/edits endpoint also exists — see Option B)
• Content-Type: application/json (Option B’s /edits endpoint uses multipart/form-data instead)
• Every reference image field is a string: input_image / input_image_2 … input_image_8 accept a public URL (recommended) or data:image/...;base64,xxx data URL
• Reference image cap varies by model: FLUX.2 [pro/max/flex] up to 8, FLUX.2 [klein] up to 4, FLUX.1 Kontext supports 1 natively
• Each image ≤ 20MB or 20MP, formats png / jpg / webp
• Input resolution: min 64×64, max 4MP; dimensions must be multiples of 16
• Result URL is valid for only 10 minutes — data[0].url must be downloaded immediately
• If aspect_ratio is omitted, output dimensions match the first input image

📎 Multi-reference order matters

The numbering of input_image / input_image_2 / input_image_3 … is exactly the index used by “image 1 / image 2 / image 3” in your prompt:

Place the person from image 1 into the scene from image 2, applying the color palette of image 3.

Each value must be a publicly reachable URL (≤ 20MB recommended) or a data:image/png;base64,xxx data URL.

Code Examples

cURL (two-image fusion · URL)

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "Naturally blend these two images",
    "input_image": "https://static.apiyi.com/apiyi-logo.png",
    "input_image_2": "https://images.unsplash.com/photo-1762138012600-2ab523f8b35a",
    "seed": 42,
    "output_format": "jpeg"
  }'

cURL (three-image fusion · URL)

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "The person from image 1 is petting the cat from image 2, the bird from image 3 is next to them",
    "input_image": "https://example.com/person.jpg",
    "input_image_2": "https://example.com/cat.jpg",
    "input_image_3": "https://example.com/bird.jpg",
    "seed": 42,
    "output_format": "jpeg"
  }'

cURL (single-image edit · Kontext)

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext-pro",
    "prompt": "Convert this architectural photo into a pencil sketch style, preserve all structural details",
    "input_image": "https://your-oss.example.com/architecture.jpg"
  }'

cURL (local file · base64 data URL)

# Encode local image as base64 data URL (macOS / Linux)
B64=$(base64 -w0 < person.png 2>/dev/null || base64 < person.png | tr -d '\n')

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d "$(jq -nc --arg img "data:image/png;base64,$B64" '{
    model: "flux-2-pro",
    prompt: "Stylize image 1 as an oil painting",
    input_image: $img
  }')"

Python (requests · two-image fusion)

import requests

resp = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "flux-2-pro",
        "prompt": "Naturally blend these two images",
        "input_image": "https://static.apiyi.com/apiyi-logo.png",
        "input_image_2": "https://images.unsplash.com/photo-1762138012600-2ab523f8b35a",
        "seed": 42,
        "output_format": "jpeg",
    },
    timeout=120,
)
image_url = resp.json()["data"][0]["url"]

# data[0].url is valid for only 10 minutes — download immediately
with open("fused.jpg", "wb") as f:
    f.write(requests.get(image_url, timeout=30).content)

Python (requests · local file as base64)

import base64, requests, mimetypes

def to_data_url(path: str) -> str:
    mime = mimetypes.guess_type(path)[0] or "image/png"
    with open(path, "rb") as f:
        b64 = base64.b64encode(f.read()).decode()
    return f"data:{mime};base64,{b64}"

resp = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={
        "Authorization": "Bearer sk-your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "flux-2-pro",
        "prompt": "Place the person from image 1 into the scene from image 2",
        "input_image": to_data_url("person.png"),
        "input_image_2": "https://your-oss.example.com/scene.jpg",
    },
    timeout=120,
)
print(resp.json()["data"][0]["url"])

Python (OpenAI SDK · pass input_image via extra_body)

from openai import OpenAI
import requests

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

# OpenAI SDK images.generate() targets /v1/images/generations with JSON;
# BFL-native fields are added straight into the body via extra_body.
resp = client.images.generate(
    model="flux-2-pro",
    prompt="Naturally blend these two images",
    extra_body={
        "input_image": "https://static.apiyi.com/apiyi-logo.png",
        "input_image_2": "https://images.unsplash.com/photo-1762138012600-2ab523f8b35a",
        "seed": 42,
        "output_format": "jpeg",
    },
)
image_url = resp.data[0].url
with open("fused.jpg", "wb") as f:
    f.write(requests.get(image_url, timeout=30).content)

Node.js (fetch · multi-reference fusion)

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer sk-your-api-key',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        model: 'flux-2-pro',
        prompt: 'Naturally blend these two images',
        input_image: 'https://static.apiyi.com/apiyi-logo.png',
        input_image_2: 'https://images.unsplash.com/photo-1762138012600-2ab523f8b35a',
        seed: 42,
        output_format: 'jpeg',
    }),
});

const { data } = await resp.json();
const img = await fetch(data[0].url);
const fs = await import('node:fs');
fs.writeFileSync('fused.jpg', Buffer.from(await img.arrayBuffer()));

Option B: OpenAI-Compatible Edit Endpoint (multipart)

Besides the JSON option above, FLUX image editing also supports the standard OpenAI Images API edit endpoint, directly compatible with client.images.edit() (verified 2026-07-04 with flux-kontext-max, successful generation):

• Endpoint: POST https://api.apiyi.com/v1/images/edits
• Content-Type: multipart/form-data (set automatically by SDKs and curl -F — do not set it manually, or the boundary gets lost and parsing fails)

The FLUX.1 Kontext series accepts a single input image only; for multi-reference fusion use Option A (input_image ~ input_image_8). Option B is currently verified on the Kontext series.

Request Parameters (form fields)

Field	Type	Required	Description
model	string	✓	E.g. flux-kontext-max / flux-kontext-pro
prompt	string	✓	Edit instruction
image	file	✓	Source image binary (png/jpg/webp, ≤ 20MB). The field name must be image — omitting it returns image is required
aspect_ratio	string	✗	E.g. 1:1 / 16:9, passed as a top-level form field; OpenAI SDK users pass it via extra_body
safety_tolerance	integer	✗	0 (strictest) – 6 (most permissive)

cURL Example

curl -X POST "https://api.apiyi.com/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=flux-kontext-max" \
  -F "prompt=Change the outfit to a fashion look" \
  -F "aspect_ratio=16:9" \
  -F "image=@input.jpg"

Python (OpenAI SDK) Example

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1",
)

result = client.images.edit(
    model="flux-kontext-max",
    image=open("input.jpg", "rb"),
    prompt="Change the outfit to a fashion look",
    extra_body={"aspect_ratio": "16:9"},  # FLUX-specific params go through extra_body
)
print(result.data[0].url)

Node.js (fetch + FormData) Example

const form = new FormData();
form.append('model', 'flux-kontext-max');
form.append('prompt', 'Change the outfit to a fashion look');
form.append('aspect_ratio', '16:9');
form.append('image', imageBlob, 'input.jpg'); // browser Blob or Node's fs.openAsBlob()

const resp = await fetch('https://api.apiyi.com/v1/images/edits', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer sk-your-api-key' },
    // Note: do NOT set Content-Type manually — let the runtime generate the multipart boundary
    body: form,
});
const data = await resp.json();
console.log(data.data[0].url);

The response format is identical to Option A (data[0].url, a BFL signed URL valid for 10 minutes — server-side download to your own storage in production).

Which Option Should I Use?

	Option A (JSON input_image)	Option B (multipart /edits)
Best for	Direct HTTP / frontend apps / multi-reference fusion	Existing OpenAI SDK code, client.images.edit() migration
Multi-image	Yes (flux-2 up to 8)	Single image only
Image input	Public URL or base64 data URL	Binary file

Parameter Reference

Field	Type	Required	Default	Description
model	string	Yes	—	FLUX model ID. For multi-reference fusion prefer flux-2-pro / flux-2-max; for single-image edits also flux-kontext-max / flux-kontext-pro
prompt	string	Yes	—	Edit / fusion instruction, up to 32K tokens. Use “image 1 / image 2 / image 3” to reference image / input_image_2 / input_image_3 ordering
input_image	string	Yes	—	Reference image 1. Public URL (recommended) or data:image/...;base64,xxx data URL
input_image_2 … input_image_8	string	No	—	Reference images 2–8 — URL or data URL. FLUX.2 [pro/max/flex] up to 8, [klein] 4, Kontext does not support extras
aspect_ratio	string	No	matches first input	E.g. 1:1 / 16:9 / 9:16 / 4:3 / 3:2
seed	integer	No	random	Fix for reproducibility
safety_tolerance	integer	No	2	0 (strictest) – 6 (most permissive)
output_format	string	No	jpeg	jpeg / png
prompt_upsampling	boolean	No	false	Auto-upsample the prompt
steps	integer	No	50	Only flux-2-flex, max 50
guidance	number	No	4.5	Only flux-2-flex, 1.5–10

Multi-Reference Strategies

Character Consistency (up to 8 images)

Upload multiple shots of the same character as references — the model preserves identity features automatically. Great for ad campaigns, comic panels, fashion editorials.

Eight consistent characters from the reference images,
in a fashion editorial set on a Tokyo rooftop at golden hour

Style Transfer

One content image + one style image, with explicit reference in the prompt:

Using the style of image 2, render the subject from image 1

Object Composition

Combine objects from multiple images into one new scene:

The person from image 1 is petting the cat from image 2,
the bird from image 3 is next to them

Outfit / Product Swap

Swap an outfit from one image to another subject:

Replace the top of the person in image 1 with the one from image 2,
keep the pose and background unchanged

Iterative editing: download data[0].url, feed it back as input_image in the next call with a new instruction, and refine progressively. Each round bills as one image.

Response Format

{
    "created": 1776832476,
    "data": [
        {
            "url": "https://delivery-eu.bfl.ai/results/xxx/sample.jpeg?signature=..."
        }
    ]
}

⚠️ data[0].url is valid for only 10 minutes

• URL hosted on delivery-eu.bfl.ai / delivery-us.bfl.ai, signature expires after 10 min
• CORS is disabled — browser fetch is blocked
• Production must server-side download to your own OSS / CDN
• The FLUX edit endpoint does not return b64_json — only url

Edit requests cost the same as text-to-image (per image, not per token). Multi-reference does not charge extra for additional images (unlike OpenAI gpt-image-2 editing).

FAQ

What causes the error image is required (shell_api_error)?

The request reached the /v1/images/edits endpoint (Option B), but the gateway couldn’t find an image in the request body. Common causes:

1. The multipart form has no image file field, or the field name is wrong (e.g. image[], file)
2. Content-Type: multipart/form-data was set manually without a boundary (don’t set this header yourself when using an SDK / fetch / curl)
3. The client’s image conversion failed but the request was sent anyway (check that the image field actually contains more than 0 bytes)
4. You meant to send an image via JSON but hit /edits — JSON + input_image goes to /v1/images/generations (Option A)

Authorizations

Authorization · string · header · required

API Key from the APIYI Console

Body

application/json

model · enum<string> · default: flux-2-pro · required

FLUX model ID. For multi-reference fusion prefer flux-2-pro / flux-2-max; for single-image edits also flux-kontext-max / flux-kontext-pro.

Available options: flux-2-pro, flux-2-max, flux-2-flex, flux-2-klein-9b, flux-2-klein-4b, flux-kontext-max, flux-kontext-pro

prompt · string · required

Edit / fusion instruction. In multi-reference scenarios, refer to images by index: 'image 1' / 'image 2' / 'image 3' map to input_image / input_image_2 / input_image_3.

Example:

"Naturally blend these two images"

input_image · string · required

Public URL for reference image 1 (required). Use plain URLs in the Playground; for local code you can also pass a data:image/png;base64,xxx data URL.

Example:

"https://static.apiyi.com/apiyi-logo.png"

input_image_2 · string

Public URL for reference image 2 (optional)

input_image_3 · string

Public URL for reference image 3 (optional)

input_image_4 · string

Public URL for reference image 4 (optional)

input_image_5 · string

Public URL for reference image 5 (optional)

input_image_6 · string

Public URL for reference image 6 (optional)

input_image_7 · string

Public URL for reference image 7 (optional)

input_image_8 · string

Public URL for reference image 8 (optional, only FLUX.2 [pro/max/flex] supports up to 8)

aspect_ratio · string

Aspect ratio, e.g. 1:1 / 16:9 / 9:16 / 4:3 / 3:4. Defaults to first input image.

seed · integer

Fix for reproducibility.

safety_tolerance · integer

Moderation level. 0 = strictest, 6 = most permissive. Default 2.

Required range: 0 <= x <= 6

output_format · enum<string>

Output format. Default jpeg.

Available options: jpeg, png

prompt_upsampling · boolean

Auto-upsample the prompt. Default false.

steps · integer

Only flux-2-flex. Inference steps. Default 50.

Required range: 1 <= x <= 50

guidance · number

Only flux-2-flex. Guidance scale. Default 4.5.

Required range: 1.5 <= x <= 10

Response

200

application/json

Image generated

created · integer

Example:

1776832476

data · object[]

Result array (single image per call)

Show child attributes