BEEOS CLOUD / DEVELOPER REFERENCE

文件

预签名上传、文件元数据、分享链接与文件汇总。

概览

files domain 存储和分享文件：准备预签名上传并确认，列出和读取文件元数据，重命名和删除文件，管理文件分享链接，并返回文件汇总。

11 个操作 · SDK 资源：TypeScript cloud.files · Python cloud.files · Go cloud.Files · API 总览

主要对象

FilePrepareUploadInput 与 FileTransferDescriptor：上传请求，以及用来传输文件的描述符。
FileConfirmInput 与 FileFile：确认请求与已存储的文件。
FilePage、FileResolution、FileSummary：列表、解析后的文件和汇总。
FileShareResponse：分享链接。

FilePrepareUploadInput

字段	类型	必填	说明
`upload_context`	FileChatUploadContext	否	把上传关联到一个实例，也可以关联到一个智能体。文件归该凭证的组织和应用所有。普通上传请省略该上下文。可为 null。
`filename`	`string`	是	文件名，1 到 255 个字符，首尾不含空白，且不含 `/`、`\` 或控制字符。
`content_type`	`string`	是	文件的 MIME 类型，最多 255 个字符，不含控制字符。上传的内容必须是该类型。
`size_bytes`	`integer`	是	文件大小，单位为字节，1 到 104857600（100 MiB）。上传的内容必须正好是这个大小。
`checksum_sha256`	`string`	否	内容的小写十六进制 SHA-256 摘要（64 个字符）。可选。发送时，上传的内容必须与之一致，确认时会校验。

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

FileTransferDescriptor

字段	类型	必填	说明
`direction`	`string`	是	该 URL 用于上传还是下载文件内容。可选值: `"upload"` — 用 `http_method` 把文件内容发送到 `url`。准备上传时返回; `"download"` — 用 `http_method` 从 `url` 获取文件内容。读取文件或分享时返回. (枚举表)
`file_id`	`string`	是	该传输所针对的文件的 ID。
`url`	`string`	是	用于传输文件内容的预签名 URL。该 URL 已签名，因此不要向它发送你的 API key。
`http_method`	`string`	是	配合 `url` 使用的 HTTP 方法：上传用 `PUT`，下载用 `GET`。
`required_headers`	`map<string, string>`	是	传输请求中要原样发送的 header。不需要时为空。
`expires_at`	`string`	是	URL 失效的时间，RFC 3339 时间戳。上传 URL 有效期为 15 分钟，下载 URL 为 5 分钟。约束: `format=date-time`.
`content_type`	`string`	是	文件的 MIME 类型。
`size_bytes`	`integer`	是	文件大小，单位字节。
`checksum_sha256`	`string`	否	文件内容的小写十六进制 SHA-256 摘要。不知道摘要时省略。

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

FileConfirmInput

字段	类型	必填	说明
`checksum_sha256`	`string`	否	已上传内容的小写十六进制 SHA-256 摘要（64 个字符）。可选。发送时，会与已存储对象的摘要比较，不一致则确认失败，返回 409 `checksum_mismatch`。

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

FileFile

字段	类型	必填	说明
`file_id`	`string`	是	文件的唯一 ID。
`filename`	`string`	是	文件名，不含路径。
`content_type`	`string`	是	文件的 MIME 类型，例如 image/png。
`size_bytes`	`integer`	是	文件大小，单位字节。
`checksum_sha256`	`string`	否	文件内容的小写十六进制 SHA-256 摘要。上传时未提供校验和、且对象上也没有记录时为空。
`status`	`string`	是	文件的上传状态。已删除的文件永远不会返回。以后可能新增状态，请忽略不认识的取值。可选值: `"pending_upload"` — 上传已准备好，但尚未确认。文件还没有可下载的内容; `"ready"` — 上传已确认。文件可以下载、重命名、分享和删除. (枚举表)
`resource_version`	`integer`	是	文件记录的版本。从 1 开始，在上传被确认、以及文件被重命名或删除时增加。
`updated_at`	`string`	是	文件最后一次变更的时间：创建、确认或重命名，取最晚的一次。RFC 3339 时间戳。约束: `format=date-time`.
`title`	`string`	否	从文档自身元数据中读取的标题。对不超过 8 MiB 的 PDF、docx、xlsx 和 pptx 文件，在首次按 ID 读取时提取；文档没有可用标题时省略。
`file_type`	`string`	是	文件的类别，由其 MIME 类型得出；对于 `application/octet-stream` 这类通用类型，则由扩展名得出。取值见下表 FileFile.file_type 取值。
`created_at`	`string`	是	文件记录的创建时间，即准备上传时。RFC 3339 时间戳。约束: `format=date-time`.
`confirmed_at`	`string`	否	上传被确认的时间。文件就绪之前省略。RFC 3339 时间戳。可为 null。约束: `format=date-time`.
`origin`	FileOrigin	否	文件的来源，以及它所属的实例和智能体。可为 null。

FileFile.file_type 取值

取值	含义
`"FILE_TYPE_IMAGE"`	图片，例如 PNG、JPEG、GIF、WebP 或 SVG。
`"FILE_TYPE_VIDEO"`	视频，例如 MP4、MOV 或 WebM。
`"FILE_TYPE_AUDIO"`	音频文件，例如 MP3、WAV 或 FLAC。
`"FILE_TYPE_DOCUMENT"`	文本或办公文档，例如纯文本、Markdown、JSON、PDF、Word、Excel、PowerPoint 或 OpenDocument。
`"FILE_TYPE_ARCHIVE"`	压缩或打包的归档文件，例如 ZIP、TAR、GZIP、7z 或 RAR。
`"FILE_TYPE_OTHER"`	其他任何文件。

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

FilePage

字段	类型	必填	说明
`data`	array<FileFile>	是	本页的文件。
`total`	`integer`	是	符合查询条件的文件数量，跨所有页。
`next_since`	`string`	否	作为 `since` 传入以获取下一页的游标。只有默认的按时间顺序列表才返回，且仅在后面还有文件时返回。经过过滤或排序的列表改用 `offset` 分页。

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

FileResolution

字段	类型	必填	说明
`file`	FileFile	是	该文件。
`download`	FileTransferDescriptor	是	用于下载内容的预签名描述。文件仍为 `pending_upload` 时，它不带可用的 URL。

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

FileSummary

字段	类型	必填	说明
`file_count`	`integer`	是	就绪文件的数量。
`storage_file_count`	`integer`	是	计入存储的就绪文件的数量。模板 skill 提供的文件不计入。
`used_bytes`	`integer`	是	计入存储的文件的总大小，单位为字节。
`image_count`	`integer`	是	`FILE_TYPE_IMAGE` 类别中就绪文件的数量。
`video_count`	`integer`	是	`FILE_TYPE_VIDEO` 类别中就绪文件的数量。
`document_count`	`integer`	是	`FILE_TYPE_DOCUMENT` 类别中就绪文件的数量。
`instances`	`array<object>`	是	就绪文件按所属智能体分组，没有智能体的按实例分组，最大的组在前。
`instances[].source`	`string`	是	文件是如何产生的。以后可能新增取值，请忽略不认识的取值。可选值: `"manual"` — 通过 files API 直接上传，不带 upload context。没有记录来源的文件按 `manual` 报告; `"chat_upload"` — 带 `upload_context` 上传，用于与其所指定的智能体的会话; `"runtime_generated"` — 由智能体在处理请求时生成。`operation_id` 标识该操作; `"template_skill"` — 由模板 skill 提供。该文件只读：不能重命名或删除，也不计入存储用量. (枚举表)
`instances[].instance_id`	`string`	否	文件所属实例的 ID。与实例无关的文件省略。
`instances[].agent_id`	`string`	否	文件所属智能体的 ID。与智能体无关的文件省略。
`instances[].operation_id`	`string`	否	生成该文件的智能体操作的 ID。仅当 `source` 为 `runtime_generated` 时设置。
`instances[].instance_name`	`string`	否	实例当前的显示名称，在返回文件时填充。没有实例的文件省略。
`instances[].agent_name`	`string`	否	智能体当前的显示名称，在返回文件时填充。没有智能体的文件省略。
`instances[].avatar_url`	`string`	否	智能体头像的 URL。没有智能体的文件省略。
`instances[].harness`	`string`	否	实例运行的 harness，例如 `openclaw`。没有实例的文件省略。
`instances[].destroyed`	`boolean`	否	实例已被终止或删除时为 true。文件仍然可用。为 false 时省略。
`instances[].count`	`integer`	是	该组中就绪文件的数量。

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

FileShareResponse

字段	类型	必填	说明
`file_id`	`string`	是	被分享文件的 ID。
`slug`	`string`	是	分享的公开 slug。把它传给 resolve-share 操作以获取文件。
`filename`	`string`	是	被分享文件的当前名称。
`content_type`	`string`	是	被分享文件的 MIME 类型。
`size_bytes`	`integer`	是	被分享文件的大小，单位为字节。
`revoked`	`boolean`	是	分享已被撤销时为 true。已撤销的分享不能再被解析。再次创建分享会重新启用它。

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

典型流程

用 files.prepareUpload 申请上传，并按返回的描述符传输文件内容。
用 files.confirmUpload 确认。
用 files.list 与 files.get 查找文件；用 files.rename 重命名；用 files.delete 删除。
用 files.createShare 分享文件，用 files.getShare 读取链接；拿到 slug 的人通过 files.resolveShare 打开；用 files.revokeShare 撤回。
files.getSummary 返回整体文件汇总。

方法

方法	HTTP	摘要
files.resolveShare	`GET /v1/file-shares/{slug}`	解析文件分享链接
files.list	`GET /v1/files`	列出文件
files.get	`GET /v1/files/{fileId}`	获取文件
files.rename	`PATCH /v1/files/{fileId}`	重命名文件
files.delete	`DELETE /v1/files/{fileId}`	删除文件
files.confirmUpload	`POST /v1/files/{fileId}/confirm`	确认一次文件上传
files.getShare	`GET /v1/files/{fileId}/share`	获取文件分享链接
files.createShare	`POST /v1/files/{fileId}/share`	创建文件分享链接
files.revokeShare	`DELETE /v1/files/{fileId}/share`	撤销文件分享链接
files.prepareUpload	`POST /v1/files/presign-upload`	创建文件上传 URL
files.getSummary	`GET /v1/files/summary`	获取文件汇总

files.resolveShare

GET /v1/file-shares/{slug} · Operation ID resolveFileShare

解析文件分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.resolveShare`	`resolveShare(slug: string): Promise<Models.ResolveFileShareResponse>`
Python	`cloud.files.resolve_share`	`def resolve_share(self, slug: str) -> ResolveFileShareResponse`
Go	`cloud.Files.ResolveShare`	`func (r *FilesResource) ResolveShare(ctx context.Context, slug string) (ResolveFileShareResponse, error)`

参数

参数	位置	类型	必填	说明
`slug`	path	`string`	是	文件分享的公开 slug，即创建分享时返回的 `slug`。

响应

200 · application/json

字段	类型	必填	说明
`file_id`	`string`	是	—
`slug`	`string`	是	—
`filename`	`string`	是	—
`content_type`	`string`	是	—
`size_bytes`	`integer`	是	—
`download`	FileTransferDescriptor	是	—

错误

状态码	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.files.resolveShare("share_slug");
console.log(result);

files.list

GET /v1/files · Operation ID listFiles

列出文件

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.list`	`list(query?: Models.ListFilesQuery): Promise<Models.ListFilesResponse>`
Python	`cloud.files.list`	`def list(self, options: ListFilesOptions \| None = None) -> FilePage`
Go	`cloud.Files.List`	`func (r *FilesResource) List(ctx context.Context, options ListFilesOptions) (FilePage, error)`

参数

参数	位置	类型	必填	说明
`content_type`	query	`string`	否	只返回 MIME 类型与此完全相同的文件，最多 255 个字符。
`since`	query	`string`	否	上一页 `next_since` 的游标。省略则从最旧的文件开始。仅适用于默认的按时间顺序列表，即未设置 `status`、`file_type`、`category`、`source`、`q`、`instance_id`、`agent_id`、`sort`、`sort_dir` 和 `offset` 中任何一个时。最多 2048 个字符。
`status`	query	`string`	否	只返回处于该状态的文件：`ready` 或 `pending_upload`。省略时，两种状态的文件都会返回。
`file_type`	query	`string`	否	只返回该类别的文件：`FILE_TYPE_IMAGE`、`FILE_TYPE_VIDEO`、`FILE_TYPE_AUDIO`、`FILE_TYPE_DOCUMENT`、`FILE_TYPE_ARCHIVE` 或 `FILE_TYPE_OTHER`。
`category`	query	`string`	否	只返回属于该大类的文件：`image`、`video`、`document` 或 `other`。`other` 涵盖所有不是图片、视频或文档的文件，包括音频和归档。
`source`	query	`string`	否	只返回该来源的文件：`manual`、`chat_upload`、`runtime_generated` 或 `template_skill`。没有记录来源的文件按 `manual` 计。
`q`	query	`string`	否	只返回名称包含该文本的文件，不区分大小写比较。
`instance_id`	query	`string`	否	只返回属于该实例的文件。
`agent_id`	query	`string`	否	只返回属于该智能体的文件。
`sort`	query	`string`	否	排序字段：`created_at`（默认）、`updated_at`、`file_name` 或 `size_bytes`。并列时按文件 ID 排序。任何排序、过滤或 `offset` 都会把列表切换为 offset 分页。
`sort_dir`	query	`string`	否	排序方向：`asc` 或 `desc`。排序或过滤时默认为 `desc`；默认的按时间顺序列表是最旧的在前。
`limit`	query	`integer`	否	返回的文件的最大数量，0 到 200。默认为 50。
`offset`	query	`integer`	否	要跳过的匹配文件数量，0 或更大。设置它会把列表切换为 offset 分页。

响应

200 · application/json · Schema: FilePage

字段	类型	必填	说明
`data`	array<FileFile>	是	本页的文件。
`total`	`integer`	是	符合查询条件的文件数量，跨所有页。
`next_since`	`string`	否	作为 `since` 传入以获取下一页的游标。只有默认的按时间顺序列表才返回，且仅在后面还有文件时返回。经过过滤或排序的列表改用 `offset` 分页。

错误

状态码	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.files.list();
console.log(result);

files.get

GET /v1/files/{fileId} · Operation ID getFile

获取文件

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.get`	`get(fileId: string): Promise<Models.GetFileResponse>`
TypeScript	`cloud.files.resolveDownload`	`resolveDownload(fileId: string)`
TypeScript	`cloud.files.download`	`download(fileId: string)`
Python	`cloud.files.get`	`def get(self, file_id: str) -> FileResolution`
Go	`cloud.Files.Get`	`func (r *FilesResource) Get(ctx context.Context, fileId string) (FileResolution, error)`

cloud.files.resolveDownload: 通过无类型的 client.request 调用 GET /files/{fileId}；返回类型被推断为 Promise<JSONValue>。需要强类型结果请使用 files.get。

cloud.files.download: files.resolveDownload(fileId) 的别名；返回类型被推断为 Promise<JSONValue>。

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。

响应

200 · application/json · Schema: FileResolution

字段	类型	必填	说明
`file`	FileFile	是	该文件。
`download`	FileTransferDescriptor	是	用于下载内容的预签名描述。文件仍为 `pending_upload` 时，它不带可用的 URL。

错误

状态码	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.files.get("file_123");
console.log(result);

files.rename

PATCH /v1/files/{fileId} · Operation ID renameFile

重命名文件

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.rename`	`rename(fileId: string, input: Models.RenameFileRequest): Promise<Models.RenameFileResponse>`
Python	`cloud.files.rename`	`def rename(self, file_id: str, input: RenameFileRequest) -> FileFile`
Go	`cloud.Files.Rename`	`func (r *FilesResource) Rename(ctx context.Context, fileId string, input RenameFileRequest) (FileFile, error)`

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。

请求体

application/json · 必填

字段	类型	必填	说明
`title`	`string`	是	文件的新名称，1 到 255 个字符，首尾不含空白，且不含 `/`、`\` 或控制字符。

响应

200 · application/json · Schema: FileFile

字段	类型	必填	说明
`file_id`	`string`	是	文件的唯一 ID。
`filename`	`string`	是	文件名，不含路径。
`content_type`	`string`	是	文件的 MIME 类型，例如 image/png。
`size_bytes`	`integer`	是	文件大小，单位字节。
`checksum_sha256`	`string`	否	文件内容的小写十六进制 SHA-256 摘要。上传时未提供校验和、且对象上也没有记录时为空。
`status`	`string`	是	文件的上传状态。已删除的文件永远不会返回。以后可能新增状态，请忽略不认识的取值。可选值: `"pending_upload"` — 上传已准备好，但尚未确认。文件还没有可下载的内容; `"ready"` — 上传已确认。文件可以下载、重命名、分享和删除. (枚举表)
`resource_version`	`integer`	是	文件记录的版本。从 1 开始，在上传被确认、以及文件被重命名或删除时增加。
`updated_at`	`string`	是	文件最后一次变更的时间：创建、确认或重命名，取最晚的一次。RFC 3339 时间戳。约束: `format=date-time`.
`title`	`string`	否	从文档自身元数据中读取的标题。对不超过 8 MiB 的 PDF、docx、xlsx 和 pptx 文件，在首次按 ID 读取时提取；文档没有可用标题时省略。
`file_type`	`string`	是	文件的类别，由其 MIME 类型得出；对于 `application/octet-stream` 这类通用类型，则由扩展名得出。取值见FileFile.file_type 取值。
`created_at`	`string`	是	文件记录的创建时间，即准备上传时。RFC 3339 时间戳。约束: `format=date-time`.
`confirmed_at`	`string`	否	上传被确认的时间。文件就绪之前省略。RFC 3339 时间戳。可为 null。约束: `format=date-time`.
`origin`	FileOrigin	否	文件的来源，以及它所属的实例和智能体。可为 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.files.rename("file_123", { title: "example_title" });
console.log(result);

files.delete

DELETE /v1/files/{fileId} · Operation ID deleteFile

删除文件

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.delete`	`delete(fileId: string, idempotencyKey: string): Promise<Models.DeleteFileResponse>`
Python	`cloud.files.delete`	`def delete(self, file_id: str, options: DeleteFileOptions) -> None`
Go	`cloud.Files.Delete`	`func (r *FilesResource) Delete(ctx context.Context, fileId string, options DeleteFileOptions) error`

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。
`Idempotency-Key`	header	`string`	是	让请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和参数重复请求会重放原结果；用相同的 key 发起不同的请求则返回 409 `idempotency_conflict`。

响应

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.files.delete("file_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.confirmUpload

POST /v1/files/{fileId}/confirm · Operation ID confirmFileUpload

确认一次文件上传

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.confirmUpload`	`confirmUpload(fileId: string, input: Models.FileConfirmInput, idempotencyKey: string): Promise<Models.ConfirmFileUploadResponse>`
Python	`cloud.files.confirm_upload`	`def confirm_upload(self, file_id: str, input: FileConfirmInput, options: ConfirmFileUploadOptions) -> FileFile`
Go	`cloud.Files.ConfirmUpload`	`func (r *FilesResource) ConfirmUpload(ctx context.Context, fileId string, input FileConfirmInput, options ConfirmFileUploadOptions) (FileFile, error)`

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。
`Idempotency-Key`	header	`string`	是	让请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和参数重复请求会重放原结果；用相同的 key 发起不同的请求则返回 409 `idempotency_conflict`。

请求体

application/json · 必填 · Schema: FileConfirmInput

字段	类型	必填	说明
`checksum_sha256`	`string`	否	已上传内容的小写十六进制 SHA-256 摘要（64 个字符）。可选。发送时，会与已存储对象的摘要比较，不一致则确认失败，返回 409 `checksum_mismatch`。

响应

200 · application/json · Schema: FileFile

字段	类型	必填	说明
`file_id`	`string`	是	文件的唯一 ID。
`filename`	`string`	是	文件名，不含路径。
`content_type`	`string`	是	文件的 MIME 类型，例如 image/png。
`size_bytes`	`integer`	是	文件大小，单位字节。
`checksum_sha256`	`string`	否	文件内容的小写十六进制 SHA-256 摘要。上传时未提供校验和、且对象上也没有记录时为空。
`status`	`string`	是	文件的上传状态。已删除的文件永远不会返回。以后可能新增状态，请忽略不认识的取值。可选值: `"pending_upload"` — 上传已准备好，但尚未确认。文件还没有可下载的内容; `"ready"` — 上传已确认。文件可以下载、重命名、分享和删除. (枚举表)
`resource_version`	`integer`	是	文件记录的版本。从 1 开始，在上传被确认、以及文件被重命名或删除时增加。
`updated_at`	`string`	是	文件最后一次变更的时间：创建、确认或重命名，取最晚的一次。RFC 3339 时间戳。约束: `format=date-time`.
`title`	`string`	否	从文档自身元数据中读取的标题。对不超过 8 MiB 的 PDF、docx、xlsx 和 pptx 文件，在首次按 ID 读取时提取；文档没有可用标题时省略。
`file_type`	`string`	是	文件的类别，由其 MIME 类型得出；对于 `application/octet-stream` 这类通用类型，则由扩展名得出。取值见FileFile.file_type 取值。
`created_at`	`string`	是	文件记录的创建时间，即准备上传时。RFC 3339 时间戳。约束: `format=date-time`.
`confirmed_at`	`string`	否	上传被确认的时间。文件就绪之前省略。RFC 3339 时间戳。可为 null。约束: `format=date-time`.
`origin`	FileOrigin	否	文件的来源，以及它所属的实例和智能体。可为 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.files.confirmUpload("file_123", {}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.getShare

GET /v1/files/{fileId}/share · Operation ID getShareFileShare

获取文件分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.getShare`	`getShare(fileId: string): Promise<Models.GetShareFileShareResponse>`
Python	`cloud.files.get_share`	`def get_share(self, file_id: str) -> FileShareResponse`
Go	`cloud.Files.GetShare`	`func (r *FilesResource) GetShare(ctx context.Context, fileId string) (FileShareResponse, error)`

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。

响应

200 · application/json · Schema: FileShareResponse

字段	类型	必填	说明
`file_id`	`string`	是	被分享文件的 ID。
`slug`	`string`	是	分享的公开 slug。把它传给 resolve-share 操作以获取文件。
`filename`	`string`	是	被分享文件的当前名称。
`content_type`	`string`	是	被分享文件的 MIME 类型。
`size_bytes`	`integer`	是	被分享文件的大小，单位为字节。
`revoked`	`boolean`	是	分享已被撤销时为 true。已撤销的分享不能再被解析。再次创建分享会重新启用它。

错误

状态码	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.files.getShare("file_123");
console.log(result);

files.createShare

POST /v1/files/{fileId}/share · Operation ID createShareFileShare

创建文件分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.createShare`	`createShare(fileId: string, idempotencyKey: string): Promise<Models.CreateShareFileShareResponse>`
Python	`cloud.files.create_share`	`def create_share(self, file_id: str, options: CreateShareFileShareOptions) -> FileShareResponse`
Go	`cloud.Files.CreateShare`	`func (r *FilesResource) CreateShare(ctx context.Context, fileId string, options CreateShareFileShareOptions) (FileShareResponse, error)`

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。
`Idempotency-Key`	header	`string`	是	让请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和参数重复请求会重放原结果；用相同的 key 发起不同的请求则返回 409 `idempotency_conflict`。

响应

200 · application/json · Schema: FileShareResponse

字段	类型	必填	说明
`file_id`	`string`	是	被分享文件的 ID。
`slug`	`string`	是	分享的公开 slug。把它传给 resolve-share 操作以获取文件。
`filename`	`string`	是	被分享文件的当前名称。
`content_type`	`string`	是	被分享文件的 MIME 类型。
`size_bytes`	`integer`	是	被分享文件的大小，单位为字节。
`revoked`	`boolean`	是	分享已被撤销时为 true。已撤销的分享不能再被解析。再次创建分享会重新启用它。

错误

状态码	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.files.createShare("file_123", "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.revokeShare

DELETE /v1/files/{fileId}/share · Operation ID revokeShareFileShare

撤销文件分享链接

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.revokeShare`	`revokeShare(fileId: string): Promise<Models.RevokeShareFileShareResponse>`
Python	`cloud.files.revoke_share`	`def revoke_share(self, file_id: str) -> None`
Go	`cloud.Files.RevokeShare`	`func (r *FilesResource) RevokeShare(ctx context.Context, fileId string) error`

参数

参数	位置	类型	必填	说明
`fileId`	path	`string`	是	文件的 ID，即准备上传时返回的 `file_id`。

响应

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.files.revokeShare("file_123");
console.log(result);

files.prepareUpload

POST /v1/files/presign-upload · Operation ID presignFileUpload

创建文件上传 URL

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.prepareUpload`	`prepareUpload(input: Models.FilePrepareUploadInput, idempotencyKey: string): Promise<Models.PresignFileUploadResponse>`
TypeScript	`cloud.files.upload`	`upload(input: Models.FilePrepareUploadInput, idempotencyKey: string)`
Python	`cloud.files.prepare_upload`	`def prepare_upload(self, input: FilePrepareUploadInput, options: PresignFileUploadOptions) -> FileTransferDescriptor`
Go	`cloud.Files.PrepareUpload`	`func (r *FilesResource) PrepareUpload(ctx context.Context, input FilePrepareUploadInput, options PresignFileUploadOptions) (FileTransferDescriptor, error)`

cloud.files.upload: files.prepareUpload(input, idempotencyKey) 的别名：返回预签名上传描述符。SDK 不传输文件内容；请向返回的 URL 上传，再调用 files.confirmUpload。

参数

参数	位置	类型	必填	说明
`Idempotency-Key`	header	`string`	是	让请求可以安全重试的 key，8 到 128 个字符，首尾不含空白。用相同的 key 和参数重复请求会重放原结果；用相同的 key 发起不同的请求则返回 409 `idempotency_conflict`。

请求体

application/json · 必填 · Schema: FilePrepareUploadInput

字段	类型	必填	说明
`upload_context`	FileChatUploadContext	否	把上传关联到一个实例，也可以关联到一个智能体。文件归该凭证的组织和应用所有。普通上传请省略该上下文。可为 null。
`filename`	`string`	是	文件名，1 到 255 个字符，首尾不含空白，且不含 `/`、`\` 或控制字符。
`content_type`	`string`	是	文件的 MIME 类型，最多 255 个字符，不含控制字符。上传的内容必须是该类型。
`size_bytes`	`integer`	是	文件大小，单位为字节，1 到 104857600（100 MiB）。上传的内容必须正好是这个大小。
`checksum_sha256`	`string`	否	内容的小写十六进制 SHA-256 摘要（64 个字符）。可选。发送时，上传的内容必须与之一致，确认时会校验。

响应

201 · application/json · Schema: FileTransferDescriptor

字段	类型	必填	说明
`direction`	`string`	是	该 URL 用于上传还是下载文件内容。可选值: `"upload"` — 用 `http_method` 把文件内容发送到 `url`。准备上传时返回; `"download"` — 用 `http_method` 从 `url` 获取文件内容。读取文件或分享时返回. (枚举表)
`file_id`	`string`	是	该传输所针对的文件的 ID。
`url`	`string`	是	用于传输文件内容的预签名 URL。该 URL 已签名，因此不要向它发送你的 API key。
`http_method`	`string`	是	配合 `url` 使用的 HTTP 方法：上传用 `PUT`，下载用 `GET`。
`required_headers`	`map<string, string>`	是	传输请求中要原样发送的 header。不需要时为空。
`expires_at`	`string`	是	URL 失效的时间，RFC 3339 时间戳。上传 URL 有效期为 15 分钟，下载 URL 为 5 分钟。约束: `format=date-time`.
`content_type`	`string`	是	文件的 MIME 类型。
`size_bytes`	`integer`	是	文件大小，单位字节。
`checksum_sha256`	`string`	否	文件内容的小写十六进制 SHA-256 摘要。不知道摘要时省略。

错误

状态码	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.files.prepareUpload({
  filename: "example_filename",
  content_type: "example_content_type",
  size_bytes: 1
}, "YOUR_IDEMPOTENCY_KEY");
console.log(result);

files.getSummary

GET /v1/files/summary · Operation ID getFilesSummary

获取文件汇总

SDK 方法

语言	方法	签名
TypeScript	`cloud.files.getSummary`	`getSummary(): Promise<Models.GetFilesSummaryResponse>`
Python	`cloud.files.get_summary`	`def get_summary(self) -> FileSummary`
Go	`cloud.Files.GetSummary`	`func (r *FilesResource) GetSummary(ctx context.Context) (FileSummary, error)`

响应

200 · application/json · Schema: FileSummary

字段	类型	必填	说明
`file_count`	`integer`	是	就绪文件的数量。
`storage_file_count`	`integer`	是	计入存储的就绪文件的数量。模板 skill 提供的文件不计入。
`used_bytes`	`integer`	是	计入存储的文件的总大小，单位为字节。
`image_count`	`integer`	是	`FILE_TYPE_IMAGE` 类别中就绪文件的数量。
`video_count`	`integer`	是	`FILE_TYPE_VIDEO` 类别中就绪文件的数量。
`document_count`	`integer`	是	`FILE_TYPE_DOCUMENT` 类别中就绪文件的数量。
`instances`	`array<object>`	是	就绪文件按所属智能体分组，没有智能体的按实例分组，最大的组在前。
`instances[].source`	`string`	是	文件是如何产生的。以后可能新增取值，请忽略不认识的取值。可选值: `"manual"` — 通过 files API 直接上传，不带 upload context。没有记录来源的文件按 `manual` 报告; `"chat_upload"` — 带 `upload_context` 上传，用于与其所指定的智能体的会话; `"runtime_generated"` — 由智能体在处理请求时生成。`operation_id` 标识该操作; `"template_skill"` — 由模板 skill 提供。该文件只读：不能重命名或删除，也不计入存储用量. (枚举表)
`instances[].instance_id`	`string`	否	文件所属实例的 ID。与实例无关的文件省略。
`instances[].agent_id`	`string`	否	文件所属智能体的 ID。与智能体无关的文件省略。
`instances[].operation_id`	`string`	否	生成该文件的智能体操作的 ID。仅当 `source` 为 `runtime_generated` 时设置。
`instances[].instance_name`	`string`	否	实例当前的显示名称，在返回文件时填充。没有实例的文件省略。
`instances[].agent_name`	`string`	否	智能体当前的显示名称，在返回文件时填充。没有智能体的文件省略。
`instances[].avatar_url`	`string`	否	智能体头像的 URL。没有智能体的文件省略。
`instances[].harness`	`string`	否	实例运行的 harness，例如 `openclaw`。没有实例的文件省略。
`instances[].destroyed`	`boolean`	否	实例已被终止或删除时为 true。文件仍然可用。为 false 时省略。
`instances[].count`	`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.files.getSummary();
console.log(result);

BeeOS Cloud返回文档首页