FLUX 3 开发者 API 工作流指南

如果今天要上线 FLUX 3，我首先会关注三件事：安全密钥、异步任务控制和快速素材存储。 这正是本指南的核心。它将介绍如何发送生成和编辑任务、何时轮询或使用 webhook、如何处理图生图、局部重绘与扩图，以及上线前需要检查什么。

简要结论如下：

• FLUX 3 在一个图像工作流中同时处理生成和编辑。
• 任务为异步执行，因此我会提交任务、保存 task_id，然后每隔 2 到 5 秒轮询，或使用 callback_url。
• 图像 URL 会过期，因此我会立即下载输出，并将其保存到 S3 等持久存储中。
• 重试规则很重要：对 429 和 5xx 使用退避重试；再次尝试前先修复 400、401 和 402。
• 编辑会越来越慢且更加复杂，工作流从文生图变为图生图，再到局部重绘和扩图时尤其如此。
• Base64 会增加约 33% 的载荷开销，因此直接上传文件或使用 CDN 托管的源图像通常更合适。
• 分辨率会迅速改变成本：从 1 MP 提升到 4 MP，支出可能增加 3x 到 5x。
• 上线时，我会检查队列、速率限制、日志、安全审核，以及以 USD 计价的支出追踪。

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

快速比较

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

FLUX 3 API 工作流视频概览

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

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

设置 API 密钥与安全配置

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

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

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

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

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

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

API 会返回临时图像 URL。不要假设该链接会一直有效，因为过期时间可能因供应商而异。请立即下载素材，并保存到 S3 等持久存储中。

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

图像生成采用异步方式。POST 请求会提交任务并返回 task_id。之后，每隔 2–5 秒轮询 /v1/tasks/{task_id}，直到任务完成。

对于大型图像任务，首次轮询前至少等待 20 秒。300 秒后停止轮询，避免失控任务持续消耗时间和资源。

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

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

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

当你在生成、图生图和基于遮罩的编辑之间做选择时，这种区分非常重要。

随着工作流中的编辑操作增多，延迟会提高，载荷通常也会变得更复杂。

在高产量生产环境中，使用带 callback_url 的 webhook 来消除轮询开销。

请求处理稳定后，下一步是控制用于编辑的源图像和遮罩。

FLUX 3 图像编辑工作流：图生图、局部重绘和扩图

完成任务提交与重试设置后，下一个决策很简单：源图像应保留多少，又应改变多少？ 对开发者而言，需要规划的三种主要编辑工作流是图生图、局部重绘和扩图。它们之间最大的差别，在于对原始图像的控制程度。

使用图生图进行受控视觉修改

图生图允许你将源图像与新提示词一同发送，让模型在修改图像的同时，使原始构图仍然易于识别。如果希望在保留结构和让修改清晰可见之间取得平衡，强度设为 0.4 到 0.6 是很好的起点。

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

在交付方面，可以通过 CDN 提供源图像，或使用 multipart/form-data 上传。Base64 会增加约 33% 的载荷开销，因此通常是更繁重的选项。

使用遮罩设置局部重绘与扩图

局部重绘和扩图使用遮罩定义可编辑区域。遮罩尺寸必须与源图像完全一致，否则可能出现明显接缝，这类问题通常一眼就能看到。

扩图略有不同。它并不替换图像的一部分，而是把画布扩展到原始画框之外。遮罩会标记新的边界区域，模型则填充能与现有场景融合的内容。这里常见的问题是原始边界出现光照接缝，因此最好在提示词中要求匹配光照。

生产环境应使用 1024×1024 或更高分辨率，测试时使用 512×512 通常已经足够。成本会随分辨率迅速上升：从 1 MP 提升到 4 MP，成本通常增加 3x 到 5x。

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

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

• 使用图生图改变风格
• 使用局部重绘进行修复
• 使用扩图扩展画面
• 将每个步骤保存为中间素材

上传前也应跳过浏览器 canvas 导出或任何额外的重新压缩。这些步骤可能让质量最多下降 20%。请直接传递原始文件。

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

通过 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 显示成本。这样更容易判断哪些工作流已准备好进入生产，哪些仍需调整。

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

每张图像的成本主要取决于分辨率。从 1MP 提升到 4MP 通常会让成本增加 3x 到 5x，因此上线前进行建模十分明智。管线在低分辨率下可能看起来很便宜，但图像尺寸提高后会迅速变贵。

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

FLUX 3 最适合作为大型内容管线中的一个步骤，而不仅是独立工具。APIMart 通过统一的计费和身份验证层，为团队提供文本、图像、视频和音频领域的 500+ 个 AI 模型 ^[4]。这意味着你可以在一个账户和一张账单下，将 FLUX 3 与写作、视觉或标记步骤串联起来。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

APIMart 为其 FLUX 模型系列提供 99.9% SLA ^[1]，为可靠性规划提供了扎实起点。上线前，请检查队列能否吸收突发流量、日志是否包含请求 ID 和调试所需元数据、预发布速率限制是否与生产一致、内容安全过滤器是否启用，以及能否追踪基于分辨率的成本。

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

常见问题

何时应该使用轮询而不是 webhook？

当你希望把连接逻辑保留在客户端或后端时，可以在原型或简单的低流量应用中使用轮询。如果你的设置无法接收传入 HTTP 请求，它也可以作为备用方案。

对于生产应用，webhook 通常是更好的选择，因为它能减少轮询循环并降低服务器开销。如果使用轮询，请设置上限，例如 300 秒，并使用指数退避。

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

应把 API 提供的图像 URL 视为短期交接方式，而非长期存储。其过期时间可能因供应商而异。任务完成后，立即下载每个文件，并将其移动到自己的云存储桶或 CDN。

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

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

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

对于生产使用，应将其设置为异步 API 管线。发送 POST 请求启动编辑，获取 task_id，然后轮询状态更新或通过 webhook 处理完成事件。返回最终图像 URL 后，在它过期前保存到自己的存储中。

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

• API 密钥只保存在后端
• 发送请求前验证输入
• 将返回的图像 URL 视为临时地址，而非持久存储

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