接入文档

把你的产品接入 AI Relay：选档位、写清单、实现 POST /relay、过接入验收。

L0：从 OpenAPI 导入（零代码）

你已经有一套 REST 接口和 OpenAPI 文档时，可以不写任何代码：在后台导入文档，勾选要开放的接口，Relay 的托管适配器替你实现 POST /relay，把 AI 的调用转成对你接口的 HTTP 请求。1–2 小时能上线。

适合：动作都能当场给结果（同步），请求和响应都是 JSON。不适合：要异步、多方案或账号绑定的产品，这些请用 L1 或 L2 自己实现端点。

步骤

  1. 在供给方后台打开「从 OpenAPI 导入」，粘贴 OpenAPI 3.0 或 3.1 文档（JSON 或 YAML）。
  2. 列表里勾选要开放的操作，按需改动作名、风险和手续费。不能开放的操作会标出原因。
  3. 填接口根地址（比如 https://api.example.com/v1）和鉴权凭据。凭据可以放在请求头（比如 Authorization: Bearer …）或查询参数里，最多 10 条，加密保存，后台不再显示明文。
  4. 生成清单草稿。它和手写的清单一样：可以在编辑器里改描述、元数据和样例输入，然后在线验收、提交审核（见接入总览）。

清单的端点会自动设成 Relay 的托管适配器 https://relay.newbeeai.online/v1/l0/<你的 supplier_id>，不用你部署任何东西。

文档怎么变成动作

  • 每个操作一个动作。路径参数、查询参数、请求头参数和 JSON 请求体的字段摊平成动作的 input；请求体字段和参数重名时，整个请求体放在 body 字段里。
  • 成功响应的 Schema 变成 output；响应不是对象时包在 result 字段里。
  • 只认文档内的 $ref，循环引用放宽成 {}。3.0 的 nullable、布尔 exclusiveMinimum、example 会转写成 2020-12 的写法。readOnly 字段不进 input。
  • $ref 展开后的 Schema 合计不超过 96 KB，超出的部分放宽成 {} 并提示；整份清单（手写的也一样）不超过 128 KB。YAML 里指向自身的别名（&a … *a）不支持，请改用 $ref。
  • 文档嵌套不超过 128 层。YAML 另有几条限制：分词后不超过 30 万个记号（空白、换行也算；带说明文字的文档 1 MB 以内一般都在这以下，几乎不写说明、全是短字段的文档接近 1 MB 时可能超过），别名（*名字）不超过 1 万个，一行里连着写的 -、?、:、标签、锚点不超过 16 个，连着的空行不超过 100 行（块文字里面的不算），键不能是列表或对象。超出的请转成不带缩进的 JSON 再导入，共用的部分改用 $ref。
  • YAML 按 1.2 的核心规则读：<< 合并键不展开（就是一个名叫 << 的键），!!binary、!!timestamp、!!set、!!omap、!!pairs 这些 YAML 1.1 的标签不认，按普通的字符串、对象、列表读。PyYAML、yq 这类按 YAML 1.1 写文件的工具不给 08、0108、02139 这种以 0 开头的数字串和 6e81993 这种写法加引号，按 1.2 会读成数（6e81993 溢出成无穷大）；这类值请加引号，或者用同一个工具先转成 JSON 再导入。.inf、.nan 和超出范围的数 JSON 写不出来，导入时直接报错。
  • summary、description 变成动作的标题和说明，这是 AI 选动作的依据，导入后值得在编辑器里改得具体一些。
  • 不能开放：表单或文件上传的请求体、必填的 cookie 参数、标了 deprecated 的操作、参数超过 100 个或参数名超过 128 个字符的操作。一份文档最多列 1000 个操作，多了请删掉用不到的路径再导入。
  • 样例输入从文档的 example、default、enum 里凑；凑不齐的动作会提示你到编辑器补上，否则在线验收会是「未测」。所有动作的样例输入合计不超过 128 KB，示例值太大的动作同样提示你去编辑器补。

默认元数据（都可以改）：

方法 风险 确认 手续费
GET 低，只读 不确认 按平台的查询单价按次收（目前不收），导入时不用填
POST、PUT、PATCH 中 按用户授权 ¥1
DELETE 高 每次确认 ¥1

用户金额 amount 默认是 "none"。下单类接口有金额字段的话，到编辑器里改成 {"from": "input.<字段>"}，见计费与结算。

你的接口会收到什么

  • 按导入的映射拼出的请求，带上你配的凭据和这几个请求头：Idempotency-Key: <订单号>、X-Relay-Order-Id: <订单号>、User-Agent: AI-Relay-L0/1.0。
  • 超时 50 秒，不跟随跳转，只访问公网 HTTPS 地址。

响应怎么翻译：

你的接口返回 AI 看到
2xx 完成，响应体作为 data
400、422 invalid_input
401、403 permanent（请检查凭据）
404、409、410 not_available
429 rate_limited
5xx、408、超时：GET temporary，可以重试
5xx、408、超时：写操作 结果未知：不扣费，订单进「待核对」，管理员核对后可能用同一个 Idempotency-Key 重新调一次

在线验收时，样例输入调你的接口回 401、403 直接判不通过（其他失败只记警告）：这说明导入时填的凭据不对，上线后每一单都会失败。改好凭据重新导入，再跑一次验收。

写操作的接口请按 Idempotency-Key 去重：同一个键再来时返回第一次的结果，不要再办一次。适配器自己也按订单号记下了最终结果，重放不会再调你的接口；但结果未知的那一笔，后台核对时会重新调用。

之后改动

  • 每个清单版本有自己的根地址和凭据。导入新草稿换地址或凭据，不影响已上线的版本。
  • 在线验收通过后又重新导入、换了根地址、凭据或接口映射：之前的验收结果作废，要再跑一次验收才能提交审核。什么都没变的重新导入不影响验收结果。
  • 只改描述或元数据：在编辑器里另存新版本就行，沿用最近一次导入的映射。改动作名要重新导入。