概念
用途、引用、过期与下载。
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/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 当前不能作为对话图片输入。参见图片引用示例。 - 素材库：用
file_id导入，生成素材记录。参见素材 API。 - 知识库：将
file_id加入库后，才会提取内容并建立索引。参见知识库概念。 - 智能体：用
type: "file"、file_id和mount_path将文件加入会话资源。仅设置purpose=assistants不会挂载文件。参见会话资源 API。
会话输出文件的元数据可包含 scope、relative_path 和 revision。用 scope_id 列出某个会话的文件；Anthropic 使用该筛选时需要 anthropic-beta: managed-agents-2026-04-01 请求头。
过期
不设置过期时间的上传文件保留到被删除。expires_after 从 created_at 起计算秒数，响应中的 expires_at 是到期时间。过期文件不能再读取或引用。可用范围见限额与错误。
下载安全
下载内容被识别为 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，可用于断点续传和音视频拖动。