WaiNao.AI

主题

跨区互通 API（Team↔Team 绑定） ​

平台签约（管理员）后，团队管理员把本团队与对等区域平台的付款团队绑定， 绑定后本团队全员可在工作流中使用对方区域的模型（id 形如 peer-overseas:gpt-5）， 费用由对方付款团队按其余额结算。

P2 起绑定单位是 Team（P1 的 /my/peer-bindings 个人绑定已移除，未曾上线）。

权威端点索引 ​

本节列出跨区签约与绑定链路的完整端点；后续章节提供请求流程和字段细节。

GET /teams/peer-bindings/callback ​

公开 OAuth 回调。校验 state 与 code 后，重定向到团队设置页继续选择付款 Team。

GET /peer/catalog ​

使用 Authorization: Bearer <contract_secret> 获取对等区开放模型目录；只有启用中的签约可调用。

GET /peer/my-payable-teams ​

使用具备 peer:binding scope 的 OAuth token，列出当前用户可管理且可用于付款的 Team 与余额可用状态。

POST /peer/team-keys ​

为消费方 Team 幂等签发付款 Team 的网关 API Key。调用用户必须是付款 Team owner/admin，明文 Key 只返回一次。

POST /peer/contracts/revoke-consumer ​

使用签约 Secret 按消费区域或消费 Team 批量吊销付款授权；重复调用返回 already_revoked。

GET /admin/peer-contracts ​

站点管理员列出平台签约，响应不包含 Secret 明文。

POST /admin/peer-contracts ​

录入平台签约并立即调用对方目录接口验证。

PATCH /admin/peer-contracts/:id ​

更新名称、端点或 Secret 等签约配置，并重新验证可用性。

POST /admin/peer-contracts/:id/sync ​

手动同步该签约的远端模型目录。

POST /admin/peer-contracts/:id/suspend ​

暂停可恢复的签约，并级联撤销现有团队绑定。

POST /admin/peer-contracts/:id/revoke ​

终态断约，并级联吊销团队绑定及付款授权。

Team 绑定（消费方，/teams/:teamId/peer-bindings） ​

认证：用户会话（JWT）；绑定操作需团队 owner/admin。

获取绑定状态 ​

http
GET /teams/:teamId/peer-bindings

响应 200

json
{
  "success": true,
  "data": {
    "canManage": true,
    "regions": [
      {
        "region": "overseas",
        "regionName": "WaiNao Global",
        "binding": {
          "region": "overseas",
          "regionName": "WaiNao Global",
          "peerTeamId": "b7c3…",
          "peerTeamName": "Acme Global",
          "status": "active",
          "createdAt": "2026-07-11T12:00:00Z"
        }
      }
    ]
  }
}

binding.status：active 可用 / contract_revoked 平台断约 / key_invalid 凭据失效（需重绑）/ key_limited 对侧限额受限（对侧调限后自动恢复）。

发起绑定 ​

http
POST /teams/:teamId/peer-bindings/:region/start

返回对等区 authorizeUrl，前端整页跳转。用户在对方域名登录 + 授权后，对方 302 回本平台 GET /teams/peer-bindings/callback?code&state（公开回调，身份由一次性 state 携带，防重放）， 后端换取确权凭据并 302 回前端选择付款团队页。

响应 200：{ "success": true, "data": { "authorizeUrl": "https://…/oauth/authorize?…" } }

错误：contract_not_active 503 / not_team_admin 403

读取绑定会话（选择付款团队页） ​

http
GET /teams/:teamId/peer-bindings/session/:sessionId

仅发起人可读；会话 15 分钟有效。

响应 200

json
{
  "success": true,
  "data": {
    "region": "overseas",
    "regionName": "WaiNao Global",
    "payableTeams": [
      { "teamId": "b7c3…", "teamName": "Acme Global", "balanceAvailable": true }
    ]
  }
}

确认绑定（选定付款团队） ​

http
POST /teams/:teamId/peer-bindings/session/:sessionId/confirm
Content-Type: application/json

{ "payerTeamId": "b7c3…" }

后端调对等区签发 Team 级付款授权凭据（幂等 create-or-rotate）、加密落库、撤销确权 token。 任一步失败可用同一 session 重试（409 session_busy 表示另一次确认在处理中）。

响应 200：{ "success": true, "data": { "region": "overseas", "peerTeamName": "Acme Global" } }

解绑 ​

http
DELETE /teams/:teamId/peer-bindings/:region

本地绑定立即失效，并 best-effort 请求对等区吊销付款授权凭据。

对外付款授权（资源方，/teams/:teamId/peer-authorizations） ​

本团队作为付款团队对外授权的清单（哪个区域的哪个团队在用本团队余额）。 认证：用户会话 + 团队 owner/admin。

http
GET /teams/:teamId/peer-authorizations
DELETE /teams/:teamId/peer-authorizations/:keyId

撤销后对方团队下一次调用即失效（其绑定进入 key_invalid）。

平台端点（服务器对服务器，/peer/*） ​

由对等平台后端调用，普通用户与前端不接触。

端点鉴权说明
GET /peer/catalogAuthorization: Bearer <contract_secret>开放模型目录（签约 enabled 才放行）
GET /peer/my-payable-teamsOAuth token（scope peer:binding）确权人可付款团队列表 + 余额可用状态
POST /peer/team-keysOAuth token（scope peer:binding）幂等签发 Team 级付款授权凭据（明文仅返回一次）
POST /peer/contracts/revoke-consumerBearer contract_secret断约批量吊销（幂等 revoked / already_revoked；签约已禁用仍可收敛）

peer:binding scope 受 DB 签约 vendor-lock：仅 oauth_apps.peer_contract.enabled=true 的签约 App 可申请，路由面收敛为上表两个 OAuth 端点。

管理端点（site:admin） ​

A 侧签约管理（/admin/peer-contracts） ​

http
GET    /admin/peer-contracts               # 签约列表（不回 secret）
POST   /admin/peer-contracts               # 录入签约（即时调对方 /peer/catalog 验证）
PATCH  /admin/peer-contracts/:id           # 更新（换 secret / 改配置，重新验证）
POST   /admin/peer-contracts/:id/sync      # 手动目录同步
POST   /admin/peer-contracts/:id/suspend   # 暂停（可恢复）+ 级联撤销团队绑定
POST   /admin/peer-contracts/:id/revoke    # 终态断约 + 级联

B 侧签约配置（oauth-apps 子资源） ​

http
GET    /admin/oauth-apps/:id/peer-contract   # 读取（只标 has_secret）
PUT    /admin/oauth-apps/:id/peer-contract   # 配置 enabled/consumer_region；生成 contract_secret（明文仅一次）
DELETE /admin/oauth-apps/:id/peer-contract   # 移除签约（级联吊销付款授权）

禁用/删除签约或禁用/删除签约 App 都会级联吊销该消费方的全部付款授权凭据（fail-closed）。

运行时行为 ​

  • 模型列表：active 签约的目录模型全员可见（GET /api/models?teamId=<uuid> 时按该团队 绑定标记 availableForTeam；未绑定的模型选择器显示「需团队管理员绑定」态）。
  • 调用：workflow 所属 team 的绑定凭据（X-API-Key）直调对方模型网关，对方侧计费， 本侧不记账；P2 仅支持纯文本生成。
  • 对方返回码分级：401 → 绑定 key_invalid；403 限额 → key_limited（自动恢复）； 402 → 提示对方付款团队充值；其余透传。

AI Workflow Editor

Copyright 2024-present WaiNao.AI