FLUX 3 接口调用返回报错——先分清是密钥、路由还是参数格式？

调用 FLUX 3 接口返回报错时，最怕把三类问题混在一起看：鉴权没通过、路由地址写错、请求体字段格式不对。三者都会表现成一句笼统的“请求失败”或“参数错误”，但排查动作完全不同。比较稳妥的做法是先发一个尽可能小的请求，把业务参数全部去掉，用返回状态码判断错误落在哪一层，再逐层补回配置。字段名和可选值必须以你实际接入的文档为准，下面给的是通用骨架，不替代官方定义。

处理 FLUX 3 报错，建议按“鉴权 → 路由 → 请求体”的顺序排除：先用最小请求体复现同一个错误，记录状态码；401/403 先查密钥是否真的被进程读到，404/405 先查地址路径与请求方法，400/422 再对照文档核对字段名和类型。每一步都用切换前后同一条请求的返回结果做对照，不要在没有复现的情况下直接改业务代码。

先看返回状态码判断错误落在哪一层

错误信息笼统时，状态码是唯一相对可靠的线索。它不一定能精确指出问题，但能先把范围缩小到某一层。下面的分类是通用 HTTP 语义，具体接口的返回体内容需要结合你的接入文档确认，不要凭印象对号入座。

401 / 403：优先怀疑鉴权。密钥为空、密钥写死在代码里但没被替换、密钥前后带空格引号、请求头字段名不对，都归到这里。
404 / 405：优先怀疑路由。接口路径少了版本前缀、多了斜杠、域名写成了另一个环境，或者该路径要求的是另一种请求方法。
400 / 422：优先怀疑请求体。字段名拼错、类型不对（字符串传了数字）、必填项缺失、枚举值不在允许范围内。
429：配额或频率限制，不属于上面三层，先按接口约定做退避重试。
5xx：服务端问题，先隔一段时间用最小请求体重试，排除自己请求内容的干扰再判断。

实际操作时，建议把每次请求的“时间、状态码、返回体原文、请求体摘要”写入一行日志记录，而不是只打印一句“调用失败”。有了状态码对照，后面两步才有方向。

用最小请求体复现同一个错误

第二步是把业务参数全部剥掉，只留鉴权和最少的必填字段，看能否复现同一个报错。能复现，说明问题不在你的业务参数里；复现不出来，说明是某个业务字段触发的，可以回到第四步。下面的骨架是通用形式，字段名、路径、请求头名称都要替换成你实际文档里的写法。

curl -i -X POST "https://你的接口域名/你的模型路径" \
  -H "Authorization: Bearer $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型标识",
    "input": {}
  }'

发请求时加上 -i 保留响应头，能同时看到状态码和返回体。每改一处配置，都用同一条命令重跑一次，把结果按下面的形式记下来，避免边改边忘：

记录格式示例：
时间        | 请求体版本 | 状态码 | 返回体关键字段
---         | ---        | ---    | ---
第一轮      | 最小骨架   | 401    | 鉴权失败类提示
第二轮      | 最小骨架   | 404    | 路径不存在类提示
第三轮      | 最小骨架   | 400    | 字段校验类提示

这里不要一次改多个变量。密钥、路径、请求体一次只动一处，否则改完正常了你也不知道是哪一处起的作用。

把密钥移到环境变量并验证是否读到

如果第一轮就是 401/403，先别急着怀疑密钥本身失效。更常见的情况是：代码里读的是某个环境变量名，但实际设置的名字拼错，或者只在一个终端会话里 export 过，跑任务的进程根本没继承到。做法是把密钥从代码里挪到环境变量，再单独验证进程能否读到。

# 设置（当前会话）
export FLUX_API_KEY="你的密钥"

# 启动前确认当前 shell 是否读到（只打印长度或前后几位，避免明文泄露）
python3 -c "import os;k=os.getenv('FLUX_API_KEY');print('已读到' if k else '未读到', len(k) if k else 0)"

代码里改为从环境读取，并且在启动时做一次非敏感校验：

import os

key = os.getenv("FLUX_API_KEY")
if not key:
    raise RuntimeError("未读到 FLUX_API_KEY，检查环境变量名与进程环境")

headers = {
    "Authorization": f"Bearer {key}",
    "Content-Type": "application/json",
}

对照验证方式：切换前用写死密钥的版本发同一条最小请求，记录状态码；切换后先跑上面那段读取校验，确认输出“已读到”，再发同一条请求。如果读取校验通过但状态码仍是 401/403，需要继续确认请求头字段名、Bearer 前缀格式、以及密钥是否属于该环境。注意不要在校验输出里打印完整密钥，日志里也应做脱敏。

对照文档字段名和类型检查请求体

如果最小请求体能通过，但带上业务参数就报 400/422，基本可以判定是参数格式问题，而不是能力不支持。这时逐项核对，而不是凭字段名猜。核对清单建议包含：

字段名拼写是否与文档完全一致，包括下划线和驼峰写法；大小写敏感的场景尤其容易出错。
字段层级是否正确，参数是放在顶层还是嵌在 input 一类的子对象里。
类型是否匹配：文档要求字符串的地方不要传数字，要求数组的地方不要传单个值。
枚举值是否在允许集合内，例如尺寸、格式类字段的取值。
必填项是否齐全，空字符串和 null 通常不等同于“不传”。
请求头是否声明了 JSON 内容类型，否则服务端可能按其他格式解析请求体。

修正后重新发送，并用同一份对照表验证：

curl -i -X POST "https://你的接口域名/你的模型路径" \
  -H "Authorization: Bearer $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你的模型标识",
    "input": {
      "prompt": "一段简短的测试描述",
      "你的尺寸字段": "文档允许的取值"
    }
  }'

验证方式是从最小骨架开始，每次只加回一个业务字段并重跑，直到报错再次出现，那个字段就是问题点。这样得到的结论来自你自己的请求记录，比任何猜测都可靠。若字段名和类型全部对齐后仍报“不支持”类错误，再去看文档里该能力的适用条件，而不是继续在格式上打转。