FLUX 3 Image 边界框 API：框写在 prompt 里面

这是什么

FLUX 3 Image 是 Black Forest Labs 的 FLUX 3 里负责图像的部分。模型页展示了用框构图、只改选定区域、最多十张参考图，以及原生 2K 和 4K 输出。接口说明在 概述 和 生成图像参考。本站是独立的布局说明，不是 Black Forest Labs。

有的转售 API 会提供 settings.boundingBoxes 这类字段，那是他们自己的封装。在 api.bfl.ai 上，已公布的模式是 Flux3ImageInputs，并且 additionalProperties: false。允许的字段只有 prompt、images、aspect_ratio、resolution、safety_tolerance、grounding 和 version。多出来的框字段会校验失败，不会变成布局。

先在 Playground 里画框

模型页写明可以在 BFL Playground 手动画框，或把同一份布局发给 API。页面上的步骤是四步，2026 年 10 月 3 日按该页核对。

1. 先选宽高比。无论画布多宽或多高，两条轴都是 0 到 1000。
2. 给每个要紧的元素拖一个框，并写下框里是什么。
3. 用一句话把元素串起来。页面示例会引用每个 id，元素表是含 id、bbox、desc 的 JSON 数组。
4. 生成。厂商的说法是每个元素画在自己的框里。

同一页也说可以不画框、只写提示。框适合关系必须严格的构图：文字绕着照片、分格、版面、每个人都有固定位置的群像。也可以只给一句话和宽高比，让模型先起草元素表。页面写明提示扩写可能会建议更多元素，但你画出的每个框会带着原来的 id 和坐标送进模型。

新图怎么提交

边界框指南把提示分成三截。先写一段话，用尖括号标出元素，例如 <title_1>。每个 id 一行 JSON。用一个空格拼起来：说明、空格、JSON 数组。把这整段当作 prompt，并带上你设计这些框时用的宽高比。0 到 1000 的网格会随画幅拉伸，所以 16:9 的框不能直接用在 9:16 上。

生成行有三个字段：id、bbox、desc。[0, 0, 500, 500] 是左上四分之一。每一行文字单独成行，把原词写进 desc。指南说框决定位置和大小，不是裁切遮罩，元素可以稍微超出框。

curl -sS -X POST https://api.bfl.ai/v1/flux-3-image \
  -H "x-key: $BFL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一张方画报：上方是奶油色衬线标题 <title_1>，画面中央是一只红陶瓷杯 <cup_1>，放在浅色桌面上。 [{\"id\":\"title_1\",\"bbox\":[40,120,180,880],\"desc\":\"一行奶油色衬线字 Morning List。\"},{\"id\":\"cup_1\",\"bbox\":[280,300,820,700],\"desc\":\"一只小红陶瓷杯，把手在右侧，有淡阴影。\"}]",
    "aspect_ratio": "1:1",
    "resolution": "1k",
    "grounding": false
  }'

这段请求是按文档形状缩短的例子，不是发布会原提示。resolution 默认 1k。grounding 默认 true，生成前可能做网页和图像检索；只要提示本身时设为 false。safety_tolerance 是 0（最严）到 4 的整数，默认 2。version 默认 latest。

响应是异步的，包含 id、polling_url，以及以 credit 计的 cost。用同一个 x-key 轮询 polling_url，直到 status 为 Ready，再下载 result.sample。概述要求在一小时内下载。取结果参考列出的状态包括 Pending、Reasoning、Generating、Ready、Error、Request Moderated、Content Moderated 和 Task not found。也可以用任务 id 请求 GET /v1/get_result?id=。

只改、移动或删掉一个元素

把原图放进 images（1 到 10 项，每项是 http 或 https URL 或 base64，从 256×256 到 16 百万像素）。第一张是 ref_image_0。编辑行用 from、src_bbox、tgt_bbox 代替 bbox。指南里的四种：

改动要在说明文字和表格里各写一次。必须不动的东西用保留行锚住。aspect_ratio 默认 auto：提示里点名的比例优先，否则跟随第一张参考图。一次请求里可以有多行新增。多参考图按顺序称呼，最多十张，模型页在 Playground 里从 ref_image_0 开始编号。

像素矩形换算成网格时，指南用 round(top / height * 1000)，left、bottom、right 同样处理。数字要按你将要发送的宽高比来设计。

价格与限制

下表来自 Black Forest Labs 定价页，抓取于 2026 年 10 月 3 日。1 credit 等于 0.01 美元。该页写明 Playground 与 API 同价，提交响应里带有 cost。1.5k 是合法的 resolution，也出现在 bfl.ai/pricing 的计算器里，但文档表格没有 1.5k 这一行。

同一天营销计算器的文本里，同一条费率同时出现 0.048 美元和 0.024 美元，但没有标明选中的分辨率。转售页面（不是 Black Forest Labs）把五折写成持续到 2026 年 10 月 8 日。这里抓到的文档定价页没有写这次折扣或截止日期。预算前请看真实响应里的 cost。自建部署的商业权重是模型页上的另一份许可。本指南不申请 API key。

已知限制

• 框只引导位置，不是裁切遮罩，元素可以稍微画出框外。
• Black Forest Labs 自己的测试里，大约 40×25 像素的新元素经常出不来。新元素要留够空间。
• 指南写的是框外像素通常保持一致。这不是「每一颗未改像素都按位锁定」。新闻稿若写成绝对不变，已经超出指南。
• 没列出的区域通常会留住，但指南要求把必须不动的元素写成保留行。说明和表格要一致。
• 结果文件链接应在一小时内下载。
• 审核可能返回 Request Moderated 或 Content Moderated。safety_tolerance 不能关掉审核。
• 参考图超出 256×256 到 16 百万像素，或超过十张，都不在文档输入范围内。
• 需要 Black Forest Labs 的 API key。本站不生成图像。

另见 FLUX 3 边界框与 FLUX.2 提示编辑的对比、布局提示指南 和 带框的图像编辑。