文件 API
管理
列出文件
/v1/files
分页列出已认证团队拥有的文件。响应始终返回 `pagination_token`；将其作为查询参数传回即可获取下一页。当返回的 `data` 数组短于 `limit` 时，说明已到达列表末尾。
查询参数
limitinteger（integer）— 单个响应中返回对象的最大数量。
orderstring（string）— 返回文件的排序顺序。使用 `asc` 表示升序，`desc` 表示降序。
sort_bystring（string）— 用于排序的字段。有效选项：`created_at`、`filename`、`size`。默认为 `created_at`。
pagination_tokenstring（string）：上一次列出文件请求返回的分页 token。
afterstring（string）— 仅为兼容性而包含。请改用 `pagination_token`。
filterstring（string）：用于缩小结果范围的 AIP-160 过滤表达式。
响应体
dataarray<object>（array<object>，必填）— 文件列表。
No parameters.{
"data": [
{
"id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
"object": "file",
"bytes": 12345,
"created_at": 1762345678,
"expires_at": null,
"filename": "document.pdf",
"purpose": ""
}
],
"pagination_token": "file_a128090d-f0c9-4873-bd84-e499777e7417"
}获取文件元数据
/v1/files/{file_id}
按 ID 获取单个文件的元数据。文件不存在、已删除或已超过其 `expires_at` 时返回 404。
路径参数
file_idstring（string，必填）— 上传或列出文件时返回的文件 `id`。
响应体
bytesinteger（integer，必填）— 文件大小，单位为字节。
created_atinteger（integer，必填）— 文件创建时间的 Unix 时间戳（秒）。
filenamestring（string，必填）— 文件名称。
idstring（string，必填）— 文件标识符，可在其他 API 请求中使用。
objectstring（string，必填）— 对象类型，始终为 `file`。仅为兼容性而包含。
purposestring（string）— 上传文件的预期用途。仅为兼容 OAI 而包含。
No parameters.{}No parameters.No response.删除文件
/v1/files/{file_id}
按 ID 删除文件。此调用返回后，该文件不再出现在 `GET /v1/files` 中，内容下载会返回 404，且该 ID 不再能在聊天附件中被引用。
路径参数
file_idstring（string，必填）— 要删除的文件 `id`。
响应体
deletedboolean（boolean，必填）— 文件是否已删除。
idstring（string，必填）— 文件的 ID。
objectstring（string，必填）— 对象类型，始终为 "file"。仅为兼容性而包含。
No parameters.{
"id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
"deleted": true
}最后更新：2026 年 4 月 28 日