跳转到内容

Drive 文件

在 /api/v1/user/drive 下使用所属 End User 的 User API Key。组织后端可通过 /api/v1/org/users/{userId}/drive 操作指定 End User 的文件;调用者仍是 Organization,范围必须留在该组织内。

  1. 用 GET /api/v1/user/drive/upload-capabilities 读取有效限制。
  2. 用 POST /api/v1/user/drive/uploads 创建上传,携带稳定 Idempotency-Key、originalName、byteSize、整个文件的小写 sha256 和 contentType(未指定时为 null)。
  3. 按返回的传输方式上传。活跃 Inline 上传的响应包含 upload.uploadUrl,可交给终端:按其相对 url 和全部 headers PUT 文件字节,无需 API Key。成功直接返回 ready File,空文件也支持。原有携带 Key 的 Inline 路径使用 PUT /api/v1/user/drive/uploads/{uploadId}/content,携带准确长度和 Content-Digest。Multipart 通过 /uploads/{uploadId}/parts/{partNumber}/presign 获得各分片的受限 URL,使用返回请求头并保存摘要与 ETag。
  4. Multipart 用 POST /api/v1/user/drive/uploads/{uploadId}/complete 确认,提交完整且按编号升序排列的分片列表。Inline PUT 已返回 ready,仍支持用 {} 确认。整个文件的大小和摘要验证通过后才就绪。

传输或确认结果不确定时读取 /uploads/{uploadId}。重放原上传意图保留 File 和固定到期时间。失败或过期的上传需要新意图,完整性失败是终态。用 DELETE /uploads/{uploadId} 取消待完成上传。

组织后端在 /api/v1/org/users/{userId}/drive 下使用同一套 Inline 和 Multipart 流程,每次带鉴权的核心管理请求都携带 Organization Key。Multipart 创建返回 partSize 和 totalParts,不签发核心上传票据。每次分片授权和完成请求都会重新检查当前确切 Key 与活跃普通所有者。轮换或撤销后,可用有效 Key 恢复同一所有者的上传,保留 File 和固定到期时间。已返回的分片 URL 继续遵循存储提供方控制的有效期;变更 Organization Key 不会撤销这些 URL。已获准的核心完成请求可以继续结束。停用所有者后仍可读取 File、查询上传状态和中止清理,但创建、分片授权和完成需要活跃所有者。普通就绪 File 可通过 /api/v1/org/users/{userId}/files 列出和读取,/{fileId}/content 返回内容,也可选作 Turn 输入。

Organization 签发的上传和下载票据绑定签发时的确切凭据。轮换或撤销后拒绝新的兑换请求;已获准的传输可在原有限制内完成。使用有效 Key 重放原创建请求,可为活跃 Inline 上传续签票据,保留 File 与固定到期时间。保留的 User-Key 票据继续遵循原有有效期。

小文件上传时,后端保管 Organization 或 User API Key,仅把 upload.uploadUrl 交给网页。调用 fetch(new URL(upload.uploadUrl.url, API_ORIGIN), { method: 'PUT', headers: upload.uploadUrl.headers, body: file, credentials: 'omit' }),浏览器自动提供 Content-Length。URL 是 Bearer 凭据,避免写入日志或公开分享。60 秒有效期限制请求准入,上传另有独立的 120 秒请求期限。遇到 404 upload_ticket_invalid,后端重放相同创建请求体和 Idempotency-Key,为活跃上传续签。状态查询不签发 URL;已完成的重放和未配置票据密钥的非生产部署也省略该字段。遇到 409 idempotency_in_progress 先查状态,当前操作结束后重试;失败、取消或过期的上传需要新 Key 和 File。503 upload_temporarily_unavailable 也可能表示并发额度不足或请求超时;已经开始的写入仍可能完成,应查询状态。

任意来源的网页也可以直接调用这些上传接口,在 Authorization 中携带 User API Key。网页因此持有可访问该 End User 全部接口的密钥,只应交给该 End User 自己的客户端。响应允许所有来源,但从不允许凭据,因此不要发送 Cookie。Inline PUT 需显式设置 Content-Type: application/octet-stream;否则 File 或 Blob 请求体会使用自身的媒体类型,上传会被拒绝。Multipart 分片直接上传到 Drive9 对象存储。该 Drive9 存储的运营方必须配置其 CORS 策略:允许该网页来源和 presign 返回的所有请求头,并暴露 ETag。

GET /api/v1/user/drive/entries 列出目录的直接子项,或按 path、fileId 读取条目。就绪附件与通用文件共用不透明文件标识。后续分页携带返回游标和原范围、筛选条件。

终端窗口
curl --fail-with-body --get "$BASE_URL/api/v1/user/drive/entries" \
-H "Authorization: Bearer $USER_API_KEY" --data-urlencode 'path=/'
curl --fail-with-body --get "$BASE_URL/api/v1/user/drive/files/content" \
-H "Authorization: Bearer $USER_API_KEY" --data-urlencode "fileId=$FILE_ID"

内容读取返回完整文件字节。目录和隐藏系统资产不属于这个文件接口。通过 Session 命令流程为消息选择就绪文件;仅创建上传不代表内容已经就绪。

MCP 工具返回图片、音频或其他二进制内容时,平台把每一项存为该 Session 所属 End User 的就绪 File,并把它的引用交给模型;支持图片输入的模型还会看到图片本身。像其他 File 一样通过 /api/v1/org/users/{userId}/files/{fileId} 和 /content 读取,或选作 Turn 输入。它的 source 为 {"kind": "session", "sessionId": ..., "operationId": ...},上传的 File 则为 {"kind": "user_upload"}。该工具调用的 Operation 在 output.details.mcp.files 中列出 File 标识,从不包含字节。

超出二进制限额(单项 4 MiB,单个结果合计 8 MiB 且最多 8 项)的结果会在存储任何 File 之前使调用失败;失败的调用不会留下部分 File。

用 POST /api/v1/user/drive/directories 创建目录。用 PUT /api/v1/user/drive/files/content 创建或覆盖通用文件,需要稳定 Idempotency-Key 和准确 Content-Length。覆盖还需要当前带引号的 If-Match ETag。完整确认的写入返回文件事实和 ETag。

DELETE /api/v1/user/drive/entries 非递归删除文件或空目录。写入或删除结果未知时不能自动再次提交;先核对结果,再决定是否发出另一个命令。完整请求体和请求头见 API 参考。

用 POST /api/v1/user/drive/download-tickets 为已授权 fileId 签发短期票据。在 GET /api/v1/drive-downloads/{ticket} 兑换完整内容或受限存储重定向。

票据是 Bearer 凭据,持有者可以直接兑换。避免写入日志或公开分享。到期后通过授权读取流程获得新票据。

后端可用 Organization Key 在 /api/v1/org/users/{userId}/drive 调用相同的通用 Drive 操作,包括管理禁用普通用户的已有数据。组织签发的票据绑定具体凭据:轮换或吊销后拒绝新的兑换请求,已准入的传输可以完成。另一把 Key 的票据不受影响;使用有效凭据可重新签发票据。已返回的存储提供方 URL 保留自己的有效期,不会因核心侧检查而被撤销。

Drive 票据现使用不透明的 v4 格式。旧 v3.drive 链接缺少签发者归属,因此被拒绝;升级后需申请新票据。新签发的 User Key Drive 票据保留独立于 Key 的有效期规则,其他下载类型和 User 上传票据的既有契约保持不变。