FLUX.2 API 接入：官方 API 上手指南

FLUX.2 是 Black Forest Labs 当前在售的图像生成与编辑模型族，它有自己的一套官方 API：请求发往 api.bfl.ai，文档在 docs.bfl.ai，密钥从 dashboard.bfl.ai 领取。这篇走完从注册到落盘的全流程，然后把官方公布了什么、没公布什么分开列清。

Black Forest Labs 之后又发布了 FLUX 3，那是一条覆盖图像、视频与音频的多模态线。本文讲的仍是图像这条线里的 FLUX.2，FLUX 主题页上有各档位对照表。

FLUX.2 API 能调用什么

托管 API 提供 [max]、[pro]、[flex] 与 [klein]。定价文档把 [dev] 标为「Local only — Open weights, non-commercial (no hosted API)」，模型总览也写明 Base 变体「are not offered on the public API」。

一次任务是一次 POST，返回的是待轮询的作业，而不是图片。你用 x-key 头带上密钥，请求体里放提示词与输出尺寸；响应回一个 id 和一个 polling_url；轮询这个地址，直到 status 变成 Ready；成品图以 result.sample 出现，那是一个签名地址，文档写明有效期十分钟。

有两条限制在第一天就该写进代码：宽高必须是 16 的倍数，最小 64×64，最大 4 MP。FLUX.2 也不支持负向提示词。

从 BFL Dashboard 拿 API key

dashboard.bfl.ai 就是全部开通路径：用邮箱注册并验证，充值 credits（定价文档原句是「1 credit = $0.01 USD」），然后创建 API key。

快速开始页有一条值得重复的提醒：密钥只在创建时显示一次。把它放进密钥管理服务，不要放进前端代码——浏览器能读到的密钥就是公开密钥。

官方还有一条不需要密钥的路。Black Forest Labs 提供位于 https://mcp.bfl.ai 的 MCP 服务器，文档里的客户端命令是 claude mcp add --transport http FLUX https://mcp.bfl.ai，走 OAuth 登录。这条路适合助手类工具，后端流水线仍然要用密钥。想先在浏览器里见一见模型，FLUX 怎么用讲的就是同一个账号的 playground 那一半。

第一条请求：用 REST 调 api.bfl.ai

预览端点与固定快照

总览页把 flux-2-pro-preview 与 flux-2-pro 并列：前者被描述为最新的 FLUX.2 [pro] 模型，后者是固定快照，供需要可复现的工作流使用；flux-2-klein-9b-preview 与 flux-2-klein-9b 遵循同样的搭配。官方有一句话可以直接定选型：预览端点与非预览端点共用同一套 API 契约，请求格式与响应格式完全一致，换端点只是换个字符串。

# 需要 curl 与 jq。密钥来自 dashboard.bfl.ai。
API_BASE="https://api.bfl.ai/v1"
MODEL="flux-2-pro-preview"

# 1. 提交任务，把响应回传的轮询地址留下来。
curl -s -X POST "${API_BASE}/${MODEL}" \
  -H "x-key: ${BFL_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A ceramic espresso cup on a walnut counter, oblique morning light, shallow depth of field.",
    "width": 1024,
    "height": 1024
  }' > submit.json

polling_url=$(jq -r .polling_url submit.json)

# 2. 轮询到状态变成 Ready。
while true; do
  curl -s -H "x-key: ${BFL_API_KEY}" "${polling_url}" > poll.json
  [ "$(jq -r .status poll.json)" = "Ready" ] && break
  sleep 1
done

# 3. 在同一次运行里下载：签名地址只活十分钟。
curl -sL -o flux-2-output.png "$(jq -r .result.sample poll.json)"

有三个细节承重。鉴权是一个 x-key 头，不是 bearer token。提交接口回的是轮询地址而不是图片，轮询循环就是为它存在的。width 与 height 是硬性要求，选尺寸时自己按 16 的倍数挑。

请求体里的多参考图编辑

九兆像素预算怎么算

编辑沿用同一个端点，只是多出字段：input_image、input_image_2，依次类推，每个字段放一张参考图。模型总览给了各档上限——[klein] 最多 4 张，[max]、[pro]、[flex] 走 API 最多 8 张、在 playground 里 10 张，[dev] 建议不超过 6 张。

决定输出分辨率的算术在提示词指南里：API 上 [pro] 有 9 MP 的输入加输出总额度，所以输出 1 MP 最多带 8 张参考图，输出 2 MP 是 7 张。计费是另一套规则——每张参考图不管你要的输出尺寸是多少，都按 1 MP 计费；传多张时，超过 1 MP 的参考图会被压到 1 MP。只传一张时则按原分辨率处理，单张超过 4 MP 会被压到 4 MP 并按 4 MP 计费。

[klein] 不带 prompt upsampling，所以在这一档写详细描述比在其他档更重要。第三方渠道的上限可能更低：kie.ai 的 API 文档写最多 8 张输入图，那是该渠道自己的口径。

把返回的图片落到文件

签名地址的有效期，就是下载必须在同一次运行里完成的理由：轮询、取 result.sample、抓取、写字节，十分钟内做完。

// 需要 Node 18+ 以使用全局 fetch。从环境变量读 BFL_API_KEY。
import { writeFile } from 'node:fs/promises';

const API_BASE = 'https://api.bfl.ai/v1';
const MODEL = 'flux-2-pro-preview';

const submit = await fetch(`${API_BASE}/${MODEL}`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-key': process.env.BFL_API_KEY,
  },
  body: JSON.stringify({
    prompt:
      'A ceramic espresso cup on a walnut counter, oblique morning light.',
    width: 1024,
    height: 1024,
  }),
});
if (!submit.ok) throw new Error(`submit failed: ${submit.status}`);

const { polling_url: pollingUrl } = await submit.json();

let result;
for (let attempt = 0; attempt < 60; attempt += 1) {
  const poll = await fetch(pollingUrl, {
    headers: { 'x-key': process.env.BFL_API_KEY },
  });
  const body = await poll.json();
  if (body.status === 'Ready') {
    result = body.result;
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 1000));
}
if (!result) throw new Error('no result after 60 polls');

const image = await fetch(result.sample);
await writeFile('flux-2-output.png', Buffer.from(await image.arrayBuffer()));
console.log('wrote flux-2-output.png');

脚本直接复用提交响应里回传的值，靠轮询等待而不是重新提交，并在 60 次之后停下，卡住的作业不会一直占着 worker。

官方页面公布了什么，没公布什么

定价文档全部按兆像素报价，并在开头写明换算：1 credit = $0.01 USD，按张计费，API 与 playground 同价。

第一兆像素按固定价收，之后每多一兆像素加到总额里。官方给的例子是：klein 4B 出一张 2 MP 的图，$0.014 加 $0.001。批量请求把基础价乘以张数；微调端点公开测试期与基础端点同价；所有操作的输出上限都是 4 MP。

没公布的东西同样要列清。官方没有公布任何免费 API 额度——它宣传的免费 demo 指的是 playground，免注册、不要卡，不是每月送多少张 API 图。任何官方页面都没有公布成功率、基准分数或与其他模型的正面对比；地区可用性没有逐国拆分；开放权重的商业授权档位只给了名称与配额（Builder 每月 10K 张、Platform 每月 100K 张），没有可以据以计算的单价。

官方数字彼此不一致时，分歧发生在官方页面之间：[flex] 在定价表里是每兆像素 $0.05，在模型总览里是 $0.06，做预算时以你实际读的那一页为准。开放权重是与托管 API 并行的一条线：release notes 里 [klein] 4B 是 Apache 2.0、[klein] 9B 是 FLUX Non-Commercial License，定价表则把 [dev] 列为 local only。想看另一个托管图像族的口径，Nano Banana 主题页与 GPT Image 主题页讲的是同一类问题。

常见问题

FLUX.2 API 有免费额度吗？ 官方页面没有公布免费 API 额度。它宣传的免费 demo 是 playground，免注册也不要卡；API 调用按 credits 计费。

该调哪个端点？ 要最新的 [pro] 用 flux-2-pro-preview，要可复现的快照用 flux-2-pro，成本或延迟优先时选 klein 端点。三者的契约完全一致。

一次请求最多带几张参考图？ 按模型总览：[klein] 最多 4 张，[max]、[pro]、[flex] 走 API 最多 8 张、playground 里 10 张，[dev] 建议不超过 6 张。[pro] 的 9 MP 输入加输出额度会随输出分辨率升高而进一步压低这个数字。

FLUX.2 支持负向提示词吗？ 不支持。把想排除的东西写进正向描述里。

必须轮询吗？ 是。提交返回的是带 polling_url 的作业，只有 status 变成 Ready 之后，图片才以 result.sample 出现。

把密钥放进密钥管理服务，把 model id 放进配置，把下载放进轮询这一次运行里。

发布于

2026年9月13日

信息核验

2026年9月13日

作者

AI Tool Blog 编辑部