① 回调地址填什么 —— 填客户自己服务器上的一个接口地址，必须以 http:// 或 https:// 开头，能被公网访问（强烈建议 https）。平台在任务结束时会向它 POST 一段 JSON。留空即为关闭回调。

② 签名密钥填什么 —— 你自己定的一串口令，建议 32 位以上随机串、不超过 64 字符，跟地址一起保存。它只有一个作用：让平台发的通知无法被第三方伪造。填好后把这一串用安全渠道告知客户，客户按第 ④ 步验签。

③ 客户会收到什么

POST 客户的回调路径
Content-Type: application/json
X-BDXFD-Event: job.done
X-BDXFD-Signature: 3f8a...(64 位小写十六进制)

{"event":"job.done","job_id":1024,"user_id":7,"status":"done",
 "result_url":"comfyui_output_auto_clean/7/xxx_00001_.png"}

一个工作流出多张图时，result_url 是**逗号分隔的内部 key 串**（按出图顺序）：
{"event":"job.done","job_id":1025,"user_id":7,"status":"done",
 "result_url":"comfyui_output_auto_clean/7/a_00001_.png,comfyui_output_auto_clean/7/a_00002_.png"}

（注意 result_url 是内部相对路径，不是能直接打开的网址；管道事件给的是可直接下载的链接）

④ 验签方式（务必用原始请求体）
签名值 X-BDXFD-Signature = HMAC-SHA256(签名密钥, 原始请求体) 的十六进制小写。
⚠️ 必须用「收到的原始 body 字节」计算，不能先把 body 解析成对象再重新序列化——空格、转义、中文都会变，算出来对不上。

import hmac, hashlib

def check(secret: str, raw_body: bytes, sig: str) -> bool:
    want = hmac.new(secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, sig)

# Flask：raw_body = request.get_data()，验签通过后再 json.loads(raw_body)

⑤ 五种事件与各自带什么字段

• job.done　工作流出图成功（工作流出图、开放 API 出图都走这条）→ status=done、result_url。⚠️ 一个工作流可以出多张图，此时 result_url 是逗号分隔的多个 key（顺序即出图顺序），客户需按逗号拆开逐张取。
• job.failed　单图失败 → status=failed、result_url=null、error=失败原因
• pipeline.done　管道（多图）成功 → status=success、result_urls=结果集合
• pipeline.failed　管道失败 → status=failed、error=失败原因
• job.test　点上面「测试」按钮发出的验证通知（job_id=0），客户返回 200 即代表通

⚠️ 取结果的两个字段不一样，这是最容易踩的坑：

• 工作流出图 result_url 是对象存储里的相对路径（内部 key），不能直接丢给浏览器打开。客户拿 job_id 再调一次出图结果查询接口（/api/open/image/result）就会拿到带签名的可下载链接（有有效期）；该接口除原有的 result_url（=第 1 张）外，新增 result_urls 数组给出全部图片，多图场景请用这个。
• 管道 result_urls 里已经是可直接下载的临时链接，24 小时内有效，过期要重新取。

⑥ 两条硬性要求

• 客户必须在 3 秒内返回：平台只等 3 秒，超时算这条回调失败。所以别在回调里同步做重活（下载图片、跑 3D 转换），要先落库、立刻返回 200、再异步处理。
• 回调失败不影响出图：发送失败只记进下方「最近回调记录」，任务结果和扣点都不受影响。所以要把「不漏单」做扎实，客户侧请用轮询任务查询接口做兜底。

⑦ 保存后怎么自查：先点「测试」按钮，再看下面「最近回调记录」——[ok] 就是通了；[failed] 常见原因：地址写错、客户没开 https、服务器没放行、或没在 3 秒内应答。

• AK/SK 就是客户调用接口的账号口令：AK 标识身份，SK 用来算签名（请求头 X-Access-Key / X-Timestamp / X-Nonce / Authorization）。客户调「管道出图」等 API 时必须带。
• SK 只在点「生成 API 密钥」时显示一次，弹窗关掉后就再也看不到（列表里只显示 AK、不回显 SK）。请当场复制给客户；确实丢了就让客户重新生成一把。
• 一个用户可以有多把密钥，方便客户区分测试/生产环境。某把泄露了 → 点「禁用」立即失效，不用影响其他。
• 安全底线：AK/SK 不要写进网页前端、不要提交到代码仓库、不要和别的系统共用同一串口令。

• 公有 / 专属的区别：公有=平台通用工作流，可授权给任意客户；专属=归属某个用户的工作流，只适合授给它的归属者。
• 勾完必须点「保存授权」才生效，直接关窗口等于没改。
• 授权后，客户在平台门户里就能看到并调用这个工作流；下面「客户专用页 → 指定工作流」的下拉，列的也正是这里的工作流。
• 标了「已下线」的不要勾——客户点了会报错，请先在工作流列表把它重新上线。
• 新客户想省事：点「全选公有」一键铺底，再按需取消。
• 只出图权限的把公有工作流勾上就够；每次保存专用页配置时也会自动补一次授权，所以先配授权、再配专用页最省事。

• 工作流 vs 管道：两者都能出多图 ——「一次出几张」只取决于产物里有几个输出节点（工作流里放 2 个保存节点就出 2 张，与走哪条链路无关）。管道的价值是「多步编排」：一次上传 → 串多个节点（出图 → 放大 → 转换 → …）。只出 1 张、或工作流本身就出多张的，用工作流链路即可，不必上管道。
• 只有「已上线」的管道才会出现在下面的列表里。下拉里找不到想要的管道 → 先去「管道列表」把它上线；如果下面一个都没有，说明当前没有任何已上线管道（归档的管道不算）。
• 勾选并保存后，客户就能用自己的 AK/SK 调 API 提交；每次调用按管道标价的点数扣费，失败会自动退回。
• 勾选后下面会自动展开「用户调用方式」，那是给客户对接的人看的，可以直接复制过去。
• 「客户专用页」选管道链路时，列的是同一批已上线管道，保存时会同时补上授权；选工作流链路则完全不涉及管道。

① 开通：勾「开通专用页」→ 选生图链路 → 指定工作流/管道 → 勾要开放的功能 → 点「保存专用页配置」。保存即生效，不需要重启或重新部署。

② 地址：{{ locationOrigin() }}/w/客户登录账号（就是下面那行「页面地址」，直接复制）。建议顺手做成二维码放进客户说明书。
地址里的账号名只是让客户看着像「他自己的入口」，不参与鉴权——客户仍要用你给的账号密码登录，猜不到也进不去，就算猜到也进不去。

③ 勾选项 = 客户能看到的界面：没勾的功能，客户页面上连按钮都不会出现，建议按需少开。

• 单图展示：结果区按「单张」样式展示（只显示第一张）
• 多图展示：结果区按「列表」展示全部产物。工作流链路同样支持 —— 不必走管道，只要这个工作流本身输出多张，勾上它客户就能看到全部；两个都不勾则客户看不到结果。
• 3D 预览 + STL 下载：把结果图转成浮雕预览和 STL 模型，按下面「3D 转换单次扣点」收费；不勾则客户完全看不到这个入口
• 16 位 TIFF 下载：给需要高精度灰度图的客户（精雕 / CNC 出刀路用）

④ 扣点：出图扣多少点由所选工作流 / 管道自己的标价决定；「3D 转换单次扣点」是单独一项。客户余额不足时页面会给他提示，回来点上方「充值点数」即可。

⑤ 页面是干净的：专用页不会出现任何平台内部名称、工作流原文件名、接口地址，只显示你填的「页面标题」和「页面公告」，可以放心把链接发给客户的最终用户。

⑥ 想给不同客户更专业的地址：绑定正式对外域名后（例如 portal.bdx3d.top），所有客户共用这一个入口、靠 /w/账号名 区分——新客户零配置，不用逐条加解析和证书；个别大客户要更独立的地址，也能再单独给他绑一个子域名，后台代码不用改。