BEEOS CLOUD / DEVELOPER REFERENCE

实例

创建、读取、更新、启停、升级与删除实例；打开终端与画布会话；执行命令；获取连接与流地址。

概览

instances domain 管理你的产品所运行的实例：列出、创建、读取、更新、启动、停止、升级和删除。它还可以打开终端和画布会话、在实例里执行命令，并返回连接地址和流地址。

15 个操作 · SDK 资源：TypeScript cloud.instances · Python cloud.instances · Go cloud.Instances · API 总览

主要对象

CreateServerInstanceInput：创建实例的请求。
RuntimeInstanceResult：创建、读取、启动、停止、删除返回的实例；InstancePage 列出 InstanceSummary 条目。
RuntimeInstanceStatusResult：实例状态。
RuntimeUpgradeJob：升级任务的状态。
TerminalSessionDocument、CanvasSessionDocument、RuntimeExecResult、ConnectURLResponse：会话、命令和 URL 操作的结果。

CreateServerInstanceInput

字段	类型	必填	说明
`name`	`string`	是	实例的显示名称，1 到 128 字节，首尾不能有空白。
`variant_id`	`string`	否	用于创建实例的目录 variant 的 ID，最多 128 个字符。可用的 variant 见实例模板目录。未知 ID 返回 404 `variant_not_found`。
`harness`	`string`	否	在实例中运行的 harness。只接受 `openclaw`。可选值: `"openclaw"` — OpenClaw 智能体运行时.
`llm`	RuntimeLLM	否	实例使用的模型 provider 和模型。当 variant 或 harness 需要调用方提供模型时必填；自带模型的 variant 请省略。Provider API key 为只写。可为 null。

完整字段和使用该对象的方法见附录。

RuntimeInstanceResult

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	本次响应时的实例。
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

完整字段和使用该对象的方法见附录。

InstancePage

字段	类型	必填	说明
`data`	array<InstanceSummary>	是	本页的实例，最新的在前。
`total`	`integer`	是	符合筛选条件的实例总数，跨所有页。

完整字段和使用该对象的方法见附录。

InstanceSummary

字段	类型	必填	说明
`has_ever_run`	`boolean`	是	实例是否曾到达过 running 状态。false 表示它从未提供过运行中的服务。
`id`	`string`	是	实例的唯一 ID。
`organization_id`	`string`	是	拥有该实例的组织的 ID。
`app_id`	`string`	是	实例所属应用的 ID。
`developer_id`	`string`	是	创建该实例所用的开发者账号的 ID。
`name`	`string`	是	实例的显示名称。
`harness`	`string`	是	产品 harness 名称（例如 `openclaw`），不是 UHP 的 `harness_id`（`chrn_*`）。
`provider_id`	`string`	是	托管该实例的 provider 的 ID。
`region`	`string`	是	实例部署所在的区域。
`os_type`	`string`	是	实例的操作系统：`linux`、`windows`、`android` 或 `macos`。
`status`	`string`	是	实例的生命周期阶段：`pending`、`provisioning`、`running`、`stopped` 或 `terminated`。取值见下表 InstanceSummary.status 取值。
`desired_status`	`string`	是	实例正被驱动朝向的生命周期阶段：`running`、`stopped` 或 `terminated`。可选值: `"running"` — 实例应处于运行状态; `"stopped"` — 实例应处于停止状态; `"terminated"` — 实例应被删除. (枚举表)
`connectivity`	`string`	是	实例中 agent 的可达性：`unknown`、`online` 或 `offline`。可选值: `"unknown"` — 尚未确定可达性; `"online"` — 该实例的智能体已连接; `"offline"` — 该实例的智能体未连接. (枚举表)
`ms_connection_status`	`string`	是	实例消息通道连接的状态：`unknown`、`connecting`、`connected`、`reconnecting`、`disconnected` 或 `failed`。它独立于 connectivity 上报；实例处于停止或已终止状态、或最近没有上报时为 `unknown`。
`created_at`	`string`	是	实例的创建时间，RFC 3339 UTC 时间戳。
`updated_at`	`string`	是	实例的最后更新时间，RFC 3339 UTC 时间戳。
`resource_version`	`integer`	是	实例记录的版本，从 1 开始。请在写请求的 `If-Match` 头中发送它，以便检测并发修改。约束: `minimum=1`, `format=int64`.
`image_slot`	`string`	否	Variant 特性。为实例选择执行镜像的键。不是容器仓库名称。
`worker_image_id`	`string`	否	Variant 特性。AgentBay worker 镜像。绝不是平台的 `image_id`。
`model_catalog`	`string`	否	Variant 特性。Cloud 响应模型列表和 reasoning 级别请求时为 `served`，两者都不响应时为 `none`。空值和未知值按 `none` 处理。
`billing_slot`	`string`	否	Variant 特性。为该实例定价的月费表的键。
`icon_key`	`string`	否	Variant 特性。UI 图标选择器。客户端不得从 `harness` 推导它。
`device_control`	`boolean`	否	Variant 特性。实例是否接受设备控制命令。false 表示这些命令会被拒绝。
`runtime_profile`	`string`	否	Variant 特性。实例所使用的 agent 运行时的 profile。已知值为 `openclaw`、`hermes` 和 `beeos-browser`。
`free_plan`	`boolean`	否	Variant 特性。免费套餐是否允许该实例的 variant。false 表示免费套餐不允许。
`cloud_provider`	`string`	否	`agentbay`、`beeos`，自托管时为空。

InstanceSummary.status 取值

取值	含义
`"pending"`	实例已创建，正在等待预配。
`"provisioning"`	实例正在预配或启动。
`"running"`	实例正在运行。
`"stopped"`	实例已停止，可以再次启动。
`"terminated"`	实例已删除，不能再使用。

完整字段和使用该对象的方法见附录。

RuntimeInstanceStatusResult

字段	类型	必填	说明
`data`	`object`	是	实例的当前状态。
`data.id`	`string`	是	实例的唯一 ID。
`data.name`	`string`	是	实例的显示名称。
`data.status`	`string`	是	实例的生命周期阶段：`pending`、`provisioning`、`running`、`stopped` 或 `terminated`。取值见下表 RuntimeInstanceStatusResult.data.status 取值。
`data.desired_status`	`string`	是	实例正被驱动朝向的生命周期阶段：`running`、`stopped` 或 `terminated`。可选值: `"running"` — 实例应处于运行状态; `"stopped"` — 实例应处于停止状态; `"terminated"` — 实例应被删除. (枚举表)
`data.connectivity`	`string`	是	实例中 agent 的可达性：`unknown`、`online` 或 `offline`。可选值: `"unknown"` — 尚未确定可达性; `"online"` — 该实例的智能体已连接; `"offline"` — 该实例的智能体未连接. (枚举表)
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

RuntimeInstanceStatusResult.data.status 取值

取值	含义
`"pending"`	实例已创建，正在等待预配。
`"provisioning"`	实例正在预配或启动。
`"running"`	实例正在运行。
`"stopped"`	实例已停止，可以再次启动。
`"terminated"`	实例已删除，不能再使用。

完整字段和使用该对象的方法见附录。

RuntimeUpgradeJob

字段	类型	必填	说明
`job_id`	`string`	是	升级任务的唯一 ID。
`image_version_id`	`string`	否	—
`instance_id`	`string`	是	正在升级的实例的 ID。
`status`	`string`	是	任务的状态：`upgrade_pending`、`rollback_pending`、`failed` 或 `succeeded`。可选值: `"upgrade_pending"` — 正在应用镜像升级; `"rollback_pending"` — 镜像升级失败，实例正在回滚到之前的镜像; `"failed"` — 镜像升级失败。见 `error`; `"succeeded"` — 镜像升级已完成，实例运行目标版本. (枚举表)
`target`	`string`	是	实例正在升级到的镜像版本。
`created_at`	`string`	是	任务的创建时间，RFC 3339 UTC 时间戳。
`completed_at`	`string`	否	任务结束的时间，RFC 3339 UTC 时间戳。任务未结束时省略。可为 null。
`error`	`string`	否	稳定的失败码。只有任务失败时才出现。可为 null。

完整字段和使用该对象的方法见附录。

TerminalSessionDocument

字段	类型	必填	说明
`transport`	`string`	是	ticket 的连接方式：始终为 `service-websocket`。
`protocolVersion`	`integer`	是	ticket 协议的版本。目前为 1。
`header`	RealtimeTicketHeader	是	已签名 ticket 的 header。
`websocketUrl`	`string`	是	用于建立终端连接的 WebSocket URL。ticket 已作为查询参数包含在内。
`ticket`	`string`	是	已签名的一次性 ticket（JWT），授权一次终端连接。有效期为 60 秒。
`issuedAt`	`string`	是	ticket 的签发时间，RFC 3339 时间戳。约束: `format=date-time`.
`expiresAt`	`string`	是	ticket 的过期时间，RFC 3339 时间戳。ticket 的有效期为 60 秒。约束: `format=date-time`.
`claims`	TerminalTicketClaims	是	已签名 ticket 中包含的 claims。

完整字段和使用该对象的方法见附录。

CanvasSessionDocument

字段	类型	必填	说明
`transport`	`string`	是	ticket 的连接方式：始终为 `relay`。
`protocolVersion`	`integer`	是	ticket 协议的版本。目前为 1。
`header`	RealtimeTicketHeader	是	已签名 ticket 的 header。
`relayUrl`	`string`	是	该画布的画布中继 WebSocket URL，以 `/ws/{canvasId}` 结尾。
`ticket`	`string`	是	已签名的一次性 ticket（JWT），授权一次中继连接。有效期为 60 秒。
`issuedAt`	`string`	是	ticket 的签发时间，RFC 3339 时间戳。约束: `format=date-time`.
`expiresAt`	`string`	是	ticket 的过期时间，RFC 3339 时间戳。ticket 的有效期为 60 秒。约束: `format=date-time`.
`claims`	CanvasTicketClaims	是	已签名 ticket 中包含的 claims。

完整字段和使用该对象的方法见附录。

RuntimeExecResult

字段	类型	必填	说明
`exit_code`	`integer`	是	命令的退出码。
`stdout`	`string`	是	命令的标准输出，最多 64 KiB。
`stderr`	`string`	是	命令的标准错误，最多 64 KiB。
`truncated`	`boolean`	是	输出是否被截断。

完整字段和使用该对象的方法见附录。

ConnectURLResponse

字段	类型	必填	说明
`data`	`object`	是	所请求服务的连接详情。
`data.url`	`string`	是	要连接的 URL。`browser` 时是浏览器查看端 URL；`acp` 时是一个 WebSocket URL，访问 ticket 已作为查询参数包含在内。
`data.mode`	`string`	是	连接模式：`browser` 对应 `browser-runtime`，`acp` 对应 `service-websocket`。可选值: `"browser-runtime"` — 浏览器查看会话；使用 `url` 和 `token` 连接; `"service-websocket"` — 到智能体服务的 WebSocket 连接；`url` 已带有访问 ticket. (枚举表)
`data.token`	`string`	是	浏览器查看端使用的短期访问 token。`acp` 不返回。
`data.service`	`string`	是	该 URL 所连接的服务：`browser` 或 `acp`。可选值: `"browser"` — 浏览器查看器; `"acp"` — 通过 WebSocket 连接智能体. (枚举表)
`data.connectivity`	`string`	是	实例中 agent 的可达性：`unknown`、`online` 或 `offline`。可选值: `"unknown"` — 尚未确定可达性; `"online"` — 该实例的智能体已连接; `"offline"` — 该实例的智能体未连接. (枚举表)
`data.stream_session_id`	`string`	是	查看端 client session 的 ID，即请求中发送的 `client_id`。`acp` 不返回。
`data.browser`	`object`	否	浏览器访问授权。仅在 `browser` 时返回。
`data.browser.grant_id`	`string`	是	浏览器访问授权的 ID。
`data.browser.generation`	`string`	是	该授权所绑定的浏览器 generation。如果请求中发送了 `generation`，则与该值相同。
`data.browser.expires_at`	`string`	是	访问授权过期的时间，Unix 毫秒。
`data.browser.role`	`string`	是	该授权的访问角色：`viewer` 或 `controller`。可选值: `"viewer"` — 可以查看浏览器，但不能控制; `"controller"` — 可以查看并控制浏览器. (枚举表)

完整字段和使用该对象的方法见附录。

RuntimeInstanceSummary

字段	类型	必填	说明
`id`	`string`	是	实例的唯一 ID。
`organization_id`	`string`	是	拥有该实例的组织的 ID。
`app_id`	`string`	是	实例所属应用的 ID。
`developer_id`	`string`	是	创建该实例所用的开发者账号的 ID。
`name`	`string`	是	实例的显示名称。
`harness`	`string`	是	产品 harness 名称（例如 `openclaw`），不是 UHP 的 `harness_id`（`chrn_*`）。
`provider_id`	`string`	是	托管该实例的 provider 的 ID。
`region`	`string`	是	实例部署所在的区域。
`os_type`	`string`	是	实例的操作系统：`linux`、`windows`、`android` 或 `macos`。
`status`	`string`	是	实例的生命周期阶段：`pending`、`provisioning`、`running`、`stopped` 或 `terminated`。取值见下表 RuntimeInstanceSummary.status 取值。
`desired_status`	`string`	是	实例正被驱动朝向的生命周期阶段：`running`、`stopped` 或 `terminated`。可选值: `"running"` — 实例应处于运行状态; `"stopped"` — 实例应处于停止状态; `"terminated"` — 实例应被删除. (枚举表)
`connectivity`	`string`	是	实例中 agent 的可达性：`unknown`、`online` 或 `offline`。可选值: `"unknown"` — 尚未确定可达性; `"online"` — 该实例的智能体已连接; `"offline"` — 该实例的智能体未连接. (枚举表)
`error_code`	`string`	否	稳定的代码，描述随生命周期结果一起上报的失败或降级状态，例如 `quota_exceeded`、`capacity_pending`、`provision_failed` 或 `stop_failed`。原始的 provider 错误绝不会导出。
`ms_connection_status`	`string`	是	实例消息通道连接的状态：`unknown`、`connecting`、`connected`、`reconnecting`、`disconnected` 或 `failed`。它独立于 connectivity 上报；实例处于停止或已终止状态、或最近没有上报时为 `unknown`。
`image_id`	`string`	否	实例所运行的平台镜像的 ID。
`image_version_id`	`string`	否	实例所运行的平台镜像版本的 ID。
`image_version`	`string`	否	实例所运行的平台镜像的版本标签。
`image_ref`	`string`	否	固定的公开镜像引用。从不包含 provider 配置。
`model_primary`	`string`	否	为实例配置的主模型。
`models`	`array<string>`	否	为实例配置的模型。
`llm`	RuntimeLLMView	否	为实例提供的模型 provider 和模型，已移除 API key。可为 null。
`hosting_type`	`string`	否	实例的托管位置：`cloud` 或 `selfhosted`。
`cloud_provider`	`string`	否	`agentbay`、`beeos`，自托管时为空。
`image_slot`	`string`	否	Variant 特性。为实例选择执行镜像的键。不是容器仓库名称。
`worker_image_id`	`string`	否	Variant 特性。AgentBay worker 镜像。绝不是平台的 `image_id`。
`model_catalog`	`string`	否	Variant 特性。Cloud 响应模型列表和 reasoning 级别请求时为 `served`，两者都不响应时为 `none`。空值和未知值按 `none` 处理。
`billing_slot`	`string`	否	Variant 特性。为该实例定价的月费表的键。
`icon_key`	`string`	否	Variant 特性。UI 图标选择器。客户端不得从 `harness` 推导它。
`device_control`	`boolean`	是	Variant 特性。实例是否接受设备控制命令。false 表示这些命令会被拒绝。
`runtime_profile`	`string`	否	Variant 特性。实例所使用的 agent 运行时的 profile。已知值为 `openclaw`、`hermes` 和 `beeos-browser`。
`free_plan`	`boolean`	是	Variant 特性。免费套餐是否允许该实例的 variant。false 表示免费套餐不允许。
`resource_version`	`integer`	是	实例记录的版本，从 1 开始。请在写请求的 `If-Match` 头中发送它，以便检测并发修改。
`has_ever_run`	`boolean`	是	实例是否曾到达过 running 状态。false 表示它从未提供过运行中的服务。
`created_at`	`string`	是	实例的创建时间，RFC 3339 UTC 时间戳。
`updated_at`	`string`	是	实例的最后更新时间，RFC 3339 UTC 时间戳。
`capabilities`	`object`	是	实例在预配时声明的能力，以 `computer`、`mobile`、`device` 和 `terminal` 等标志表示。空对象表示没有声明任何能力。
`capabilities.computer`	`boolean`	否	—
`capabilities.mobile`	`boolean`	否	—
`capabilities.device`	`boolean`	否	—
`capabilities.terminal`	`boolean`	否	—

RuntimeInstanceSummary.status 取值

取值	含义
`"pending"`	实例已创建，正在等待预配。
`"provisioning"`	实例正在预配或启动。
`"running"`	实例正在运行。
`"stopped"`	实例已停止，可以再次启动。
`"terminated"`	实例已删除，不能再使用。

完整字段和使用该对象的方法见附录。

RuntimeOperationSummary

字段	类型	必填	说明
`id`	`string`	是	操作的唯一 ID。
`kind`	`string`	是	操作的种类：`create`、`start`、`stop`、`delete` 或 `image_upgrade`。取值见下表 RuntimeOperationSummary.kind 取值。
`phase`	`string`	是	操作的阶段：`intent`、`reserved`、`admitted`、`provisioning`、`running`、`cleanup_pending`、`failed`、`stop_pending`、`stopped`、`delete_pending`、`deleted`、`upgrade_pending` 或 `rollback_pending`。它描述持久化的工作，而不是观测到的实例健康状况。取值见下表 RuntimeOperationSummary.phase 取值。
`error_code`	`string`	否	稳定的失败码，与实例的 `error_code` 取值相同。原始的 provider 错误绝不会导出。

RuntimeOperationSummary.kind 取值

取值	含义
`"create"`	创建实例。
`"start"`	启动已停止的实例。
`"stop"`	停止实例。
`"delete"`	删除实例。
`"image_upgrade"`	把实例升级到另一个平台镜像。

RuntimeOperationSummary.phase 取值

取值	含义
`"intent"`	创建请求已记录，尚未预留任何资源。
`"reserved"`	创建请求已被接受，其资源已预留。
`"admitted"`	创建请求已被受理，正在等待预配。
`"provisioning"`	实例正在预配或启动。
`"running"`	创建、启动或镜像升级成功的最终阶段。
`"cleanup_pending"`	创建失败，它所预留的资源正在清理。
`"failed"`	操作失败的最终阶段。见 `error_code`。
`"stop_pending"`	实例正在停止。
`"stopped"`	停止成功的最终阶段。
`"delete_pending"`	实例正在被删除。
`"deleted"`	删除成功的最终阶段。
`"upgrade_pending"`	正在应用镜像升级。
`"rollback_pending"`	镜像升级失败，实例正在回滚到之前的镜像。

完整字段和使用该对象的方法见附录。

RealtimeTicketHeader

字段	类型	必填	说明
`alg`	`string`	是	ticket 的签名算法：`RS256`。
`typ`	`string`	是	Token 类型：`JWT`。
`kid`	`string`	是	签署该 ticket 的密钥的 ID。

完整字段和使用该对象的方法见附录。

TerminalTicketClaims

字段	类型	必填	说明
`iss`	`string`	是	ticket 的签发者。
`aud`	`string`	是	ticket 的目标受众：终端服务。
`sub`	`string`	是	未使用。Cloud 不接受外部用户 ID，因此该声明为空。
`jti`	`string`	是	ticket 的唯一 ID。
`instance_id`	`string`	是	该终端所属实例的 ID。
`platform_agent_id`	`string`	是	该终端会话所针对的 agent 的 ID，即请求中的 `platformAgentId`。
`client_id`	`string`	是	为这次终端客户端连接生成的 ID。
`conversation_id`	`string`	否	该终端所附着的会话的 ID。仅当请求发送了 `conversationId` 时才出现。
`resume_terminal_id`	`string`	否	要恢复的终端的 ID。仅当请求发送了 `resumeTerminalId` 时才出现。
`iat`	`integer`	是	ticket 的签发时间，Unix 秒。
`exp`	`integer`	是	ticket 的过期时间，Unix 秒。

完整字段和使用该对象的方法见附录。

CanvasTicketClaims

字段	类型	必填	说明
`iss`	`string`	是	ticket 的签发者。
`sub`	`string`	是	未使用。Cloud 不接受外部用户 ID，因此该声明为空。
`jti`	`string`	是	ticket 的唯一 ID。
`purpose`	`string`	是	ticket 的用途：始终为 `canvas_session`。
`instance_id`	`string`	是	该画布所属实例的 ID。
`platform_agent_id`	`string`	是	该画布会话所针对的 agent 的 ID，即请求中的 `platformAgentId`。
`client_id`	`string`	是	为这次中继客户端连接生成的 ID。
`conversation_id`	`string`	是	该画布所属会话的 ID，即请求中的 `conversationId`。
`canvas_id`	`string`	是	ticket 授予访问权限的画布的 ID。
`role`	`string`	是	在该画布上授予的访问角色：`viewer` 或 `editor`。可选值: `"viewer"` — 可以查看画布，但不能修改; `"editor"` — 可以查看和编辑画布. (枚举表)
`session_id`	`string`	是	为该 ticket 创建的实时会话的 ID。
`aud`	`array<string>`	是	ticket 的目标受众：画布中继。
`iat`	`integer`	是	ticket 的签发时间，Unix 秒。
`exp`	`integer`	是	ticket 的过期时间，Unix 秒。

完整字段和使用该对象的方法见附录。

典型流程

用 instances.create 创建实例。响应是 202：创建已开始，实例尚未就绪。
轮询 instances.getStatus，直到实例运行。
使用实例：instances.exec 执行命令，instances.createTerminalSession 与 instances.createCanvasSession 打开会话，instances.getConnectURL 与 instances.getStreamURL 返回地址。
用 instances.update 修改（在 If-Match 里传当前版本），用 instances.stop 与 instances.start 停止和启动，或用 instances.upgrade 升级并用 instances.getUpgrade 跟踪任务。
用 instances.delete 删除。

方法

方法	HTTP	摘要
instances.list	`GET /v1/instances`	列出实例
instances.create	`POST /v1/instances`	创建实例
instances.get	`GET /v1/instances/{instanceId}`	获取实例
instances.update	`PATCH /v1/instances/{instanceId}`	更新实例
instances.delete	`DELETE /v1/instances/{instanceId}`	删除实例
instances.createCanvasSession	`POST /v1/instances/{instanceId}/canvas-sessions`	创建画布会话
instances.getConnectURL	`GET /v1/instances/{instanceId}/connect-url`	获取实例连接 URL
instances.exec	`POST /v1/instances/{instanceId}/exec`	在实例中运行命令
instances.start	`POST /v1/instances/{instanceId}/start`	启动实例
instances.getStatus	`GET /v1/instances/{instanceId}/status`	获取实例状态
instances.stop	`POST /v1/instances/{instanceId}/stop`	停止实例
instances.getStreamURL	`GET /v1/instances/{instanceId}/stream-url`	获取实例流 URL
instances.createTerminalSession	`POST /v1/instances/{instanceId}/terminal-sessions`	创建终端会话
instances.upgrade	`POST /v1/instances/{instanceId}/upgrade`	开始一次实例升级
instances.getUpgrade	`GET /v1/instances/{instanceId}/upgrades/{jobId}`	获取一次实例升级

instances.list

GET /v1/instances · Operation ID listInstances

列出实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.list`	`list(query?: Models.ListInstancesQuery): Promise<Models.ListInstancesResponse>`
Python	`cloud.instances.list`	`def list(self, options: ListInstancesOptions \| None = None) -> InstancePage`
Go	`cloud.Instances.List`	`func (r *InstancesResource) List(ctx context.Context, options ListInstancesOptions) (InstancePage, error)`

参数

参数	位置	类型	必填	说明
`page`	query	`integer`	否	从 1 开始的页码，取值 1 到 1000000。默认为 1。约束: `minimum=1`, `maximum=1000000`.
`page_size`	query	`integer`	否	每页的实例数，取值 1 到 100。默认为 20。约束: `minimum=1`, `maximum=100`.
`status`	query	`string`	否	只返回处于该生命周期阶段的实例：`pending`、`provisioning`、`running`、`stopped` 或 `terminated`。省略时不返回已终止的实例。
`provider_id`	query	`string`	否	只返回由该 provider 托管的实例，最多 128 个字符。
`harness`	query	`string`	否	只返回运行该产品 harness（例如 `openclaw`）的实例，最多 128 个字符。
`cluster_id`	query	`string`	否	只返回部署在该集群上的实例，最多 128 个字符。
`search`	query	`string`	否	对实例名称或 ID 做不区分大小写的子串匹配，最多 200 个字符。

响应

200 限定于租户的结果 · application/json · Schema: InstancePage

字段	类型	必填	说明
`data`	array<InstanceSummary>	是	本页的实例，最新的在前。
`total`	`integer`	是	符合筛选条件的实例总数，跨所有页。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.list();
console.log(result);

instances.create

POST /v1/instances · Operation ID instanceCreate

创建实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.create`	`create(input: Models.CreateServerInstanceInput, idempotencyKey: string): Promise<Models.InstanceCreateResponse>`
Python	`cloud.instances.create`	`def create(self, input: CreateServerInstanceInput, options: InstanceCreateOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Create`	`func (r *InstancesResource) Create(ctx context.Context, input CreateServerInstanceInput, options InstanceCreateOptions) (RuntimeInstanceResult, error)`

参数

参数	位置	类型	必填	说明
`Idempotency-Key`	header	`string`	是	使请求可以安全重试的 key，1 到 256 字节，首尾不能有空白。用相同的 key 和请求体重复请求会重放原来的结果；把该 key 用于另一个不同的请求会返回 409 `idempotency_conflict`。

请求体

application/json · 必填 · Schema: CreateServerInstanceInput

字段	类型	必填	说明
`name`	`string`	是	实例的显示名称，1 到 128 字节，首尾不能有空白。
`variant_id`	`string`	否	用于创建实例的目录 variant 的 ID，最多 128 个字符。可用的 variant 见实例模板目录。未知 ID 返回 404 `variant_not_found`。
`harness`	`string`	否	在实例中运行的 harness。只接受 `openclaw`。可选值: `"openclaw"` — OpenClaw 智能体运行时.
`llm`	RuntimeLLM	否	实例使用的模型 provider 和模型。当 variant 或 harness 需要调用方提供模型时必填；自带模型的 variant 请省略。Provider API key 为只写。可为 null。

响应

202 · application/json · Schema: RuntimeInstanceResult

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	本次响应时的实例。
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.create({ name: "example" }, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

instances.get

GET /v1/instances/{instanceId} · Operation ID getInstance

获取实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.get`	`get(id: string): Promise<Models.GetInstanceResponse>`
Python	`cloud.instances.get`	`def get(self, instance_id: str) -> RuntimeInstanceResult`
Go	`cloud.Instances.Get`	`func (r *InstancesResource) Get(ctx context.Context, instanceId string) (RuntimeInstanceResult, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。

响应

200 · application/json · Schema: RuntimeInstanceResult

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	本次响应时的实例。
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.get("instance_123");
console.log(result);

instances.update

PATCH /v1/instances/{instanceId} · Operation ID updateInstanceMetadata

更新实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.update`	`update(instanceId: string, input: Models.UpdateServerInstanceInput, version: number): Promise<Models.UpdateInstanceMetadataResponse>`
Python	`cloud.instances.update`	`def update(self, instance_id: str, input: UpdateServerInstanceInput, options: UpdateInstanceMetadataOptions) -> UpdateInstanceMetadataResponse`
Go	`cloud.Instances.Update`	`func (r *InstancesResource) Update(ctx context.Context, instanceId string, input UpdateServerInstanceInput, options UpdateInstanceMetadataOptions) (UpdateInstanceMetadataResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`If-Match`	header	`string`	是	请求所针对的实例版本：即你最近一次读取的表示中的 `resource_version`，可以带引号。版本过期返回 412 `version_mismatch`；缺失或无效返回 428 `precondition_required`。

请求体

application/json · 必填 · Schema: UpdateServerInstanceInput

字段	类型	必填	说明
`name`	`string`	否	新的显示名称，1 到 128 个字符，首尾不能有空白。发送 `name`、`llm` 或两者。
`llm`	RuntimeLLM	否	替换用的模型 provider 和模型。它会替换整个现有的 llm 块。Provider API key 为只写。当同时发送 `name` 时，先替换 llm 块。

响应

200 · application/json

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	—

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.update("instance_123", {}, 1);
console.log(result);

instances.delete

DELETE /v1/instances/{instanceId} · Operation ID deleteInstance

删除实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.delete`	`delete(id: string, idempotencyKey: string, version: number): Promise<Models.DeleteInstanceResponse>`
Python	`cloud.instances.delete`	`def delete(self, instance_id: str, options: DeleteInstanceOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Delete`	`func (r *InstancesResource) Delete(ctx context.Context, instanceId string, options DeleteInstanceOptions) (RuntimeInstanceResult, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`Idempotency-Key`	header	`string`	是	使请求可以安全重试的 key，1 到 256 字节，首尾不能有空白。用相同的 key 和请求体重复请求会重放原来的结果；把该 key 用于另一个不同的请求会返回 409 `idempotency_conflict`。
`If-Match`	header	`string`	是	请求所针对的实例版本：即你最近一次读取的表示中的 `resource_version`，可以带引号。版本过期返回 412 `version_mismatch`；缺失或无效返回 428 `precondition_required`。

响应

202 · application/json · Schema: RuntimeInstanceResult

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	本次响应时的实例。
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.delete("instance_123", "YOUR_IDEMPOTENCY_KEY", 1);
console.log(result);

instances.createCanvasSession

POST /v1/instances/{instanceId}/canvas-sessions · Operation ID createCanvasSession

创建画布会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.createCanvasSession`	`createCanvasSession(instanceId: string, input: Models.CreateCanvasSessionRequest): Promise<Models.CreateCanvasSessionResponse>`
Python	`cloud.instances.create_canvas_session`	`def create_canvas_session(self, instance_id: str, input: CreateCanvasSessionRequest) -> CanvasSessionDocument`
Go	`cloud.Instances.CreateCanvasSession`	`func (r *InstancesResource) CreateCanvasSession(ctx context.Context, instanceId string, input CreateCanvasSessionRequest) (CanvasSessionDocument, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。

请求体

application/json · 必填

字段	类型	必填	说明
`platformAgentId`	`string`	是	画布会话所属智能体的 ID，UUID 格式。约束: `format=uuid`.
`conversationId`	`string`	是	画布所属会话的 ID，UUID 格式。约束: `format=uuid`.
`canvasId`	`string`	否	不透明的 Canvas/A2UI 界面标识符；不是 UUID. 约束: `minLength=1`, `maxLength=128`, `pattern=^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$`.

响应

201 一次性的 RS256 画布中继 ticket · application/json · Schema: CanvasSessionDocument

字段	类型	必填	说明
`transport`	`string`	是	ticket 的连接方式：始终为 `relay`。
`protocolVersion`	`integer`	是	ticket 协议的版本。目前为 1。
`header`	RealtimeTicketHeader	是	已签名 ticket 的 header。
`relayUrl`	`string`	是	该画布的画布中继 WebSocket URL，以 `/ws/{canvasId}` 结尾。
`ticket`	`string`	是	已签名的一次性 ticket（JWT），授权一次中继连接。有效期为 60 秒。
`issuedAt`	`string`	是	ticket 的签发时间，RFC 3339 时间戳。约束: `format=date-time`.
`expiresAt`	`string`	是	ticket 的过期时间，RFC 3339 时间戳。ticket 的有效期为 60 秒。约束: `format=date-time`.
`claims`	CanvasTicketClaims	是	已签名 ticket 中包含的 claims。

错误

状态码	Schema	说明
400	ErrorResponse	Cloud Server 错误
401	ErrorResponse	Cloud Server 错误
404	ErrorResponse	Cloud Server 错误
429	ErrorResponse	Cloud Server 错误
5XX	ErrorResponse	Cloud Server 错误
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.createCanvasSession("instance_123", {
  platformAgentId: "00000000-0000-4000-8000-000000000000",
  conversationId: "00000000-0000-4000-8000-000000000000"
});
console.log(result);

instances.getConnectURL

GET /v1/instances/{instanceId}/connect-url · Operation ID getInstanceConnectURL

获取实例连接 URL

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.getConnectURL`	`getConnectURL(instanceId: string, query?: Models.GetInstanceConnectURLQuery): Promise<Models.GetInstanceConnectURLResponse>`
Python	`cloud.instances.get_connect_url`	`def get_connect_url(self, instance_id: str, options: GetInstanceConnectURLOptions \| None = None) -> ConnectURLResponse`
Go	`cloud.Instances.GetConnectURL`	`func (r *InstancesResource) GetConnectURL(ctx context.Context, instanceId string, options GetInstanceConnectURLOptions) (ConnectURLResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`service`	query	`string`	否	要连接的服务：`browser` 表示浏览器查看端，`acp` 表示 agent 连接。必填。
`client_id`	query	`string`	否	你为查看端 client session 选择的 ID，1 到 128 个字符（字母、数字、`_`、`.`、`:` 和 `-`，以字母或数字开头）。当 `service` 为 `browser` 时必填；`acp` 不接受。
`role`	query	`string`	否	要请求的访问角色：`viewer` 或 `controller`。当 `service` 为 `browser` 时必填；`acp` 不接受。
`generation`	query	`string`	否	访问授权必须绑定的浏览器 generation，格式与 `client_id` 相同。如果浏览器当前的 generation 不同，请求会失败。仅用于 `browser`。

响应

200 · application/json · Schema: ConnectURLResponse

字段	类型	必填	说明
`data`	`object`	是	所请求服务的连接详情。
`data.url`	`string`	是	要连接的 URL。`browser` 时是浏览器查看端 URL；`acp` 时是一个 WebSocket URL，访问 ticket 已作为查询参数包含在内。
`data.mode`	`string`	是	连接模式：`browser` 对应 `browser-runtime`，`acp` 对应 `service-websocket`。可选值: `"browser-runtime"` — 浏览器查看会话；使用 `url` 和 `token` 连接; `"service-websocket"` — 到智能体服务的 WebSocket 连接；`url` 已带有访问 ticket. (枚举表)
`data.token`	`string`	是	浏览器查看端使用的短期访问 token。`acp` 不返回。
`data.service`	`string`	是	该 URL 所连接的服务：`browser` 或 `acp`。可选值: `"browser"` — 浏览器查看器; `"acp"` — 通过 WebSocket 连接智能体. (枚举表)
`data.connectivity`	`string`	是	实例中 agent 的可达性：`unknown`、`online` 或 `offline`。可选值: `"unknown"` — 尚未确定可达性; `"online"` — 该实例的智能体已连接; `"offline"` — 该实例的智能体未连接. (枚举表)
`data.stream_session_id`	`string`	是	查看端 client session 的 ID，即请求中发送的 `client_id`。`acp` 不返回。
`data.browser`	`object`	否	浏览器访问授权。仅在 `browser` 时返回。
`data.browser.grant_id`	`string`	是	浏览器访问授权的 ID。
`data.browser.generation`	`string`	是	该授权所绑定的浏览器 generation。如果请求中发送了 `generation`，则与该值相同。
`data.browser.expires_at`	`string`	是	访问授权过期的时间，Unix 毫秒。
`data.browser.role`	`string`	是	该授权的访问角色：`viewer` 或 `controller`。可选值: `"viewer"` — 可以查看浏览器，但不能控制; `"controller"` — 可以查看并控制浏览器. (枚举表)

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.getConnectURL("instance_123");
console.log(result);

instances.exec

POST /v1/instances/{instanceId}/exec · Operation ID execInstance

在实例中运行命令

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.exec`	`exec(instanceId: string, input: Models.ExecInstanceRequest): Promise<Models.ExecInstanceResponse>`
Python	`cloud.instances.exec`	`def exec(self, instance_id: str, input: ExecInstanceRequest) -> RuntimeExecResult`
Go	`cloud.Instances.Exec`	`func (r *InstancesResource) Exec(ctx context.Context, instanceId string, input ExecInstanceRequest) (RuntimeExecResult, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。

请求体

application/json · 必填

字段	类型	必填	说明
`argv`	`array<string>`	是	程序及其参数，以参数向量表示；绝不会经过 shell。1 到 64 项，每项最多 4096 字节，总计最多 16 KiB。第一项不能为空白。
`timeout_seconds`	`integer`	否	最长运行时间，单位为秒，取值 1 到 30。

响应

200 · application/json · Schema: RuntimeExecResult

字段	类型	必填	说明
`exit_code`	`integer`	是	命令的退出码。
`stdout`	`string`	是	命令的标准输出，最多 64 KiB。
`stderr`	`string`	是	命令的标准错误，最多 64 KiB。
`truncated`	`boolean`	是	输出是否被截断。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.exec("instance_123", { argv: ["example_argv"] });
console.log(result);

instances.start

POST /v1/instances/{instanceId}/start · Operation ID startInstance

启动实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.start`	`start(instanceId: string, idempotencyKey: string, version: number): Promise<Models.StartInstanceResponse>`
Python	`cloud.instances.start`	`def start(self, instance_id: str, options: StartInstanceOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Start`	`func (r *InstancesResource) Start(ctx context.Context, instanceId string, options StartInstanceOptions) (RuntimeInstanceResult, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`Idempotency-Key`	header	`string`	是	使请求可以安全重试的 key，1 到 256 字节，首尾不能有空白。用相同的 key 和请求体重复请求会重放原来的结果；把该 key 用于另一个不同的请求会返回 409 `idempotency_conflict`。
`If-Match`	header	`string`	是	请求所针对的实例版本：即你最近一次读取的表示中的 `resource_version`，可以带引号。版本过期返回 412 `version_mismatch`；缺失或无效返回 428 `precondition_required`。

响应

202 · application/json · Schema: RuntimeInstanceResult

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	本次响应时的实例。
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.start("instance_123", "YOUR_IDEMPOTENCY_KEY", 1);
console.log(result);

instances.getStatus

GET /v1/instances/{instanceId}/status · Operation ID getInstanceStatus

获取实例状态

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.getStatus`	`getStatus(id: string): Promise<Models.GetInstanceStatusResponse>`
Python	`cloud.instances.get_status`	`def get_status(self, instance_id: str) -> RuntimeInstanceStatusResult`
Go	`cloud.Instances.GetStatus`	`func (r *InstancesResource) GetStatus(ctx context.Context, instanceId string) (RuntimeInstanceStatusResult, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。

响应

200 · application/json · Schema: RuntimeInstanceStatusResult

字段	类型	必填	说明
`data`	`object`	是	实例的当前状态。
`data.id`	`string`	是	实例的唯一 ID。
`data.name`	`string`	是	实例的显示名称。
`data.status`	`string`	是	实例的生命周期阶段：`pending`、`provisioning`、`running`、`stopped` 或 `terminated`。取值见RuntimeInstanceStatusResult.data.status 取值。
`data.desired_status`	`string`	是	实例正被驱动朝向的生命周期阶段：`running`、`stopped` 或 `terminated`。可选值: `"running"` — 实例应处于运行状态; `"stopped"` — 实例应处于停止状态; `"terminated"` — 实例应被删除. (枚举表)
`data.connectivity`	`string`	是	实例中 agent 的可达性：`unknown`、`online` 或 `offline`。可选值: `"unknown"` — 尚未确定可达性; `"online"` — 该实例的智能体已连接; `"offline"` — 该实例的智能体未连接. (枚举表)
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.getStatus("instance_123");
console.log(result);

instances.stop

POST /v1/instances/{instanceId}/stop · Operation ID stopInstance

停止实例

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.stop`	`stop(id: string, idempotencyKey: string, version: number): Promise<Models.StopInstanceResponse>`
Python	`cloud.instances.stop`	`def stop(self, instance_id: str, options: StopInstanceOptions) -> RuntimeInstanceResult`
Go	`cloud.Instances.Stop`	`func (r *InstancesResource) Stop(ctx context.Context, instanceId string, options StopInstanceOptions) (RuntimeInstanceResult, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`Idempotency-Key`	header	`string`	是	使请求可以安全重试的 key，1 到 256 字节，首尾不能有空白。用相同的 key 和请求体重复请求会重放原来的结果；把该 key 用于另一个不同的请求会返回 409 `idempotency_conflict`。
`If-Match`	header	`string`	是	请求所针对的实例版本：即你最近一次读取的表示中的 `resource_version`，可以带引号。版本过期返回 412 `version_mismatch`；缺失或无效返回 428 `precondition_required`。

响应

202 · application/json · Schema: RuntimeInstanceResult

字段	类型	必填	说明
`data`	RuntimeInstanceSummary	是	本次响应时的实例。
`operation`	RuntimeOperationSummary	是	本次响应所报告的生命周期操作。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.stop("instance_123", "YOUR_IDEMPOTENCY_KEY", 1);
console.log(result);

instances.getStreamURL

GET /v1/instances/{instanceId}/stream-url · Operation ID getInstanceStreamURL

获取实例流 URL

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.getStreamURL`	`getStreamURL(instanceId: string, query?: Models.GetInstanceStreamURLQuery): Promise<Models.GetInstanceStreamURLResponse>`
Python	`cloud.instances.get_stream_url`	`def get_stream_url(self, instance_id: str, options: GetInstanceStreamURLOptions \| None = None) -> GetInstanceStreamURLResponse`
Go	`cloud.Instances.GetStreamURL`	`func (r *InstancesResource) GetStreamURL(ctx context.Context, instanceId string, options GetInstanceStreamURLOptions) (GetInstanceStreamURLResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`viewportWidth`	query	`integer`	否	视口宽度，单位为像素，大于 0 且小于 100000。
`viewportHeight`	query	`integer`	否	视口高度，单位为像素，大于 0 且小于 100000。
`dpr`	query	`number`	否	设备像素比，大于 0 且小于 16。

响应

200 · application/json

字段	类型	必填	说明
`data`	JSONValue	是	真正开放的 JSON 值（provider/插件参数或任意元数据）。可为 null。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.getStreamURL("instance_123");
console.log(result);

instances.createTerminalSession

POST /v1/instances/{instanceId}/terminal-sessions · Operation ID createTerminalSession

创建终端会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.createTerminalSession`	`createTerminalSession(instanceId: string, input: Models.CreateTerminalSessionRequest): Promise<Models.CreateTerminalSessionResponse>`
Python	`cloud.instances.create_terminal_session`	`def create_terminal_session(self, instance_id: str, input: CreateTerminalSessionRequest) -> TerminalSessionDocument`
Go	`cloud.Instances.CreateTerminalSession`	`func (r *InstancesResource) CreateTerminalSession(ctx context.Context, instanceId string, input CreateTerminalSessionRequest) (TerminalSessionDocument, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。

请求体

application/json · 必填

字段	类型	必填	说明
`platformAgentId`	`string`	是	终端会话所属智能体的 ID，UUID 格式。约束: `format=uuid`.
`conversationId`	`string`	否	要接入终端的会话的 ID，UUID 格式。可选。约束: `format=uuid`.
`resumeTerminalId`	`string`	否	要恢复的现有终端的 ID，UUID 格式。可选。约束: `format=uuid`.

响应

201 一次性的 RS256 终端 ticket · application/json · Schema: TerminalSessionDocument

字段	类型	必填	说明
`transport`	`string`	是	ticket 的连接方式：始终为 `service-websocket`。
`protocolVersion`	`integer`	是	ticket 协议的版本。目前为 1。
`header`	RealtimeTicketHeader	是	已签名 ticket 的 header。
`websocketUrl`	`string`	是	用于建立终端连接的 WebSocket URL。ticket 已作为查询参数包含在内。
`ticket`	`string`	是	已签名的一次性 ticket（JWT），授权一次终端连接。有效期为 60 秒。
`issuedAt`	`string`	是	ticket 的签发时间，RFC 3339 时间戳。约束: `format=date-time`.
`expiresAt`	`string`	是	ticket 的过期时间，RFC 3339 时间戳。ticket 的有效期为 60 秒。约束: `format=date-time`.
`claims`	TerminalTicketClaims	是	已签名 ticket 中包含的 claims。

错误

状态码	Schema	说明
400	ErrorResponse	Cloud Server 错误
401	ErrorResponse	Cloud Server 错误
404	ErrorResponse	Cloud Server 错误
429	ErrorResponse	Cloud Server 错误
5XX	ErrorResponse	Cloud Server 错误
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.createTerminalSession("instance_123", { platformAgentId: "00000000-0000-4000-8000-000000000000" });
console.log(result);

instances.upgrade

POST /v1/instances/{instanceId}/upgrade · Operation ID upgradeInstance

开始一次实例升级

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.upgrade`	`upgrade(instanceId: string, input: Models.UpgradeInstanceRequest, idempotencyKey: string): Promise<Models.UpgradeInstanceResponse>`
Python	`cloud.instances.upgrade`	`def upgrade(self, instance_id: str, input: UpgradeInstanceRequest, options: UpgradeInstanceOptions) -> RuntimeUpgradeJob`
Go	`cloud.Instances.Upgrade`	`func (r *InstancesResource) Upgrade(ctx context.Context, instanceId string, input UpgradeInstanceRequest, options UpgradeInstanceOptions) (RuntimeUpgradeJob, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`Idempotency-Key`	header	`string`	是	使请求可以安全重试的 key，1 到 256 字节，首尾不能有空白。用相同的 key 和请求体重复请求会重放原来的结果；把该 key 用于另一个不同的请求会返回 409 `idempotency_conflict`。

请求体

application/json · 必填

字段	类型	必填	说明
`image_id`	`string`	否	要升级到的已发布平台镜像的 ID。`image_id`、`image_ref` 和 `target_version` 至少发送一个；它们只在已发布的平台镜像中进行选择。
`image_ref`	`string`	否	要升级到的已发布平台镜像的固定公开引用。
`target_version`	`string`	否	要升级到的已发布平台镜像的版本。

响应

202 · application/json · Schema: RuntimeUpgradeJob

字段	类型	必填	说明
`job_id`	`string`	是	升级任务的唯一 ID。
`image_version_id`	`string`	否	—
`instance_id`	`string`	是	正在升级的实例的 ID。
`status`	`string`	是	任务的状态：`upgrade_pending`、`rollback_pending`、`failed` 或 `succeeded`。可选值: `"upgrade_pending"` — 正在应用镜像升级; `"rollback_pending"` — 镜像升级失败，实例正在回滚到之前的镜像; `"failed"` — 镜像升级失败。见 `error`; `"succeeded"` — 镜像升级已完成，实例运行目标版本. (枚举表)
`target`	`string`	是	实例正在升级到的镜像版本。
`created_at`	`string`	是	任务的创建时间，RFC 3339 UTC 时间戳。
`completed_at`	`string`	否	任务结束的时间，RFC 3339 UTC 时间戳。任务未结束时省略。可为 null。
`error`	`string`	否	稳定的失败码。只有任务失败时才出现。可为 null。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.upgrade("instance_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

instances.getUpgrade

GET /v1/instances/{instanceId}/upgrades/{jobId} · Operation ID getInstanceUpgrade

获取一次实例升级

SDK 方法

语言	方法	签名
TypeScript	`cloud.instances.getUpgrade`	`getUpgrade(instanceId: string, jobId: string): Promise<Models.GetInstanceUpgradeResponse>`
Python	`cloud.instances.get_upgrade`	`def get_upgrade(self, instance_id: str, job_id: str) -> RuntimeUpgradeJob`
Go	`cloud.Instances.GetUpgrade`	`func (r *InstancesResource) GetUpgrade(ctx context.Context, instanceId string, jobId string) (RuntimeUpgradeJob, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	实例的 ID。
`jobId`	path	`string`	是	升级任务的 ID，即启动升级时返回的 `job_id`。

响应

200 · application/json · Schema: RuntimeUpgradeJob

字段	类型	必填	说明
`job_id`	`string`	是	升级任务的唯一 ID。
`image_version_id`	`string`	否	—
`instance_id`	`string`	是	正在升级的实例的 ID。
`status`	`string`	是	任务的状态：`upgrade_pending`、`rollback_pending`、`failed` 或 `succeeded`。可选值: `"upgrade_pending"` — 正在应用镜像升级; `"rollback_pending"` — 镜像升级失败，实例正在回滚到之前的镜像; `"failed"` — 镜像升级失败。见 `error`; `"succeeded"` — 镜像升级已完成，实例运行目标版本. (枚举表)
`target`	`string`	是	实例正在升级到的镜像版本。
`created_at`	`string`	是	任务的创建时间，RFC 3339 UTC 时间戳。
`completed_at`	`string`	否	任务结束的时间，RFC 3339 UTC 时间戳。任务未结束时省略。可为 null。
`error`	`string`	否	稳定的失败码。只有任务失败时才出现。可为 null。

错误

状态码	Schema	说明
其他（default）	ErrorResponse	Cloud Server 错误

错误 schema 见错误。

示例

import { BeeOSClient } from "@beeos-ai/cloud-sdk";

const cloud = new BeeOSClient({
  baseURL: "https://api.cloud.beeos.ai/v1",
  apiKey: "YOUR_API_KEY", // bsk_ key: backend only
});
const result = await cloud.instances.getUpgrade("instance_123", "job_123");
console.log(result);

BeeOS Cloud返回文档首页