跳到主要内容

Cloud API

这个页面说明官网当前公开给自动化客户端和集成方的 Cloud API 发现入口。

当前策略是只公开真实存在且已有文档支撑的接口子集，不把后台私有能力、未稳定能力或不存在的 OAuth / MCP 发现文件包装成已上线能力。

发现入口​

  • API catalog：https://qiugeapp.zhangqiu.pro/.well-known/api-catalog
  • OpenAPI：https://qiugeapp.zhangqiu.pro/.well-known/qiuge-cloud-api.openapi.json
  • Health endpoint：https://qiugeapi.zhangqiu.pro/api/cloud/health

当前认证模型​

当前 Cloud API 使用平台账号邮箱密码登录，再返回 bearer token 供后续请求使用。

这意味着：

  • 已发布 bearer token 认证接口说明
  • 未发布 /.well-known/openid-configuration
  • 未发布 /.well-known/oauth-authorization-server
  • 未发布 /.well-known/oauth-protected-resource

原因很直接：当前线上实现还不是标准 OAuth / OIDC 授权服务器。

已文档化的公开子集​

Public​

  • GET /api/cloud/health
  • POST /api/cloud/auth/register-code/request
  • POST /api/cloud/auth/register
  • POST /api/cloud/auth/login

Authenticated​

  • POST /api/cloud/auth/refresh
  • GET /api/cloud/me
  • PATCH /api/cloud/me
  • GET /api/cloud/subscription/plans
  • GET /api/cloud/quota
  • POST /api/cloud/ai/credential-leases
  • POST /api/cloud/ai/usage-reports

使用边界​

  • /api/cloud/admin/* 属于后台运维接口，不在官网公开发现范围内
  • Cloud API 文档页描述的是稳定公开子集，不等于完整内部接口总表
  • 自动化客户端应优先读取 API catalog，再按 service-desc 和 service-doc 继续发现

响应格式​

OpenAPI 文件当前使用 JSON 发布，面向机器读取。文档页则保留中文说明和上下文边界，便于人和 agent 同时理解。

相关链接​