FLUX 3 开发者 API 工作流指南
学习如何使用安全 API 密钥、异步任务、图像编辑流程、重试机制、持久存储和成本控制，构建可用于生产环境的 FLUX 3 图像处理管线。
如果今天要上线 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 调用，而是围绕任务、文件、重试和成本建立一条清晰的管线。
快速比较
| 工作流 | 发送内容 | 通常等待时间 | 主要用途 |
|---|---|---|---|
| 文生图 | 提示词、模型 ID、尺寸/宽高比 | 5–15 秒 | 生成全新图像 |
| 图生图 | 提示词、模型 ID、源图像、强度 | 10–30 秒 | 受控视觉修改 |
| 局部重绘 | 提示词、模型 ID、源图像、遮罩 | 15–40 秒 | 替换图像的一部分 |
| 扩图 | 提示词、模型 ID、源图像、扩展设置 | 15–40 秒 | 扩展画面范围 |
我喜欢这篇文章的一点是，它始终聚焦真正需要交付的内容：请求流程、编辑控制、生产设置和成本注意事项，而不仅仅是演示输出。
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，以免创建重复计费的任务。
当你在生成、图生图和基于遮罩的编辑之间做选择时，这种区分非常重要。
随着工作流中的编辑操作增多，延迟会提高，载荷通常也会变得更复杂。
| 工作流类型 | 必需输入 | 预期延迟 | 实现复杂度 |
|---|---|---|---|
| 文生图 | 提示词、模型 ID、尺寸/宽高比 | 5–15 秒 | 低 |
| 图生图 | 提示词、模型 ID、参考 URL、强度 | 10–30 秒 | 中等 |
| 局部重绘 | 提示词、模型 ID、源图像、遮罩图像 | 15–40 秒 | 高 |
| 扩图 | 提示词、模型 ID、源图像、扩展参数 | 15–40 秒 | 高 |
在高产量生产环境中，使用带 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 密钥还可以覆盖多个模型和项目。