# 概念 (/docs/cloud/services/file/concepts)



## purpose 用途 [#purpose-用途]

`purpose` 记录文件的预期用途。上传接受三个值：

| purpose      | 用途与限制                                                                            |
| ------------ | -------------------------------------------------------------------------------- |
| `user_data`  | 通用输入文件。在对话中引用图片时必须使用此值。                                                          |
| `assistants` | 用于智能体或知识库工作流的文件。上传不等于加入智能体或知识库；对话图片引用不接受此用途。                                     |
| `vision`     | 只接受 PNG、JPEG、GIF、WebP 图片（按内容识别），其他内容返回 400 `FILE_TYPE_UNSUPPORTED`；对话图片引用不接受此用途。 |

上传不接受 `batch`、`fine-tune` 和 `evals`。通过 Anthropic 上传的文件统一记为 `user_data`。

## 引用 file\_id [#引用-file_id]

同一账户的 `/file/v1/files`、`/openai/v1/files` 和 `/anthropic/v1/files` 共用文件 ID，可跨接口读取元数据和删除。上传文件的下载使用文件 API 或 OpenAI API；Anthropic 下载仅支持会话输出文件。

* **对话**：图片以 `user_data` 上传，用 `type: "file"` 与 `file.file_id` 引用。不要将 ID 填进 `image_url.url`。文本和 PDF 的文件 ID 当前不能作为对话图片输入。参见[图片引用示例](/docs/cloud/services/model/guides/files)。
* **素材库**：用 `file_id` 导入，生成素材记录。参见[素材 API](/docs/api/native/media/assets)。
* **知识库**：将 `file_id` 加入库后，才会提取内容并建立索引。参见[知识库概念](/docs/cloud/services/knowledge/concepts)。
* **智能体**：用 `type: "file"`、`file_id` 和 `mount_path` 将文件加入会话资源。仅设置 `purpose=assistants` 不会挂载文件。参见[会话资源 API](/docs/api/native/agent)。

会话输出文件的元数据可包含 `scope`、`relative_path` 和 `revision`。用 `scope_id` 列出某个会话的文件；Anthropic 使用该筛选时需要 `anthropic-beta: managed-agents-2026-04-01` 请求头。

## 过期 [#过期]

不设置过期时间的上传文件保留到被删除。`expires_after` 从 `created_at` 起计算秒数，响应中的 `expires_at` 是到期时间。过期文件不能再读取或引用。可用范围见[限额与错误](/docs/cloud/services/file/limits-and-errors)。

## 下载安全 [#下载安全]

下载内容被识别为 HTML、SVG、XML 或 JavaScript 时，以附件下发，并设置 `X-Content-Type-Options: nosniff`。类型按内容识别，不依赖扩展名：上传的 HTML 或 SVG 也可能被识别为纯文本并以纯文本返回。下载不会执行其中的内容。

## 分段下载 [#分段下载]

内容下载支持单个 `Range` 区间：`bytes=0-1023`、`bytes=1024-`（从某处到结尾）或 `bytes=-1024`（最后 1024 字节）。命中时返回 206 和 `Content-Range`；区间超出文件大小返回 416。所有下载响应都带 `Accept-Ranges: bytes`，可用于断点续传和音视频拖动。

[API 参考 →](/docs/api/native/file) · [Cookbook →](/docs/cookbook)