接入总览与接口清单
适用对象：FDE、客户模型/计量平台开发者。调用方向：QwenWork 服务端 → 客户接口。
本文统一提供 BYOK 接入入口。限额与统计SPI 的接口名称、字段、示例和验收要求以仓库现有BYOK限额和统计文档及当前代码为准；模型与搜索以《模型BYOK与搜索接口》的当前接入协议为准。示例均为合成数据，真实联调须替换组织、用户、实时周期与凭据。
阅读入口
| 文档 | 内容 |
|---|---|
| 本文 | 全部SPI接口列表、依赖和交付要求 |
| 限额与统计SPI 接入概览 | 仓库现有八个SPI接口总览与调用关系 |
| 快速开始 | 地址、认证、身份与配置 |
| 统计接口 | 日期、组织用量、成员用量与趋势 |
| 额度接口 | 规则与周期、成员额度、限额设置、组织额度 |
| 联调验收与排障 | 联调清单、错误与排障 |
| 模型BYOK与搜索接口 | Chat、图片、视频、音乐、ASR、搜索协议及流式/异步示例 |
全部SPI接口列表
模型模块必选，至少接通一个 Agent 主 Chat。专项模型和搜索按实际开放能力实现；限额与统计SPI 可选，启用时统一为“BYOK限额和统计”一组，八接口共用一个地址、Token 和开关。
模型与搜索
| 功能 | 方法 / 参考路径 | 要求与详细位置 |
|---|---|---|
| Chat、VL、文本润色 | POST 完整 Chat URL，例如 /v1/chat/completions | 主 Chat 必需；模型文档 §3 |
| 同步图片生成/编辑 | POST /api/v1/services/aigc/multimodal-generation/generation | 选用 Sync 时；模型 §5.2、§5.3 |
| 异步图片提交 | POST /api/v1/services/aigc/image-generation/generation | 选用 Async 时，配套实现图片/视频任务查询；模型 §5.2、§5.4 |
| 图片/视频任务查询 | GET 配置的 …/{task_id} 模板 | 异步图片提交、视频四模式提交的配套接口；模型 §4、§5.4、§6 |
| 视频四模式提交 | POST /api/v1/services/aigc/video-generation/video-synthesis | 按开放模式，配套实现图片/视频任务查询；模型 §6 |
| 同步音乐生成 | POST /api/v1/services/audio/music/generation | 选用音乐时，无额外任务查询；模型 §7 |
| Realtime ASR | WS/WSS /api-ws/v1/realtime?model=… | Base64音频/session事件；模型 §8.2 |
| Streaming ASR | WS/WSS /api-ws/v1/inference | 二进制音频/task事件；模型 §8.1 |
| 网页搜索 | POST 完整配置地址，参考 /search/unified | 选用时，网页搜索请求；模型 §9.1 |
| 图片搜索 | POST 完整配置地址，参考 /search/multimodal | 选用时，只传query；模型 §9.2 |
限额与统计SPI
以下入口复用仓库现有接口名称；完整协议和示例只在原文档维护。
| 接口名称 | Method 与路径 | 职责 | 调用时机 |
|---|---|---|---|
| 获取最新统计日期 | GET /spi/v1/usage/meta | 最新完整数据日期 | 统计刷新、手动连通性检测 |
| 查询组织用量概览 | GET /spi/v1/usage/overview | 组织历史用量 | 按日期和五个周期构建快照 |
| 查询成员用量列表 | GET /spi/v1/usage/members | 成员历史用量 | 构建快照，读取全部分页 |
| 查询成员每日用量趋势 | GET /spi/v1/usage/members/{external_user_id}/trend | 成员每日趋势 | 查看成员趋势时按需读取 |
| 查询额度规则与周期 | GET /spi/v1/quota/context | 额度约束与当前周期 | 校验额度、确定周期边界 |
| 查询成员额度 | POST /spi/v1/quota/users/query | 已应用的成员额度 | SDK 显式查询；当前产品不强制写后回读 |
| 设置成员限额 | PUT /spi/v1/quota/users | 设置单个成员的绝对限额 | 后台派发与重试额度变更 |
| 查询组织额度 | GET /spi/v1/quota/org | 实时组织总额度与已用量 | 查询组织额度 |
模型采用完整 Endpoint，参考路径可按选定协议允许范围自定义；限额与统计SPI 在 Base URL 后追加固定路径。模型能力可共用 URL，异步查询模板可共用，不意味着每家客户必须实现18个独立 URL。
不需要实现模型订阅查询、用户创建、部门聚合、CSV 导出、Console/IAM Internal API、配置发布或每次调用的记账回调。产品订阅继续由 License/IAM 提供。
对接流程与责任
- 确认组织、用户 ID 与计量口径，独立配置模型与搜索。
- 配置并启用 BYOK限额和统计；检测连通性仅调用“获取最新统计日期”。
- 查询额度规则与周期，设置成员限额并确认结果；查询组织额度供额度概览展示。
- 使用同一用户进行真实模型调用，验证客户限额执行。
- 客户固化统计数据后，获取最新统计日期，按五个周期查询组织用量概览和成员用量列表。
- 原统计任务校验数据并将快照发布到本地 PostgreSQL，页面、部门统计与导出读取快照。
- 成员详情按需调用“查询成员每日用量趋势”。
客户账本定义 credits，QwenWork 不从模型 usage 自动推导价格。QwenWork 将 IAM 内部用户 UUID 映射为企业第三方 ID；模型、额度与统计需使用同一 ID。客户依据可信凭据建立“组织 UUID → 客户账本租户”的授权绑定；模型请求不承诺携带限额与统计SPI 的组织 Header。
额度最终值和重试沿用原额度任务。设置成员限额应幂等、保留已用量，成功响应必须是实际生效结果；FDE 可调用查询成员额度验证。统计快照按 ds 发布，定时任务跳过已发布目标日期，手动任务可重建同日期；查询成员每日用量趋势按已发布日期查询。
当前配置与联调入口
- 配置：Console → 开放平台 → 扩展配置 → BYOK限额和统计。配置存入
spi_configurations，凭据加密；每个新请求/任务动态读取，同次操作固定版本。未配置/关闭时使用 K8S 空实现，启用后八接口走客户 SPI，其他静态扩展（包括 License）保持原路径。 - 地址：支持 HTTP/HTTPS、域名/IP、端口与路径前缀。HTTP 提示 Token 明文传输；HTTPS 正常校验证书，不提供自定义 CA 或跳过验证。配置、检测及实际调用共用校验，不跟随重定向。
- 检测连通性：只检测获取最新统计日期的 HTTP 200，最多 5 秒，不验证 JSON 或其他七接口，不保存或启用配置。
.svc由集群内 Biz 访问，浏览器无需能解析。 - 额度概览：
/api/console/biz/v1/quota-overview的组织总额度/已用量来自查询组织额度，规则数量及默认个人额度来自本地配置。关闭时提示 K8S 不支持，启用后按客户响应处理。 - 手动统计同步：登录态 POST
/api/console/biz/v1/analytics/usage/sync-runs，无按钮。新 ds 或同一 ds 都重新拉取五周期并发布，更早 ds 返回 unchanged；详见《统计接口》中的同步说明。
配置及调用行为以仓库现有限额与统计SPI 文档和当前代码为准；是否已部署到目标环境需以实际镜像为准。
FDE 交付登记与验收
| 项目 | 需要交付/确认 |
|---|---|
| 能力与版本 | 模型范围、是否启用本组、双方构建与本包版本 |
| 模型地址 | 模型 ID、完整 URL、协议、查询模板、认证与支持参数 |
| 普通地址 | 一组 Base URL/Token、授权组织 UUID 与客户租户；binding_id 由 QwenWork 请求提供 |
| 用户身份 | 第三方 ID 来源、实际 IAM 绑定、离职/换绑与跨组织隔离 |
| 计量周期 | credit 定义、价格、舍入、失败/取消收费、周期边界与永久额度 |
| 数据服务 | 完整 ds 就绪 SLA、五周期、稳定分页、趋势及保留期 |
| 网络容量 | Biz 可达、证书、超时、限流、素材和任务有效期 |
| 联调证据 | 八接口字段、设置成员限额幂等及真实限额、组织额度查询、统计发布/重复触发、动态切换 |
验收顺序：认证与网络 → 八接口字段 → 配置启停 → 同用户额度/模型/统计闭环 → 故障重试及跨期 → 客户环境验收。模型限额执行需验证受限调用的身份及客户账本，不能仅凭“检测连通性”成功判定完成。密钥单独通过安全渠道交付。
模型与搜索文档以客户服务接入协议说明请求、响应、异步任务与错误处理；限额与统计SPI 的后续变化以仓库现有章节和代码为准，不在本目录另建重复版本。
静态文档校验不替代客户网络、实际额度写入、模型效果或部署验收。