FLUX 3 开发者指南：生产级图像工作流

如果今天要上线 FLUX 3，我首先会关注三件事：安全密钥、异步任务控制和快速素材存储。 这正是本指南的核心。它将介绍如何发送生成和编辑任务、如何轮询任务状态、如何处理单图编辑、bbox 局部编辑与多图参考，以及上线前需要检查什么。可以在 APIMart 上直接试用 FLUX 3 Image API。

简要结论如下：

• FLUX 3 在一个图像工作流中同时处理生成和编辑。
• 任务为异步执行，因此我会提交任务、保存 task_id，然后轮询 /v1/tasks/{task_id}，直到状态为 completed 或 failed。
• APIMart 生成结果保留 72 小时。
• 重试规则很重要：对 429 和 5xx 使用退避重试；再次尝试前先修复 400、401 和 402。
• 分辨率决定等待时间和成本：4k 可能需要数分钟，文档建议总等待上限设为 10 分钟。
• 源图像优先以公网 URL 传入 image_urls。Base64 也支持，但会增加约 33% 的载荷开销。
• 按截至 2026 年 10 月的原价，FLUX 3 Image 的 1k 为每张 $0.048，4k 为每张 $0.607，后者约为前者的 12.6 倍。 FLUX 3 Image
• 上线时，我会检查队列、速率限制、日志、安全审核，以及以 USD 计价的支出追踪。

如果只看一个核心结论：FLUX 3 的关键不是单次 API 调用，而是围绕任务、文件、重试和成本建立一条清晰的管线。

快速比较

我喜欢这篇文章的一点是，它始终聚焦真正需要交付的内容：请求流程、编辑控制、生产设置和成本注意事项，而不仅仅是演示输出。

核心要点

• FLUX 3 Image 通过同一个异步端点处理文生图、单图编辑、多图参考（最多 10 张）和在提示词中写 bbox 的局部编辑；没有 mask 参数，也没有 strength 参数。
• 任务遵循「POST 返回 task_id」的流程：轮询 /v1/tasks/{task_id}，状态为 completed 或 failed 时停止；4k 可能需要数分钟，文档建议总等待上限 10 分钟。
• 对 429 和 5xx 响应使用指数退避重试；400、401、402 错误需先修复请求再重试；并在重试前持久化 task_id，以免产生重复计费的任务。
• APIMart 生成结果保留 72 小时。
• 按截至 2026 年 10 月的原价，FLUX 3 Image 的 1k 为每张 $0.048，4k 为每张 $0.607，后者约为前者的 12.6 倍。 使用同一个 APIMart API key，即可调用多家供应商的模型。

FLUX 3 速览

FLUX 3 工作流视频概览

FLUX 3 工作流：身份验证、请求和任务处理

稳定的 FLUX 3 集成依赖三件事：安全密钥、临时图像 URL和异步任务处理。

设置 API 密钥与安全配置

绝不要把 API 密钥硬编码进源代码。应将其保存在服务端密钥管理器中，切勿在客户端代码或公开仓库中暴露。如果密钥泄露，请立即在 APIMart 控制面板中轮换。

最好把密钥轮换视为日常维护，而不是重大紧急事件。这种思维方式可以让设置更整洁，并在风险演变成问题前将其降低。

安全凭据、可预测的请求处理和可靠的任务管理，是交付能够经受生产环境考验的图像功能的基础。

构建文生图请求并处理响应

一个基本的 FLUX 3 图像生成请求需要：

• 模型 ID
• 文本提示词
• 尺寸或宽高比

APIMart 生成结果保留 72 小时。任务完成后请及时下载图片；如需长期使用，请转存到自己的 S3 等存储中。

处理长时间运行任务的轮询、重试和错误

图像生成采用异步方式。POST 请求会提交任务并返回 task_id。之后轮询 GET /v1/tasks/{task_id}，状态变为 completed 或 failed 时停止。文档没有规定轮询间隔，可以从几秒一次开始，再逐步拉长间隔。

等待上限应按分辨率设置：4k 可能需要数分钟，文档建议总等待上限为 10 分钟；较低分辨率可以设得更短。达到上限只表示客户端停止等待，不等于任务失败，只有状态返回 failed 才是失败。保存好 task_id，之后仍可再次查询，避免为同一需求重复提交任务。

重试需要适当判断，并非所有错误都应采用相同处理方式。

• 429 和 5xx 响应应触发指数退避并重试。
• 400、401 和 402 错误说明请求本身存在问题，例如参数错误、密钥缺失或无效，或账户余额不足。

如果请求本身有问题，在不修复根本原因的情况下重试只会浪费积分和时间。重试前还应持久保存 task_id，以免创建重复计费的任务。

无论是文生图、单图编辑还是局部编辑，都适用同一套重试规则。

不同工作流的差别主要在请求内容上；它们使用同一个端点和模型，并按 resolution 计费。

该模型文档没有提供 webhook 或 callback_url，因此生产环境需要自行管理轮询：用队列控制并发，并记录每个 task_id 的状态。

请求处理稳定后，下一步是决定如何把源图像和编辑指令交给模型。

FLUX 3 图像编辑工作流：单图编辑、局部编辑和多图参考

完成任务提交与重试设置后，下一个决策很简单：源图像应保留多少，又应改变多少？ FLUX 3 Image 的编辑全部通过 image_urls 加提示词完成，主要有三种用法：单图编辑、bbox 局部编辑和多图参考。

使用单图编辑进行受控视觉修改

在 image_urls 中传入一张源图像，并在提示词中写明要改什么、保留什么。该模型没有 strength 之类的强度参数，修改幅度只能靠提示词控制。aspect_ratio 为 auto 时，输出会沿用第一张参考图的宽高比。

它非常适合制作产品变体、刷新广告和重塑品牌风格。务必明确说明哪些内容不能改变，否则模型可能偏离源图像。一个实际用例是重复使用同一张基础照片制作季节性变体，而不必重新安排拍摄。

源图像可以是公网可访问的 HTTP(S) URL，也可以是 Base64。Base64 会增加约 33% 的载荷开销，因此通常优先使用 CDN 等公网 URL。

使用 bbox 指定局部编辑区域

该模型没有 mask 参数，传入 mask_url 会返回 HTTP 400。只想修改某个区域时，在提示词里用 <car_1> 这类标签指代元素，并在同一字符串末尾附上 bbox JSON 数组。坐标格式为 [top, left, bottom, right]，取值位于 0–1000 的归一化网格，不是像素。tgt_bbox 与 src_bbox 相同表示元素原地保留，不同则表示移动元素。下面的示例把框中的汽车改成红色，并保留背景：

{
  "model": "flux-3-image",
  "prompt": "In <ref_image_0>, make the car <car_1> red and preserve the background <background_1>. [{\"id\":\"car_1\",\"from\":null,\"src_bbox\":null,\"tgt_bbox\":[250,300,750,800],\"desc\":\"A red car, preserving its original shape and orientation.\"},{\"id\":\"background_1\",\"from\":\"ref_image_0\",\"src_bbox\":[0,0,1000,1000],\"tgt_bbox\":[0,0,1000,1000],\"desc\":\"Preserve the original road, background, and lighting.\"}]",
  "image_urls": [
    "https://example.com/car.jpg"
  ],
  "aspect_ratio": "auto",
  "resolution": "2k"
}

文档没有提供扩图（outpainting）专用参数。多图参考时，图像按顺序编号为 ref_image_0、ref_image_1 等，提示词里也可以写 Image 1 / Image 2，例如“Turn Image 1 into the style of Image 2.”。

预览可选择 resolution: "768sq"，交付时再按需求选择 1k、1.5k、2k 或 4k。这些是分辨率档位，不是 width/height 像素参数；4k 约为 16 MP，2k 才约为 4 MP。 FLUX 3 Image

将编辑步骤串联成可重复的管线

一种简单的组织方式如下：

• 使用单图编辑调整风格或细节
• 使用 bbox 局部编辑修改或移动指定元素
• 使用多图参考组合主体与风格
• 将每个步骤保存为中间素材

上传前也应跳过浏览器 canvas 导出或任何额外的重新压缩，以免损失细节。请直接传递原始文件。

这些编辑步骤稳定后，下一个挑战是把它们变成具有访问控制和成本追踪能力的统一产品工作流。

通过 APIMart 使用 FLUX 3 进行产品集成与成本控制

当编辑步骤可以重复执行后，APIMart 可以作为生产使用的中间控制层。你无需分别连接技术栈的各个环节，而是通过一个 API 层路由编辑管线，以管理访问、支出和下游自动化。

通过统一 API 工作流连接 FLUX 3

如果已经使用 OpenAI 风格的客户端，设置通常很轻量。多数情况下，只需换用新的基础 URL、添加 API 密钥，并把请求指向 FLUX 3 模型 ID。

优势在于可以保留相同的请求结构、解析、重试规则和异步逻辑。FLUX 3 任务在 APIMart 上遵循相同的流程：从 POST 获得 task_id，然后通过 GET 进行轮询。因此，无论是运行一次图像生成，还是在完整管线中串联多个编辑步骤，现有任务处理代码都能继续工作。一个 APIMart API 密钥还可以覆盖多个模型和项目。

以 USD 追踪用量、预算和团队工作负载

APIMart 控制面板会汇总不同模型和项目的用量，并以 USD 显示成本。这样更容易判断哪些工作流已准备好进入生产，哪些仍需调整。

例如，可以为商品目录生成项目设置月度上限，并在支出达到上限前设置提醒阈值。这样团队就有余地在成本失控前减慢或暂停批处理任务。

按截至 2026 年 10 月的原价，FLUX 3 Image 的 1k 为每张 $0.048，4k 为每张 $0.607，后者约为前者的 12.6 倍。 下表为截至 2026 年 10 月的原价，单位为美元/张；参考图不另收费。当前价格以 FLUX 3 Image 价格表为准。

将 FLUX 3 图像生成与更广泛的多模态工作流结合

可以把 FLUX 3 放在内容管线中的图像生成环节，再连接写作、视觉理解或标记步骤。APIMart 支持用同一个 API key 调用多家供应商的模型。 APIMart

你还可以设置基于角色的权限，让分析访问权限只分配给需要它的人员，同时仅允许获批工程师管理密钥。

这套设置使扩展、速率限制和日志记录成为日常运营的下一层工作。

生产部署：扩展、可观测性和发布决策

规划队列、并发与速率限制

当生成和编辑已经稳定，生产环境就成为另一套挑战。此时，工作的重点不再是让一次请求成功，而是在系统不崩溃的情况下处理流量。

图像生成需求可能迅速激增，因此不应以内联方式处理每个请求。队列能提供缓冲空间，把请求接收与执行分开，避免突发流量同时冲击所有工作进程。

并发量也应与速率限制保持一致。一种简单方式是将队列与每个模型的并发上限结合，这样既能吸收突发流量，又不会超过供应商限制。

为调试与可复现性记录正确数据

如果每次运行的输出都不同，而又没有记录正确字段，调试很快就会陷入混乱。

为了保证可复现性和故障排查，应记录请求 ID、任务 ID、提示词和生成元数据。这些信息足以追踪发生了什么，并在需要时重新运行任务。日志深度也应与环境相适应，预发布和生产日志应保持实用，同时避免暴露不必要的载荷数据。

记录每个任务的分辨率和估算成本同样明智，这有助于在高成本异常值演变成账单意外前发现它们。

总结：上线前如何评估 FLUX 3 图像功能

将 FLUX 3 投入生产前，请在以下环境中验证设置，并使用不同的访问、日志和审核规则。

使用这张矩阵验证上线准备情况。

可靠性规划应以实际压测、监控和恢复流程为依据。上线前，请检查突发流量处理、日志中的请求与任务 ID、速率限制、内容安全措施，以及按分辨率追踪成本的能力。

如果这些控制措施通过负载测试，FLUX 3 就已准备好投入生产。

想全面了解这个模型，可以阅读 FLUX 3 全解析：型号、上线情况与价格。

常见问题

FLUX 3 任务应该轮询多久？

持续轮询 GET /v1/tasks/{task_id}，直到状态为 completed 或 failed。该模型文档没有提供 webhook 或 callback_url，因此需要通过轮询获取结果。

等待上限按分辨率设置：4k 可能需要数分钟，文档建议总等待上限为 10 分钟。达到上限只是客户端停止等待，任务本身不一定失败；保留 task_id，稍后仍可再次查询。

生产环境应如何存储 FLUX 3 图像？

APIMart 生成结果保留 72 小时。任务完成后请及时下载图片；如需长期使用，请转存到自己的 S3 等存储中。

使用异步工作流。轮询 task_id 直到任务完成，然后将文件保存到持久基础设施中。最好还维护一份包含 task_id、时间戳和内部文件路径的数据库日志，从而获得清晰的审计记录。

哪种 FLUX 3 编辑工作流最好？

使用从现有图像开始的图像编辑工作流，再通过聚焦的提示词只修改真正需要改变的内容。必要时也可以包含其他语言的文本，同时保持图像其余布局不变。

对于生产使用，应将其设置为异步 API 管线。发送 POST 请求启动编辑，获取 task_id，然后轮询任务，直到状态为 completed 或 failed。返回最终图像 URL 后，在它过期前保存到自己的存储中。

这里有几条重要基本规则：

• API 密钥只保存在后端
• 发送请求前验证输入
• APIMart 生成结果保留 72 小时。

这套设置可以让工作流保持清晰，并在流量增长后避免本可避免的错误。