BEEOS CLOUD / DEVELOPER REFERENCE

画布

画布分享链接、快照与会话画布会话。

概览

canvases domain 管理实例画布的分享链接和快照，并解析会话的画布会话。

6 个操作 · SDK 资源：TypeScript cloud.canvases · Python cloud.canvases · Go cloud.Canvases · API 总览

主要对象

CanvasShare：画布分享链接。
CanvasSnapshot：画布的一个已保存状态。
CanvasSessionDocument：会话的画布会话。

CanvasShare

字段	类型	必填	说明
`id`	`string`	是	分享的唯一 ID。
`canvasId`	`string`	是	被分享的画布的 ID。一个画布最多有一个分享。
`slug`	`string`	是	分享的公开标识，用于构造分享链接。更新分享时保持不变。
`mode`	`string`	是	访客如何获得访问权。`password` 要求访客输入创建分享时设置的密码。其他任何值（例如 `link`）表示任何拥有链接的人都可以打开画布。
`allowInteraction`	`boolean`	是	访客是否可以与画布交互。为 false 时，访客只能查看。
`expiresAt`	`string`	否	分享失效的时间，RFC 3339 时间戳。分享不过期时省略；通过此 API 创建的分享永不过期。
`createdAt`	`string`	是	分享首次创建的时间，RFC 3339 时间戳。更新分享不会改变它。

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

CanvasSnapshot

字段	类型	必填	说明
`id`	`string`	是	快照的唯一 ID。把它传给 restore 操作。
`canvasId`	`string`	是	快照所属画布的 ID。
`componentsSnapshot`	`string`	否	生成快照时画布的内容，为 base64 编码的 JSON：surface 数组，每个都有 `surfaceId`、`presentation`、`components` 和 `root`。未捕获内容时省略。
`actorType`	`string`	是	做出快照所记录的大部分变更的操作者类型：`user` 为人（还原点也记录为 `user`），`agent` 为智能体，`system` 为没有已知操作者的自动快照。
`actorId`	`string`	是	`actorType` 所指的操作者的 ID。没有已知操作者的自动快照为 `system`。
`description`	`string`	否	关于快照的简短备注，例如自动快照为 `Auto-snapshot`，还原点为 `Restored from v3`。没有时省略。
`version`	`integer`	是	快照所记录的画布内容的版本。数字越大越新。
`createdAt`	`string`	是	生成快照的时间，RFC 3339 时间戳。

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

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。

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

RealtimeTicketHeader

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

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

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 秒。

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

典型流程

用 canvases.getSession 解析会话的画布会话。
用 canvases.createShare 分享画布，用 canvases.getShare 读取链接；用 canvases.deleteShare 撤回。
用 canvases.listSnapshots 列出已保存的状态，用 canvases.restoreSnapshot 恢复其中一个。

方法

方法	HTTP	摘要
canvases.getSession	`GET /v1/instances/{instanceId}/canvas-sessions/{conversationId}`	解析会话画布会话
canvases.getShare	`GET /v1/instances/{instanceId}/canvases/{canvasId}/share`	获取画布分享链接
canvases.createShare	`POST /v1/instances/{instanceId}/canvases/{canvasId}/share`	创建画布分享链接
canvases.deleteShare	`DELETE /v1/instances/{instanceId}/canvases/{canvasId}/share`	撤销画布分享链接
canvases.listSnapshots	`GET /v1/instances/{instanceId}/canvases/{canvasId}/snapshots`	列出画布快照
canvases.restoreSnapshot	`POST /v1/instances/{instanceId}/canvases/{canvasId}/snapshots/{snapshotId}/restore`	恢复画布快照

canvases.getSession

GET /v1/instances/{instanceId}/canvas-sessions/{conversationId} · Operation ID getCanvasSession

解析会话画布会话

SDK 方法

语言	方法	签名
TypeScript	`cloud.canvases.getSession`	`getSession(instanceId: string, conversationId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.GetCanvasSessionResponse>`
Python	`cloud.canvases.get_session`	`def get_session(self, instance_id: str, conversation_id: str, options: GetCanvasSessionOptions) -> GetCanvasSessionResponse`
Go	`cloud.Canvases.GetSession`	`func (r *CanvasesResource) GetSession(ctx context.Context, instanceId string, conversationId string, options GetCanvasSessionOptions) (GetCanvasSessionResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	承载该智能体的实例的 ID。它必须属于你的应用。
`conversationId`	path	`string`	是	要查询画布会话的会话 ID。它必须等于 `X-BeeOS-Conversation-ID` header。
`X-BeeOS-Conversation-ID`	header	`string`	是	使用该画布的会话的 ID。查询会话时，它必须等于路径中的 `conversationId`。
`X-BeeOS-Platform-Agent-ID`	header	`string`	是	拥有该画布的智能体的 ID。它必须是 `instanceId` 的智能体。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	`object`	是	可为 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.canvases.getSession("instance_123", "conversation_123", "conversation_123", "agent_123");
console.log(result);

canvases.getShare

GET /v1/instances/{instanceId}/canvases/{canvasId}/share · Operation ID getShareCanvas

获取画布分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.canvases.getShare`	`getShare(instanceId: string, canvasId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.GetShareCanvasResponse>`
Python	`cloud.canvases.get_share`	`def get_share(self, instance_id: str, canvas_id: str, options: GetShareCanvasOptions) -> GetShareCanvasResponse`
Go	`cloud.Canvases.GetShare`	`func (r *CanvasesResource) GetShare(ctx context.Context, instanceId string, canvasId string, options GetShareCanvasOptions) (GetShareCanvasResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	承载该智能体的实例的 ID。它必须属于你的应用。
`canvasId`	path	`string`	是	画布的 ID，UUID 格式。该画布必须属于 header 所指定的会话和智能体。
`X-BeeOS-Conversation-ID`	header	`string`	是	使用该画布的会话的 ID。查询会话时，它必须等于路径中的 `conversationId`。
`X-BeeOS-Platform-Agent-ID`	header	`string`	是	拥有该画布的智能体的 ID。它必须是 `instanceId` 的智能体。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	CanvasShare	是	可为 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.canvases.getShare("instance_123", "canvas_123", "conversation_123", "agent_123");
console.log(result);

canvases.createShare

POST /v1/instances/{instanceId}/canvases/{canvasId}/share · Operation ID createShareCanvas

创建画布分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.canvases.createShare`	`createShare(instanceId: string, canvasId: string, input: Models.CreateShareCanvasRequest, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.CreateShareCanvasResponse>`
Python	`cloud.canvases.create_share`	`def create_share(self, instance_id: str, canvas_id: str, input: CreateShareCanvasRequest, options: CreateShareCanvasOptions) -> CreateShareCanvasResponse`
Go	`cloud.Canvases.CreateShare`	`func (r *CanvasesResource) CreateShare(ctx context.Context, instanceId string, canvasId string, input CreateShareCanvasRequest, options CreateShareCanvasOptions) (CreateShareCanvasResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	承载该智能体的实例的 ID。它必须属于你的应用。
`canvasId`	path	`string`	是	画布的 ID，UUID 格式。该画布必须属于 header 所指定的会话和智能体。
`X-BeeOS-Conversation-ID`	header	`string`	是	使用该画布的会话的 ID。查询会话时，它必须等于路径中的 `conversationId`。
`X-BeeOS-Platform-Agent-ID`	header	`string`	是	拥有该画布的智能体的 ID。它必须是 `instanceId` 的智能体。

请求体

application/json · 必填

字段	类型	必填	说明
`mode`	`string`	是	访客如何获得访问权：`password` 表示用 `password` 保护分享；其他任何值（例如 `link`）表示任何拥有链接的人都可以打开画布。必填。
`password`	`string`	否	访客必须输入的密码。仅在 `mode` 为 `password` 时使用；没有它，任何访客都无法通过校验。
`allowInteraction`	`boolean`	否	访客是否可以与画布交互。默认为 true。发送 false 则分享为只读。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	CanvasShare	是	可为 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.canvases.createShare("instance_123", "canvas_123", { mode: "example_mode" }, "conversation_123", "agent_123");
console.log(result);

canvases.deleteShare

DELETE /v1/instances/{instanceId}/canvases/{canvasId}/share · Operation ID deleteShareCanvas

撤销画布分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.canvases.deleteShare`	`deleteShare(instanceId: string, canvasId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.DeleteShareCanvasResponse>`
Python	`cloud.canvases.delete_share`	`def delete_share(self, instance_id: str, canvas_id: str, options: DeleteShareCanvasOptions) -> None`
Go	`cloud.Canvases.DeleteShare`	`func (r *CanvasesResource) DeleteShare(ctx context.Context, instanceId string, canvasId string, options DeleteShareCanvasOptions) error`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	承载该智能体的实例的 ID。它必须属于你的应用。
`canvasId`	path	`string`	是	画布的 ID，UUID 格式。该画布必须属于 header 所指定的会话和智能体。
`X-BeeOS-Conversation-ID`	header	`string`	是	使用该画布的会话的 ID。查询会话时，它必须等于路径中的 `conversationId`。
`X-BeeOS-Platform-Agent-ID`	header	`string`	是	拥有该画布的智能体的 ID。它必须是 `instanceId` 的智能体。

响应

204

无响应体。

错误

状态码	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.canvases.deleteShare("instance_123", "canvas_123", "conversation_123", "agent_123");
console.log(result);

canvases.listSnapshots

GET /v1/instances/{instanceId}/canvases/{canvasId}/snapshots · Operation ID listCanvasSnapshots

列出画布快照

SDK 方法

语言	方法	签名
TypeScript	`cloud.canvases.listSnapshots`	`listSnapshots(instanceId: string, canvasId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.ListCanvasSnapshotsResponse>`
Python	`cloud.canvases.list_snapshots`	`def list_snapshots(self, instance_id: str, canvas_id: str, options: ListCanvasSnapshotsOptions) -> ListCanvasSnapshotsResponse`
Go	`cloud.Canvases.ListSnapshots`	`func (r *CanvasesResource) ListSnapshots(ctx context.Context, instanceId string, canvasId string, options ListCanvasSnapshotsOptions) (ListCanvasSnapshotsResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	承载该智能体的实例的 ID。它必须属于你的应用。
`canvasId`	path	`string`	是	画布的 ID，UUID 格式。该画布必须属于 header 所指定的会话和智能体。
`X-BeeOS-Conversation-ID`	header	`string`	是	使用该画布的会话的 ID。查询会话时，它必须等于路径中的 `conversationId`。
`X-BeeOS-Platform-Agent-ID`	header	`string`	是	拥有该画布的智能体的 ID。它必须是 `instanceId` 的智能体。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	array<CanvasSnapshot>	是	—

错误

状态码	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.canvases.listSnapshots("instance_123", "canvas_123", "conversation_123", "agent_123");
console.log(result);

canvases.restoreSnapshot

POST /v1/instances/{instanceId}/canvases/{canvasId}/snapshots/{snapshotId}/restore · Operation ID restoreCanvasSnapshot

恢复画布快照

SDK 方法

语言	方法	签名
TypeScript	`cloud.canvases.restoreSnapshot`	`restoreSnapshot(instanceId: string, canvasId: string, snapshotId: string, XBeeOSConversationID: string, XBeeOSPlatformAgentID: string): Promise<Models.RestoreCanvasSnapshotResponse>`
Python	`cloud.canvases.restore_snapshot`	`def restore_snapshot(self, instance_id: str, canvas_id: str, snapshot_id: str, options: RestoreCanvasSnapshotOptions) -> RestoreCanvasSnapshotResponse`
Go	`cloud.Canvases.RestoreSnapshot`	`func (r *CanvasesResource) RestoreSnapshot(ctx context.Context, instanceId string, canvasId string, snapshotId string, options RestoreCanvasSnapshotOptions) (RestoreCanvasSnapshotResponse, error)`

参数

参数	位置	类型	必填	说明
`instanceId`	path	`string`	是	承载该智能体的实例的 ID。它必须属于你的应用。
`canvasId`	path	`string`	是	画布的 ID，UUID 格式。该画布必须属于 header 所指定的会话和智能体。
`snapshotId`	path	`string`	是	要恢复的快照的 ID，即快照列表返回的 ID。
`X-BeeOS-Conversation-ID`	header	`string`	是	使用该画布的会话的 ID。查询会话时，它必须等于路径中的 `conversationId`。
`X-BeeOS-Platform-Agent-ID`	header	`string`	是	拥有该画布的智能体的 ID。它必须是 `instanceId` 的智能体。

响应

200 · application/json

字段	类型	必填	说明
`success`	`boolean`	是	—
`data`	`object`	是	—
`data.snapshotId`	`string`	是	—
`data.canvasId`	`string`	是	—
`data.restored`	`boolean`	是	—
`data.version`	`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.canvases.restoreSnapshot("instance_123", "canvas_123", "snapshot_123", "conversation_123", "agent_123");
console.log(result);

BeeOS Cloud返回文档首页