图片编辑 API 参考

FLUX 图片编辑 API 参考与在线调试 — 上传参考图（最多 8 张）+ 指令进行单图改图、多图融合，FLUX.2 全系列 + FLUX.1 Kontext 通用

POST /v1/images/generations

图片编辑：根据指令编辑或融合参考图

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": "自然融合这两个图片",
  "input_image": "https://static.apiyi.com/apiyi-logo.png"
}
'

200

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

右侧的交互式 Playground：在 Authorization 中填入 API Key（格式：Bearer sk-xxx），把参考图的公网 URL 填到 input_image，多图融合继续填 input_image_2 … input_image_8，然后填 prompt、model 一键发送即可。Playground 只支持 URL 输入；如需用 base64 data URL，请复制下方代码示例到本地调试。

场景说明：本页用于「基于一张或多张参考图改图 / 多图融合」。FLUX 系列文生图与图片编辑共用同一端点 /v1/images/generations（与 OpenAI gpt-image 不同，FLUX 没有独立的 /edits 路径）：传入 input_image 即触发编辑模式，不传则走纯文本生成。请求是 application/json 格式，所有参考图字段都是 URL 字符串（也可在本地代码中传 base64 data URL）。如需纯文本生成图片，请使用 文生图接口。

⚠️ 关键差异 / 注意事项

• 端点路径：/v1/images/generations（与文生图共用，不是 /v1/images/edits）
• Content-Type：application/json（apiyi 的 FLUX 通道要求 JSON，不是 multipart）
• 所有参考图字段是字符串：input_image / input_image_2 … input_image_8，值为公网 URL（推荐）或 data:image/...;base64,xxx data URL
• 多图上限因模型而异：FLUX.2 [pro/max/flex] 最多 8 张，FLUX.2 [klein] 最多 4 张，FLUX.1 Kontext 系列原生只支持 1 张
• 单张参考图 ≤ 20MB 或 20MP，格式 png / jpg / webp
• 输入分辨率：最小 64×64，最大 4MP；dimensions 必须是 16 的倍数
• 结果 URL 仅 10 分钟有效 — data[0].url 必须立即下载
• 不传 aspect_ratio 时，输出尺寸自动匹配第一张输入图

📎 多图融合顺序有意义

input_image / input_image_2 / input_image_3 … 的编号 就是 prompt 中「image 1 / image 2 / image 3」的引用依据。建议在 prompt 中显式指代，例如：

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

每张图必须为可公网访问的 URL（推荐 ≤ 20MB），或 data:image/png;base64,xxx 格式 base64 data URL。

​

代码示例

​

cURL（双图融合 · 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": "自然融合这两个图片",
    "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（三图融合 · 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（单图编辑 · 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（本地文件 · base64 data URL）

# 先把本地图片转为 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: "把图1风格化为油画",
    input_image: $img
  }')"

​

Python（requests · 双图融合）

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": "自然融合这两个图片",
        "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 仅 10 分钟有效，立即下载
with open("fused.jpg", "wb") as f:
    f.write(requests.get(image_url, timeout=30).content)

​

Python（requests · 本地文件 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": "把图1人物放进图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 · extra_body 注入 input_image）

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() 走 /v1/images/generations + JSON，
# BFL 原生字段通过 extra_body 直接拼到 JSON 请求体里
resp = client.images.generate(
    model="flux-2-pro",
    prompt="自然融合这两个图片",
    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 · 多图融合）

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: '自然融合这两个图片',
        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()));

​

参数说明速查

字段	类型	必填	默认	说明
model	string	是	—	FLUX 模型 ID，多图融合推荐 flux-2-pro / flux-2-max，单图改图也可用 flux-kontext-max / flux-kontext-pro
prompt	string	是	—	编辑 / 融合指令，最长 32K tokens；多图场景用「image 1 / image 2 / image 3」指代 image / input_image_2 / input_image_3 顺序
input_image	string	是	—	参考图 1。公网 URL（推荐）或 data:image/...;base64,xxx data URL
input_image_2 ~ input_image_8	string	否	—	第 2–8 张参考图，URL 或 data URL。FLUX.2 [pro/max/flex] 最多 8 张，[klein] 4 张，Kontext 不支持
aspect_ratio	string	否	跟随首图	例如 1:1 / 16:9 / 9:16 / 4:3 / 3:2
seed	integer	否	随机	固定可复现
safety_tolerance	integer	否	2	0（最严）– 6（最宽松）
output_format	string	否	jpeg	jpeg / png
prompt_upsampling	boolean	否	false	是否自动扩写 prompt
steps	integer	否	50	仅 flux-2-flex，最大 50
guidance	number	否	4.5	仅 flux-2-flex，1.5–10

​

多图融合策略

角色一致性（最多 8 张）

上传同一角色的多张照片作参考，模型会自动维持身份特征。适合广告系列、漫画分镜、时尚编辑。

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

风格迁移

一张内容图 + 一张风格图，prompt 显式指代：

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

对象组合

把多张图里的不同物体组合到一个新场景：

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

服装/产品换样

把图1人物的上衣换成图2 的款式：

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

多轮迭代：把上一次的 data[0].url 重新下载后作为下一次 image[] 输入，配合新指令逐步精调画面。每轮按张数计费。

​

响应格式

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

⚠️ data[0].url 仅 10 分钟有效

• URL 托管在 delivery-eu.bfl.ai / delivery-us.bfl.ai，签名 10 分钟过期
• 不开启 CORS，浏览器 fetch 会被拦
• 生产服务必须服务端代下载到自有 OSS / CDN
• FLUX 编辑端点不返回 b64_json，仅返回 url

编辑请求与文生图同价，按张数计费而非按 token。多图融合不会因图片数量加价（与 OpenAI gpt-image-2 编辑不同）。

授权

Authorization · string · header · 必填

在 API易控制台获取的 API Key

请求体

application/json

model · enum<string> · 默认值: flux-2-pro · 必填

FLUX 模型 ID。多图融合推荐 flux-2-pro / flux-2-max；单图改图也可用 flux-kontext-max / flux-kontext-pro

可用选项: 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 · 必填

编辑/融合指令。多图场景用「image 1 / image 2 / image 3」指代 input_image / input_image_2 / input_image_3 顺序

示例:

"自然融合这两个图片"

input_image · string · 必填

参考图 1 的公网 URL（必填）。Playground 直接填 URL；本地代码调试也可传 data:image/png;base64,xxx 形式的 base64 data URL

示例:

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

input_image_2 · string

参考图 2 的公网 URL（可选）

input_image_3 · string

参考图 3 的公网 URL（可选）

input_image_4 · string

参考图 4 的公网 URL（可选）

input_image_5 · string

参考图 5 的公网 URL（可选）

input_image_6 · string

参考图 6 的公网 URL（可选）

input_image_7 · string

参考图 7 的公网 URL（可选）

input_image_8 · string

参考图 8 的公网 URL（可选，仅 FLUX.2 [pro/max/flex] 支持到 8 张）

aspect_ratio · string

宽高比，例如 1:1 / 16:9 / 9:16 / 4:3 / 3:4。不传则跟随首张输入图

seed · integer

固定可复现

safety_tolerance · integer

审核档位。0 最严格，6 最宽松，默认 2

必填范围: 0 <= x <= 6

output_format · enum<string>

输出格式，默认 jpeg

可用选项: jpeg, png

prompt_upsampling · boolean

是否自动扩写 prompt，默认 false

steps · integer

仅 flux-2-flex。推理步数，默认 50

必填范围: 1 <= x <= 50

guidance · number

仅 flux-2-flex。引导强度，默认 4.5

必填范围: 1.5 <= x <= 10

响应

200

application/json

成功生成图片

created · integer

示例:

1776832476

data · object[]

生成结果数组（本接口单次返回 1 张）

Show child attributes