BEEOS CLOUD / DEVELOPER REFERENCE

OpenAPI

下载 BeeOS Cloud Server API 的 OpenAPI 文档、完成鉴权，并生成客户端。

Server API 由一份 OpenAPI 3.1.0 文档描述：103 个操作、135 个 schema，文档版本 3.1.0（与 Cloud SDK 版本一致）。Cloud SDK 的方法页和 Cloud SDK 都由它生成。

下载规范

位置	地址
本站（静态文件）	`/openapi/server.openapi.json`
公共仓库	`beeos-ai/beeos-cloud-sdks` · `spec/server.openapi.json`

本站的副本就是 Cloud SDK 页面所用的那份。它省略了仅记录文档生成方式的扩展字段；所有操作、schema 以及 x-sdk-resource / x-sdk-method 名称保持不变。

服务器与鉴权

文档声明的服务器是 https://api.cloud.beeos.ai/v1。UHP 的 14 个操作声明了各自的服务器 https://api.cloud.beeos.ai/uhp/v1，它们的路径相对于该服务器；请确认你的生成器支持操作级别的 servers，否则需要为这些操作覆盖 base URL。

安全方案 ServerAPIKey：HTTP bearer 鉴权，使用服务端 API Key（前缀 bsk_），以 Authorization: Bearer <key> 发送，且只能从你的后端发出。

curl "https://api.cloud.beeos.ai/v1/instances" \
  -H "Authorization: Bearer $BEEOS_API_KEY"

每个操作上的 x-sdk-resource 与 x-sdk-method 给出它所属的 domain 和 SDK 方法名；x-sdk-base-path 标记 /uhp/v1 下的操作。其余的扩展字段 (x-enumDescriptions, x-idempotency, x-required-scopes, x-sdk-error-code-field, x-sdk-event-schema, x-sdk-response-stream, x-sdk-stream, x-variantSchemas, x-variants) 用于驱动 SDK 生成或补充标注，其他工具可以忽略。

生成客户端

从上方链接下载文档并保存为 server.openapi.json，再运行下面任一生成器。每条命令都会写入新的目录或文件；使用前请先检查生成结果。

npx @openapitools/openapi-generator-cli generate \
  -i server.openapi.json \
  -g typescript-fetch \
  -o ./beeos-client

openapi-generator 通过 -g 支持多种语言（例如 python、go）。openapi-typescript 只生成类型，调用 API 时请使用 fetch 或 openapi-fetch 之类的客户端。本文档是 OpenAPI 3.1：请使用 openapi-typescript 7 或更高版本，并在依赖 oapi-codegen 之前确认你的版本是否支持 3.1。

官方 SDK 还是自行生成

TypeScript、Python、Go 请优先使用官方 Cloud SDK。它们由同一份文档生成，并补上了通用生成器不了解的部分：自动切换 UHP 的 base path，组织和应用来自服务端 Key，错误统一为保留状态码和解码后错误体的同一种错误类型，另有手写 helper 覆盖流式 Responses 与 webhook 签名校验。

需要其他语言、不同的 HTTP 栈，或只需要类型时，再自行生成客户端。此时下面这些需要你自己处理：UHP 操作的 base URL，Authorization、Idempotency-Key、If-Match 头，server-sent events 流，以及 webhooks 的签名校验。

BeeOS Cloud返回文档首页