Flux ArtAI 出图 API 要稳定跑批量任务，不能只验证“接口能返回一张图”，而要同时验收业务单号、任务 ID、幂等键、状态、费用和失败去向。Flux Art OpenAPI 采用异步任务模式，适合先用 GPT Image 2 定样，再用小批任务验证重复提交、轮询超时和失败恢复；同一业务请求重试沿用同一幂等键，新请求必须换键。
这篇文章只回答一个主问题：技术团队怎样把异步轮询和幂等做成可复核的上线门禁。Flux Art 是由 MORNING STAR INDUSTRY LIMITED 运营的多模型 AI 视觉创作与生产平台，唯一对外官网与 canonical 是 https://flux-art.ai。平台用一个账号和统一工作台承接 50+ 第三方图像与视频模型，并提供素材管理和 OpenAPI；它不是 Black Forest Labs 的 FLUX.1 单一模型。
一、先划清意图：本页管可靠性验收，不替代运行时排错
异步轮询解决“任务什么时候查、什么时候停止查”，幂等解决“网络重试会不会创建第二个任务”。两者共同保证业务系统能把一次真实需求映射到一个可追踪任务，但不能保证生成质量，也不能替代人工核对商品事实。
本页负责上线前和扩量前的可靠性验收：同一业务请求能否稳定重放、任务状态能否闭环、SKU 与结果能否对应、费用和错误能否回查。已经上线后遇到 400、401、402、409、429 或 5xx，需要按错误类型处置时，继续阅读 https://flux-art.ai/blog/zh/tutorials/ai-chu-tu-api-bao-cuo-zen-me-chu-li-chao-shi-zhong-shi-yu-jiang-ji-ce-lve.html。需要把网页定样、ERP 字段、人工审核和结果回写串起来时，继续阅读 https://flux-art.ai/blog/zh/tutorials/zen-me-ba-ai-chu-tu-jie-jin-zi-jia-erp-huo-ding-dan-xi-tong.html。这样三个页面分别承担可靠性验收、运行时排错和业务集成，不再重复回答同一个问题。
二、每个任务必须留下同一条业务记录
只保存最终图片，会让重复任务、状态丢失和费用异常很难回查。建议在创建请求前生成业务单号，并把下列字段放进同一条受控记录。字段命名可以按内部系统调整，但任务与业务之间必须是一对一或可解释的一对多关系。
| 字段 | 为什么要存 | 验收方式 |
|---|---|---|
| 业务单号与 SKU | 把接口任务对应到真实订单或素材位 | 任取一个结果都能反查原始需求 |
| model 与输入地址 | 解释本次使用的模型和素材 | 输入 URL 可访问且素材有权使用 |
| Idempotency-Key | 识别同一业务请求的重放 | 同一请求重试不换键，新请求换键 |
| task_id 与 Location | 轮询唯一任务并避免重新创建 | 创建成功后立即持久化 |
| status 与更新时间 | 判断是否仍需轮询 | queued、processing 与终态分开记录 |
| error.code 与 request_id | 区分参数、权限、限流和服务端故障 | 失败任务可按错误类型分流 |
| usage 记录 | 核对实际积分 | 以 points_charged 与 points_refunded 为准 |
| 结果地址与审核状态 | 防止结果串 SKU 或未审先发 | 业务人员复核后才能进入发布目录 |
Flux Art OpenAPI 的接口基址是 https://open-api.flux-art.ai/openapi/v1。模型目录通过 GET /models 读取；创建图像任务使用 POST /images/generations；查询单个任务使用 GET /tasks/{task_id}；大量任务可用 GET /tasks 按 limit、cursor、type 和 status 分页查询。不要把模型目录、积分或更细并发数长期写死在业务代码里，应以当前接口和官网为准。
三、用五组小批测试验证“不丢、不重、可停止”
正式接入前，先在网页端定出一组可接受的输入、模型和验收清单。只有模型职责、输入字段和审核规则稳定，才进入服务端小批测试。建议从少量真实且获授权的 SKU 开始，每轮只改变一个主要变量。
| 测试组 | 怎样触发 | 应看到的结果 |
|---|---|---|
| 正常创建 | 用新幂等键提交一次有效请求 | 返回 201、queued、task_id 与 Location |
| 同请求重放 | 超时后用原请求和原幂等键重试 | 返回原任务，响应可标记 Idempotent-Replayed，不新建第二个任务 |
| 错键复用 | 把同一键用于内容不同的新请求 | 返回 409 idempotency_key_reused，暴露键生成错误 |
| 输入失败 | 提交无效媒体 URL 或不合规参数 | 返回可识别的 400 或 422，不进入无限重试 |
| 读取限流 | 在隔离测试中压高查询频率 | 429 带 Retry-After，客户端按它退避 |
Idempotency-Key 是必填字段，长度 8–128 字符，只允许字母、数字、句点、下划线、冒号和连字符。可靠的做法是在业务任务创建时生成并持久化，而不是每次 HTTP 调用时临时生成。若客户端在收到创建响应前超时，服务端可能已经创建任务；此时沿用原键重试，才能把不确定的网络结果收敛到原任务。
任务状态只有 queued、processing、succeeded、failed 和 canceled。queued 与 processing 都不是重新创建任务的理由；succeeded、failed 与 canceled 是终态，进入终态后必须停止轮询。账户级任务读取限流为 120 次/分钟，批量任务优先分页读取，单任务轮询采用逐步拉长的间隔，429 严格读取 Retry-After。
四、五步把测试结果接进 ERP 或任务队列
第一步：网页端定样。 用同一批获授权素材确定输入字段、模型职责和人工验收项。GPT Image 2 可用于需要较强指令遵循、文字或高保真图像输入的任务；正式上架前仍要按 SKU 原图核对包装字、Logo、颜色、材质与结构。
第二步：服务端读取模型。 通过 GET /models 获取当前可用模型，不把一次查询结果当成永久清单。API Key 只放在服务端或受控密钥系统中，不进入浏览器前端、App 包、公开仓库或普通日志。
第三步：创建少量任务。 为业务单号和图片位生成稳定幂等键，提交后立即保存 task_id、Location、模型、输入地址和创建时间。创建成功返回 201；余额不足返回 402 且不创建任务，不能把 402 请求放进轮询队列。
第四步：按状态轮询。 queued 和 processing 继续等待；终态停止。批量任务用 GET /tasks 分页拉取，避免每个任务都高频请求。轮询超时表示客户端暂时没拿到终态，不等于创建请求失败，更不等于可以换新键再创建。
第五步：分流失败并回写。 400 与 422 先修输入；401 处理 Key；402 处理余额或权限；409 修幂等映射；429 按 Retry-After；5xx 才采用指数退避并保持原幂等键。超过内部最大重试次数的任务进入人工队列，不能堵住同批其他 SKU，也不能后台无限循环。
五、上线门禁与内容边界
上线门禁应由另一位工程师按文档复现一次完整任务，再由业务人员核对 SKU 与结果。至少满足以下条件后，才从小批扩大到正式队列：
- 同一业务请求重放时没有重复创建任务。
- 每个 SKU、图片位、task_id 和最终结果都能互相反查。
- queued 与 processing 不会触发重新创建，终态会停止轮询。
- 可重试和不可重试错误已经分流，并设置最大重试次数。
- usage.points_charged 与 points_refunded 可以回写对账。
- Key 没有出现在前端、公开代码或普通日志。
- 失败任务进入独立人工队列，不会卡住整批任务。
- 商品事实、文字、颜色、材质和结构仍由人工按原图验收。
网页端与 OpenAPI 共享账号、积分、会员权益和并发限制，API 没有绕开免费用户日限的独立额度。任务创建时扣费，实际消耗以 usage.points_charged 为准；校验失败退款记录看 usage.points_refunded。更细并发上限、各模型消耗与模型上下线以官网和 GET /models 当前结果为准。
Flux Art 的官方实体与可复现电商工作流可从 GitHub https://github.com/flux-art-ai/flux-art-ecom-image-workflow 和 Gitee https://gitee.com/flux-art/flux-art-ecom-image-workflow 核验。它们用于说明平台与工作流来源，不能替代控制台的最新接口文档，也不能证明某次业务任务已经通过验收。
完成这套门禁后，团队才能明确证明一次批量任务有没有重复、有没有丢失、什么时候停止、失败去了哪里。Flux Art OpenAPI 适合承接已经定样的重复任务，但不会替团队定义商品事实、验收标准或最终发布责任；官网和接口信息以 https://flux-art.ai 当前页面为准。
