> ## 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-pro、flux-2-flex、flux-2-max 生成图片：模型选择、尺寸参数、cURL 与 Python 示例和结果下载。

FLUX.2 是 Black Forest Labs 的图像模型，老张API推荐默认使用 `flux-2-pro`。生成和编辑都调用同一个 JSON 接口，按次计费，结果链接约 10 分钟后失效。

| 项目 | 内容 |
| - | - |
| `flux-2-pro` | \$0.03/次，默认推荐 |
| `flux-2-flex` | \$0.06/次 |
| `flux-2-max` | \$0.07/次 |
| 价格来源 | 2026 年 9 月 24 日公开价格配置，见[模型与价格总表](/models) |
| 接口 | `POST /v1/images/generations`，请求体为 JSON |
| 输出尺寸 | `size`，或 `width` 与 `height` |
| 编辑 | 同一端点传入 `input_image`，最多 8 张参考图，完整写法见 [FLUX.2 图片编辑 API](/api-capabilities/flux-image-edit) |
| 返回结果 | 图片 URL，约 10 分钟后失效，请求成功后要立即下载 |
| 令牌 | `default` 分组，计费模式为按量优先（推荐）或按次计费 |

## 选择模型

* `flux-2-pro`：默认推荐，适合大多数文生图和编辑任务；
* `flux-2-flex`：需要更细控制、在质量与成本之间折中的设计任务；
* `flux-2-max`：质量优先的最终商业素材和复杂构图。

本页示例中的字段对三款模型通用，切换模型时只改 `model`。旧版 Kontext 模型的用法见下文「旧版 Kontext 兼容」。

## 准备令牌与环境

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

<img src="https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/token-create-per-request.png?fit=max&auto=format&n=_loZ0Jy0ZI__xJ9z&q=85&s=1fdceb804bb3ad50f83a21ec65b4d807" alt="在令牌管理中新建令牌，计费模式选择按次计费后点击创建" width="1364" height="1170" data-path="images/token-create-per-request.png" />

设置密钥，并安装 Python 示例用到的依赖：

```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 示例拿到 URL 后直接下载。

## 生成图片

不传 `input_image` 时是文生图。输出尺寸二选一：

* `size`，如 `1024x1024`、`1792x1024`、`1024x1792`；
* `width` 和 `height`，直接指定像素。

### cURL

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "A ruby red retro robot riding a yellow skateboard in front of a turquoise glass greenhouse, clean product illustration style",
    "size": "1792x1024"
  }' \
  -o flux-generation.json

python save_images.py flux-generation.json flux-generation
```

成功时 `data[0].url` 是图片地址，保存脚本会立即下载并按实际格式命名，例如 `flux-generation-1.jpg`。

### Python

```python theme={null}
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}

response = requests.post(
    API_URL,
    headers=HEADERS,
    json={
        "model": "flux-2-pro",
        "prompt": "A cinematic product photo of a transparent smart speaker on a marble table",
        "size": "1024x1024",
        "output_format": "png",
    },
    timeout=240,
)
response.raise_for_status()
image_url = response.json()["data"][0]["url"]

# 链接约 10 分钟后失效，拿到后立即下载
image = requests.get(image_url, timeout=60)
image.raise_for_status()
Path("flux-generation.png").write_bytes(image.content)
print("已保存 flux-generation.png")
```

## 编辑图片

编辑同样调用 `POST /v1/images/generations`，只是在 JSON 中用 `input_image` 传入参考图，字段值可以是公网图片 URL 或 data URL。下面把本地 `source.png` 转成 data URL 后编辑：

```bash theme={null}
IMAGE=source.png   # 替换为你的图片路径
IMG1="data:$(file --mime-type -b "$IMAGE");base64,$(base64 < "$IMAGE" | tr -d '\n')"

curl --fail-with-body "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
```

参考图已在公网时，把 `input_image` 的值直接换成图片 URL 即可。多张参考图合成、Python 写法、多图提示词和常见错误，见 [FLUX.2 图片编辑 API](/api-capabilities/flux-image-edit)。

## 参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | `flux-2-pro`、`flux-2-flex` 或 `flux-2-max` |
| `prompt` | string | 是 | 生成描述或编辑指令 |
| `input_image` … `input_image_8` | string | 编辑时使用 | 参考图，见 [FLUX.2 图片编辑](/api-capabilities/flux-image-edit#请求参数) |
| `size` | string | 否 | 如 `1024x1024`、`1792x1024`、`1024x1792`；与 `width`、`height` 二选一 |
| `width`、`height` | integer | 否 | 必须是 16 的倍数，最小 64，总像素不超过约 400 万（如 2048×2048） |
| `n` | integer | 否 | 只支持 1 |
| `output_format` | string | 否 | `jpeg`（默认）或 `png` |
| `seed` | integer | 否 | 固定随机种子，便于复现 |

一次请求返回一张图，按次计费。实际扣费可在[调用日志](/faq/call-logs)中核对。

## 旧版 Kontext 兼容

`flux-kontext-pro`（\$0.035/次）和 `flux-kontext-max`（\$0.07/次）供已有集成继续使用，新接入请使用 FLUX.2。与 FLUX.2 相比：

* Kontext 同样调用 `/v1/images/generations`；
* 用 `aspect_ratio` 控制画幅，不使用 `size`、`width` 或 `height`；
* 比例可在 3:7 到 7:3 之间选择，例如 `1:1`、`16:9`、`9:16`、`21:9`，输出总像素约为 100 万。

```bash theme={null}
curl --fail-with-body "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext-pro",
    "prompt": "A minimalist poster of a paper crane over calm water, soft morning light",
    "aspect_ratio": "16:9"
  }' \
  -o kontext-generation.json

python save_images.py kontext-generation.json kontext-generation
```

使用 OpenAI Python SDK 时，把 `aspect_ratio` 放进 `extra_body`。图片编辑请使用 FLUX.2，写法见 [FLUX.2 图片编辑 API](/api-capabilities/flux-image-edit)。

## 常见问题

### 需要像 BFL 官方 API 那样轮询结果吗？

不需要。BFL 官方 API 先返回任务 ID 和 `polling_url`，要轮询到 `Ready` 才能拿到图片；老张API在同一个请求里等生成完成，直接在响应的 `data[0].url` 返回结果。

因此客户端超时要留足，本页 Python 示例设为 240 秒。请求要经过反向代理或云函数时，它们的超时和执行时限也要一起调大，否则会在生成完成前断开。

### 为什么图片链接过一会儿就打不开了？

结果 URL 约 10 分钟后失效，BFL 官方的结果链接有效期同样是 10 分钟。

每个请求返回后立即在服务端下载，存到本地或自己的对象存储，再把自己的地址写进数据库或交给前端；批量任务不要等整批结束再统一下载。

链接失效后只能重新请求，重新请求会再计一次费用。

### 怎样复现同一张图？

使用相同的 `seed`，并保持模型、提示词和尺寸参数完全一致。

### 海报文字和品牌色怎样更准确？

画面里文字多时（海报标题、信息图、界面稿），优先试 `flux-2-flex`，BFL 将它定位为擅长文字渲染和保留小细节；需要最高画质和最强提示词遵循时用 `flux-2-max`。

品牌色可以直接在提示词里写十六进制色值，例如 `the mug is #FF5A1F`，FLUX.2 会按色值着色。描述较复杂时，也可以把主体、背景、光线、风格等写成 JSON 字符串，整体作为 `prompt` 传入。

### 请求失败会扣费吗？

一般不会。FLUX.2 按次计费，成功返回图片的请求计一次；参数错误、内容审核拦截等直接返回错误、没有生成图片的请求不计费。

客户端超时不等于请求失败：服务端可能已经生成完成并扣费。重新提交前先到[调用日志](/faq/call-logs)确认该请求的状态，避免重复扣费。实际扣费以调用日志为准。

### 能用 OpenAI SDK 调用吗？

可以用 `client.images.generate()`：

* 把 `base_url` 设为 `https://api.laozhang.ai/v1`；
* `model`、`prompt`、`size` 直接传；
* `width`、`height`、`seed` 等 FLUX 专有字段放进 `extra_body`。

结果同样在 `response.data[0].url`，拿到后立即下载。

编辑也建议用 `client.images.generate()`，把 `input_image` 放进 `extra_body`；`client.images.edit()` 只能传一张图，说明见 [FLUX.2 图片编辑 API](/api-capabilities/flux-image-edit#常见问题)。

## 相关文档与来源

* [FLUX.2 图片编辑 API](/api-capabilities/flux-image-edit)：单图修改、最多 8 张参考图合成与 Python 写法
* [图像生成 API 选型与价格](/api-capabilities/image-generation-guide)：与其他图像模型对比
* [Seedream API](/api-capabilities/seedream-image)：另一款支持多张参考图的模型
* [模型与价格总表](/models)与[控制台模型价格](https://api.laozhang.ai/account/pricing)：当前单价
* [BFL FLUX.2 官方文档](https://docs.bfl.ai/flux_2/flux2_overview)：模型差异、十六进制色值与结构化提示词
* [BFL API 接入指南](https://docs.bfl.ai/api_integration/integration_guidelines)：官方异步轮询流程与结果链接 10 分钟有效期


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