文件

面向接入 OpenBot 客户端或扩展服务端的开发者。示例需要本页说明的访问权限。从开发者手册开始。

文件是你交给 OpenBot 的一张图片、一个 PDF 或其他文档。你上传一次，然后在给 Bot 的消息中指明它。Bot 的模型就能看到这个文件。

OpenBot 把每个文件的字节保存在对象存储中：一种保存文件、使用 S3 API 的服务，例如 AWS S3、Cloudflare R2、MinIO 或 RustFS。平台管理员负责设置存储。见设置存储。

每个文件属于一个组织中的一个成员。其他人不能读取它。

上传文件

上传有两种方式。平台管理员可以分别打开或关闭它们。

通过 OpenBot

把文件以 multipart/form-data 发送到 POST /v1/files。字段 file 放文件。OpenBot 接受其他字段，例如 purpose，但不使用它们。

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -F file=@photo.png \
  https://api.example.com/v1/files

{
  "id": "file_6f1c…",
  "object": "file",
  "filename": "photo.png",
  "mediaType": "image/png",
  "bytes": 52731,
  "status": "ready",
  "createdAt": 1793000000000
}

文件立刻就是 ready。OpenBot 从表单读取媒体类型。当表单写的是 application/octet-stream 时，OpenBot 会根据文件名的结尾猜测类型，例如 .png 或 .pdf。

直接上传到存储

对于大文件，客户端可以自己把字节放进存储。这样字节就不经过 OpenBot。

用 POST /v1/files/uploads 请求一个上传地址：

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","mediaType":"application/pdf","bytes":1048576}' \
  https://api.example.com/v1/files/uploads

{
  "file": { "id": "file_9a2e…", "status": "pending", "…": "…" },
  "url": "https://s3.example.com/openbot/files/file_9a2e…?X-Amz-Signature=…",
  "method": "PUT",
  "headers": {
    "content-type": "application/pdf",
    "content-length": "1048576"
  },
  "expiresAt": 1793000900000
}

用 PUT 把字节发送到 url，并带上这些 headers。这个地址 15 分钟内有效。签名包含媒体类型和大小，所以存储不会接受别的字节。
用 POST /v1/files/:fileId/complete 完成文件。OpenBot 会检查字节已经在存储中，并且大小正确。然后文件就是 ready。

一个小时内没有人完成的文件会被删除。

限制

平台设置决定文件最大多大，以及 OpenBot 接受哪些媒体类型。默认情况下，一个文件最大 20 MB，允许这些类型：

image/png、image/jpeg、image/gif、image/webp
application/pdf
text/plain

每个模型只接受某些类型。模型不接受的文件会让 Turn 失败。所以列表中只保留你的模型能读的类型。

平台管理员还可以用 files.quotaBytes 给每个成员一个配额。配额是一个成员的所有文件加起来最多能占的字节数。pending 的文件也算在内，所以直接上传在字节到达之前就占住了空间。放不下的文件返回 413 和 FileQuotaExceeded，并带有 quotaBytes 和 usedBytes。删除文件可以拿回空间。默认没有配额。

把文件交给 Bot

在消息的 content 中指明文件。input_image 接受媒体类型以 image/ 开头的文件。input_file 接受任何文件，例如 PDF。

curl -H "Authorization: Bearer $OPENBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": [{
      "role": "user",
      "content": [
        { "type": "input_text", "text": "What is in this picture?" },
        { "type": "input_image", "file_id": "file_6f1c…" }
      ]
    }]
  }' \
  https://api.example.com/v1/bots/$BOT/messages

文件必须是你自己的文件，并且必须是 ready。否则 OpenBot 返回 400 和 FileInvalid。

Chat 只保存文件的 ID，不保存它的字节。每次调用模型之前，OpenBot 从存储读取字节。如果文件已被删除，模型会在它的位置看到一条简短的说明。

读取和删除文件

请求	作用
`GET /v1/files`	列出你的文件，最新的在前。用 `next` 读取更多。
`GET /v1/files/:fileId`	读取一个文件。
`GET /v1/files/:fileId/content`	给出一个已就绪文件的字节。
`DELETE /v1/files/:fileId`	立刻删除一个文件。返回 `204`。

GET /v1/files/:fileId/content 在字节从存储到达时就发送它们，所以大文件不会停留在 OpenBot 的内存里。如果存储在字节开始之前出错，回答是 503。如果之后出错，回答会提前结束。把长度和文件的 bytes 比较，确认你拿到了全部字节。

读取文件需要 File 上的 read，上传和删除需要 File 上的 write。每个成员对自己的文件都有这两个权限。见权限。

文件怎样被删除

OpenBot 会删除没有人需要的文件。这叫垃圾回收。每个实例每分钟运行一次，多个实例可以同时运行它。

指明了一个文件的 Chat 会保留它。只要这个 Chat 还在，文件就会留着。
当你删除这个 Chat 后，它就不再保留这个文件。见删除历史。
没有任何 Chat 保留的文件，在一段时间内没人使用后会被删除。默认时间是 24 小时。平台管理员可以用 files.unusedMs 修改它。
没有人完成的文件在一小时后被删除。
你删除的文件会立刻消失。它的字节会在下一次运行时离开存储。

当没有存储时，OpenBot 会保留已删除文件的行。存储恢复后，它会删除这些文件的字节。

设置存储

参见文件存储.

错误

状态码	错误	何时出现
`400`	`FileInvalid`	文件太大、类型不被平台接受，或者还没有就绪。
`404`	`FileNotFound`	你没有这个 ID 的文件。
`413`	`FileQuotaExceeded`	文件放不进你的配额中剩下的空间。
`409`	`FilesDisabled`	平台没有存储，或者这种上传方式已关闭。
`503`	`FilesUnavailable`	OpenBot 无法访问它的数据库或存储。