Files API
管理
GET /v1/files
列出认证团队拥有的文件，并进行分页处理。响应始终返回一个 `pagination_token`；将其作为查询参数传回以获取下一页。当返回的 `data` 数组长度小于 `limit` 时，表示已到达列表末尾。
查询参数
limit(整数) — 单次响应中返回的最大对象数量。order(字符串) — 用于排序返回文件的顺序。使用 `asc` 表示升序，`desc` 表示降序。sort_by(字符串) — 排序依据的字段。有效选项：`created_at`、`filename`、`size`。默认为 `created_at`。pagination_token(字符串) — 上一次列出文件请求返回的分页令牌。after(字符串) — 仅用于兼容性。请使用 `pagination_token`。filter(字符串) — AIP-160 过滤表达式，用于缩小结果范围。可过滤字段：
字段 类型 描述 `name` (或 `file_name`) 字符串 文件名的模糊匹配 `file_id` 字符串 文件 ID 的精确匹配 `size_bytes` 整数 文件大小（字节） `content_type` 字符串 MIME 类型的部分匹配（例如 `"pdf"` 匹配 `"application/pdf"`） `created_at` 时间戳 RFC 3339 时间戳（例如 `"2024-01-01T00:00:00Z"`） `expires_at` 时间戳 RFC 3339 时间戳 `upload_status` 字符串 上传状态（`"Complete"`） `user_defined_id` 字符串 用户定义 ID 的精确匹配 运算符： `=`, `!=`, `>`, `>=`, `<`, `<=`
逻辑运算： `AND`, `OR`, `NOT`
示例：
- `name:"quarterly report"` — 文件名的模糊匹配
- `content_type = "pdf"` — PDF 内容类型的文件
- `size_bytes > 1000000 AND created_at > "2024-01-01T00:00:00Z"` — 大于 1 MB 且在 2024 年 1 月 1 日之后创建的文件
- `file_id = "file_abc123"` — 精确的文件 ID 匹配
响应体
data(数组<对象>, 必需) — 文件列表。bytes(整数, 必需) — 文件大小，以字节为单位。created_at(整数, 必需) — 文件创建时间的 Unix 时间戳（秒）。expires_at(整数 | null) — 文件过期时间的 Unix 时间戳（秒）。如果文件不过期，则为 null。filename(字符串, 必需) — 文件名。id(字符串, 必需) — 文件标识符，可用于其他 API 请求。object(字符串, 必需) — 对象类型，始终为 `file`。仅用于兼容性。public_url(字符串 | null) — 文件的公共 URL。仅当文件具有活动的公共 URL 时存在。public_url_expires_at(整数 | null) — 公共 URL 过期的 Unix 时间戳（秒）。仅当公共 URL 具有独立的过期时间时存在。purpose(字符串) — 上传文件的预期用途。仅包含用于 OAI 兼容性。
pagination_token(字符串 | null) — 用于下一次请求的分页令牌。
响应示例：
{
"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"
}GET /v1/files/{file_id}
通过 ID 检索单个文件的元数据。如果文件不存在、已被删除或已超过其 `expires_at`，则返回 404 错误。
路径参数
file_id(字符串, 必需) — 上传或列出操作返回的文件的 `id`。
响应体
bytes(整数, 必需) — 文件大小，以字节为单位。created_at(整数, 必需) — 文件创建时间的 Unix 时间戳（秒）。expires_at(整数 | null) — 文件过期时间的 Unix 时间戳（秒）。如果文件不过期，则为 null。filename(字符串, 必需) — 文件名。id(字符串, 必需) — 文件标识符，可用于其他 API 请求。object(字符串, 必需) — 对象类型，始终为 `file`。仅用于兼容性。public_url(字符串 | null) — 文件的公共 URL。仅当文件具有活动的公共 URL 时存在。public_url_expires_at(整数 | null) — 公共 URL 过期的 Unix 时间戳（秒）。仅当公共 URL 具有独立的过期时间时存在。purpose(字符串) — 上传文件的预期用途。仅包含用于 OAI 兼容性。
响应示例：
{}PUT /v1/files/{file_id}
向 /v1/files/{file_id} 发送 PUT 请求的 API 端点。
Method: PUT
Path: /v1/files/{file_id}DELETE /v1/files/{file_id}
通过 ID 删除文件。此请求返回后，文件将不再出现在 `GET /v1/files` 中，内容下载将返回 404，并且该 ID 无法再在聊天附件中被引用。
路径参数
file_id(字符串, 必需) — 要删除的文件的 `id`。
响应体
deleted(布尔值, 必需) — 文件是否已被删除。id(字符串, 必需) — 文件的 ID。object(字符串, 必需) — 对象类型，始终为 "file"。仅用于兼容性。
响应示例：
{
"id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
"deleted": true
}