> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# FLUX.2 图片编辑 API：单图修改与多图合成

> 用 FLUX.2 编辑图片：在 /v1/images/generations 中传 1–8 张参考图，做单图修改或多图合成，附 cURL 与 Python 示例。

FLUX.2 的图片编辑和文生图使用同一个 JSON 接口：传入一张图片即可按提示词修改，最多传 8 张参考图可合成一张新图。按次计费，结果链接约 10 分钟后失效，需要立即下载。

| 项目 | 内容 |
| - | - |
| 接口 | `POST /v1/images/generations`，JSON 请求体 |
| 要修改的图片 | `input_image` |
| 追加参考图 | `input_image_2` 到 `input_image_8`，最多 8 张合成一张新图 |
| 参考图格式 | 公网 URL，或 `data:image/png;base64,...` 形式的 data URL |
| 返回结果 | 每次请求返回一张图片，链接约 10 分钟后失效 |
| 价格（按次） | `flux-2-pro` \$0.03/次、`flux-2-flex` \$0.06/次、`flux-2-max` \$0.07/次；2026 年 9 月 24 日公开价格配置，见[模型与价格](/models) |

## 选择模型

* `flux-2-pro`：默认选择，适合大多数编辑和批量任务；
* `flux-2-flex`：需要更细的控制，在质量与成本之间折中；
* `flux-2-max`：编辑一致性和画质要求最高的最终素材。

三款模型的请求字段相同，切换时只改 `model`。

本页示例只适用于 FLUX.2，新的编辑任务请使用 FLUX.2。旧版 `flux-kontext-pro`、`flux-kontext-max` 的用法见 [FLUX.2 图像生成中的旧版 Kontext 兼容](/api-capabilities/flux-image-generation#旧版-kontext-兼容)。

## 调用前准备

在[令牌管理](https://api.laozhang.ai/token)新建 `default` 分组的令牌，计费模式选择「按量优先」（推荐）或「按次计费」：按量优先的令牌可以同时调用按量和按次计费的模型，按次计费的令牌只能调用按次计费的模型。

设置密钥并安装依赖：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
python -m pip install requests pillow
```

cURL 示例把响应写入 JSON 文件，再用 [Images API 参考中的保存脚本](/api-reference/images#保存返回图片) `save_images.py` 保存图片（脚本依赖 `pillow`）。Python 示例在代码里直接保存。

## 编辑一张图片

编辑请求至少包含 `model`、`prompt` 和 `input_image`。输出尺寸二选一：

* `width` 和 `height`；
* `size`，如 `1024x1024`。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    IMAGE=source.png   # 替换为你的图片路径

    # 把本地图片转成 data URL
    IMG1="data:$(file --mime-type -b "$IMAGE");base64,$(base64 < "$IMAGE" | tr -d '\n')"

    curl --fail-with-body --max-time 240 "https://api.laozhang.ai/v1/images/generations" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "Content-Type: application/json" \
      --data-binary @- \
      -o flux-edit.json <<EOF
    {
      "model": "flux-2-pro",
      "prompt": "保留主体，把背景换成干净的浅蓝色摄影棚，保持原始光照和主体细节",
      "input_image": "$IMG1",
      "width": 1024,
      "height": 1024,
      "output_format": "png"
    }
    EOF

    python save_images.py flux-edit.json flux-edit
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    """FLUX.2 图片编辑：python flux_edit.py "编辑指令" 图片1 [图片2 ...]"""
    import base64
    import mimetypes
    import os
    import sys
    from pathlib import Path

    import requests

    API_URL = "https://api.laozhang.ai/v1/images/generations"
    HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}
    MODEL = "flux-2-pro"         # 也可以用 flux-2-flex 或 flux-2-max
    WIDTH, HEIGHT = 1024, 1024   # 输出尺寸，宽高须为 16 的倍数


    def to_reference(source):
        """公网 URL 和 data URL 原样使用，本地文件转成 data URL。"""
        if source.startswith(("http://", "https://", "data:")):
            return source
        path = Path(source)
        mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
        return f"data:{mime_type};base64,{base64.b64encode(path.read_bytes()).decode('ascii')}"


    def save_result(item, output):
        """下载结果图。FLUX 只返回 url，链接约 10 分钟后失效。"""
        if not item.get("url"):
            raise SystemExit(f"返回结果中没有图片：{item}")
        image = requests.get(item["url"], timeout=60)
        image.raise_for_status()
        Path(output).write_bytes(image.content)
        print("已保存", output)


    if not 1 <= len(sys.argv) - 2 <= 8:
        raise SystemExit('用法：python flux_edit.py "编辑指令" 图片1 [图片2 ...]，最多 8 张')

    payload = {
        "model": MODEL,
        "prompt": sys.argv[1],
        "width": WIDTH,
        "height": HEIGHT,
        "output_format": "png",
    }
    for index, source in enumerate(sys.argv[2:], start=1):
        payload["input_image" if index == 1 else f"input_image_{index}"] = to_reference(source)

    response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=240)
    if response.status_code != 200:
        raise SystemExit(f"HTTP {response.status_code}：{response.text[:1000]}")
    save_result(response.json()["data"][0], "flux-edit.png")
    ```
  </Tab>
</Tabs>

Python 示例保存为 `flux_edit.py` 后运行，图片参数可以是本地路径，也可以是公网 URL：

```bash theme={null}
python flux_edit.py "保留主体，把背景换成干净的浅蓝色摄影棚，保持原始光照和主体细节" source.png
```

成功后当前目录会出现 `flux-edit.png`（cURL 示例保存为 `flux-edit-1.png` 等文件）。参考图已在公网时，把 `input_image` 的值直接换成图片 URL 即可，不必转成 data URL。

## 合成多张图片

多张参考图按字段编号传入：第 1 张放 `input_image`，其余依次放 `input_image_2` 到 `input_image_8`。提示词里用 image 1、image 2、image 3 指明每张图的用途，编号与字段顺序一致：

```bash theme={null}
# 把本地图片转成 data URL
to_data_url() { printf 'data:%s;base64,%s' "$(file --mime-type -b "$1")" "$(base64 < "$1" | tr -d '\n')"; }

IMG1=$(to_data_url source_1_red_robot.png)
IMG2=$(to_data_url source_2_glass_greenhouse.png)
IMG3=$(to_data_url source_3_yellow_skateboard.png)

curl --fail-with-body --max-time 240 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-multi-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "Combine the three reference images into one coherent new image. Use image 1 as the red robot, image 2 as the turquoise glass greenhouse background, and image 3 as the yellow skateboard. Do not create a collage or split-screen layout.",
  "input_image": "$IMG1",
  "input_image_2": "$IMG2",
  "input_image_3": "$IMG3",
  "width": 1792,
  "height": 1024,
  "output_format": "png"
}
EOF

python save_images.py flux-multi-edit.json flux-multi-edit
```

用 Python 脚本时，按顺序传入多张图片：

```bash theme={null}
python flux_edit.py "结合三张参考图创作一张新图：image 1 的红色机器人、image 2 的温室背景、image 3 的黄色滑板，不要拼贴或分屏" source_1_red_robot.png source_2_glass_greenhouse.png source_3_yellow_skateboard.png
```

多图提示词的写法：

* 用 image 1、image 2、image 3 指代参考图，顺序与字段编号一致；
* 写清要保留的元素，例如颜色、物体、背景、贴纸或文字；
* 说明要生成一张完整的新图，而不是简单拼接；
* 写明不要什么，例如边框、多栏排版或文字标签。

```text theme={null}
Use image 1 as the character, image 2 as the background, and image 3 as the product.
Create one coherent commercial poster.
Preserve the character's clothing, the background lighting, and the product logo.
Do not create a collage or split-screen layout.
```

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | `flux-2-pro`、`flux-2-flex` 或 `flux-2-max` |
| `prompt` | string | 是 | 编辑指令；多图时写明每张图的用途 |
| `input_image` | string | 是 | 要编辑的图片或第 1 张参考图，公网 URL 或 data URL |
| `input_image_2` … `input_image_8` | string | 否 | 第 2–8 张参考图，按顺序使用 |
| `width`、`height` | integer | 否 | 必须是 16 的倍数，最小 64，总像素不超过约 400 万（如 2048×2048）；与 `size` 二选一 |
| `size` | string | 否 | 如 `1024x1024`、`1792x1024`、`1024x1792` |
| `output_format` | string | 否 | `jpeg`（默认）或 `png` |
| `seed` | integer | 否 | 固定随机种子；模型、提示词、参考图和尺寸都相同时便于复现 |

本页请求体都是 JSON，本地图片先转成 data URL 放进 `input_image` 字段。多张参考图只能用这种写法传；multipart 形式的 `/v1/images/edits` 只接收一张图片，文件字段名必须是 `image`。

## 保存结果

成功响应的 `data[0].url` 是结果图的下载地址，约 10 分钟后失效。FLUX 只返回图片 URL，不返回 `b64_json`，也不需要传 `response_format`。

收到响应后立即下载到本地或自己的存储；下载时不需要附带老张API密钥。链接失效后只能重新发起请求。

## 常见错误

| 现象 | 处理方法 |
| - | - |
| 401 | 检查 `Authorization: Bearer` 请求头和 API Key，不要使用账号 AccessToken |
| 400 | 检查 JSON 结构、`input_image` 系列字段名、data URL 格式、参考图数量（最多 8 张）和宽高取值（16 的倍数） |
| multipart 上传返回 `image is required`，或多张图没有生效 | `/v1/images/edits` 只接收一张图片，文件字段名必须是 `image`；多图合成改用 `/v1/images/generations` 的 `input_image` 系列字段 |
| 公网 URL 参考图读取失败 | 确认图片能被公网直接下载，或改用 data URL |
| 429、5xx 或超时 | 先在[调用日志](/faq/call-logs)确认请求状态，再决定是否重试 |
| 结果链接打不开 | 链接约 10 分钟后失效，重新发起请求并立即下载 |

## 常见问题

### 能只修改图片的一部分吗？

可以，但要靠提示词指定范围。请求没有蒙版（mask）字段，无法用遮罩精确圈定修改区域。在提示词里写明要改的对象和必须保持不变的部分，例如「只把杯子改成哑光黑色，构图、光线和背景保持不变」。

### 编辑比文生图贵吗？参考图多了会多收费吗？

都不会。FLUX.2 按次计费，编辑和文生图单价相同，一次请求计一次费用，与参考图数量（1–8 张）和输出尺寸无关。实际扣费以[调用日志](/faq/call-logs)为准。

### 编辑和文生图用的是同一个模型吗？

是。`flux-2-pro`、`flux-2-flex`、`flux-2-max` 同时支持文生图和编辑，请求里有没有 `input_image` 决定是生成还是编辑。文生图的写法见 [FLUX.2 API：图像生成](/api-capabilities/flux-image-generation)。

### 能用 SDK 的 `images.edit()` 编辑吗？

只适合单图编辑。OpenAI SDK 的 `images.edit()` 用 multipart 表单把文件上传到 `/v1/images/edits`，只能传一张图，不能多图合成。

建议统一用 `client.images.generate()`，把 `input_image`（多图时再加 `input_image_2` 起的字段）放进 `extra_body`，值是公网 URL 或 data URL；也可以直接使用本页的 Python 脚本。

## 相关文档与来源

* [FLUX.2 API：图像生成](/api-capabilities/flux-image-generation)：文生图、尺寸与旧版 Kontext 兼容
* [Images API 参考](/api-reference/images)：`save_images.py` 保存脚本与通用错误处理
* [Seedream API](/api-capabilities/seedream-image)：另一款支持多张参考图的模型
* [图像 API 选型与价格](/api-capabilities/image-generation-guide)：与其他图像模型比较
* [BFL FLUX.2 图片编辑文档](https://docs.bfl.ai/flux_2/flux2_image_editing)：参考图字段、数量上限与结果链接有效期
* [BFL FLUX.2 概览](https://docs.bfl.ai/flux_2/flux2_overview)：三款模型的定位与差异


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.