本文根据 Claude 官方《Files API》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。代码里的模型名取自官方当天示例，请以官方模型页为准。本站（bigolab.com）不是 Anthropic 官方网站。API 是按用量计费的独立服务，与 Claude 订阅分开计算，Key 的获取见 /guides/claude-api-key-console。
适用于谁
- 同一份 PDF、图片要在很多请求里反复使用的开发者；
- 多轮对话里带图片，发现请求体越来越大、越来越慢的人；
- 要用代码执行工具分析数据文件，并下载生成结果（图表、报告）的人。
结论先说
- 上传一次拿到
file_id，之后只引用编号，不再重传文件内容。 - 引用写法：PDF 和纯文本用
document块，图片用image块，source都是{"type": "file", "file_id": "..."}。 - 单文件最大 500 MB，每个组织总存储 1 TB。
- 你上传的文件不能下载；只有技能或代码执行工具生成的文件可以下载。
- 文件对整个工作区可见，所以绝不能接受用户传来的
file_id，这是官方的明确警告。 - 上传、下载、列表、删除都免费，文件内容在请求里用到时按输入 token 计费。
图：本站根据 Claude 官方《Files API》 整理的示意图
一、上传文件
Python：
python
import anthropic
client = anthropic.Anthropic()
uploaded = client.files.upload(
file=("document.pdf", open("document.pdf", "rb"), "application/pdf"),
)
print(uploaded.id)TypeScript：
typescript
import fs from "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";
const client = new Anthropic();
const uploaded = await client.files.upload({
file: await toFile(fs.createReadStream("document.pdf"), undefined, {
type: "application/pdf",
}),
});
console.log(uploaded.id);官方提醒，TypeScript 里要显式指定内容类型，因为 Files API 不会替你推断。返回的元数据里有 id、filename、mime_type、size_bytes、created_at、downloadable 和 expires_at。上传的文件 downloadable 是 false。
二、在请求里引用
python
response = client.messages.create(
model="claude-opus-5-5", # 以官方模型页当天为准
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "请总结这份文件。"},
{
"type": "document",
"source": {"type": "file", "file_id": uploaded.id},
},
],
}
],
)文件类型和内容块的对应：
| 文件类型 | MIME 类型 | 内容块 |
|---|---|---|
application/pdf | document | |
| 纯文本 | text/plain | document |
| 图片 | image/jpeg、image/png、image/gif、image/webp | image |
| 数据集等其他文件 | 不一 | container_upload（配合代码执行工具） |
document 块还有三个可选字段：title、context，以及 citations（设 {"enabled": true} 启用引用）。docx、xlsx 这类二进制格式不能放进 document 块，需要先转成文字或 PDF。PDF 的详细规则见 /guides/claude-api-pdf-support，图片见 /guides/claude-api-image-input。
三、管理文件
- 列表：
client.files.list()，按创建时间由新到旧，默认一页 20 个，最多 1000 个；SDK 提供自动翻页。想一次核对已知的一批文件，可以最多传 100 个ids[]参数，不存在的编号会被静默忽略，要自己对照返回结果； - 元数据：Python 是
client.files.retrieve_metadata(file_id)，TypeScript 是client.files.retrieveMetadata(id)； - 删除：
client.files.delete(file_id)。删除后无法恢复，文件在删除后很快无法通过 API 访问，但可能仍存在于正在进行的 Messages 调用中； - 修改：文件创建后不能改内容也不能改名，想换内容只能重新上传、再删除旧的。
四、下载：只有生成的文件可以
图：本站根据 Claude 官方《Files API》 整理的示意图
官方规定：只有技能或代码执行工具创建的文件能下载，元数据里 downloadable 为 true。你自己上传的文件下载会返回 400。生成文件的 file_id 出现在产生它的那次 Messages 响应的 bash_code_execution_tool_result 内容块里。Python 下载的写法是：
python
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")五、限制和过期
- 大小：单文件最大 500 MB；每个组织总存储 1 TB；
- 文件名：1 到 255 个字符，不能包含
<、>、:、"、|、?、*、\、/以及控制字符； - 速率：文件相关调用约每分钟 500 次请求，需要更高请联系官方销售；
- 过期：上传时可加表单字段
expires_in_seconds，范围是 3600 秒（1 小时）到 7776000 秒（90 天）。到期后，下载返回 404，引用它的 Messages 请求会在推理前失败，元数据最多还能读 30 天，expires_at的值在过去。过期时间只能在上传时设置，之后不能改。官方强调，过期是生命周期功能，不是保证删除的手段；想提前删除，用DELETE； - 大小超窗口：文件内容仍受模型上下文窗口限制，比如把 500 MB 的纯文本放进请求会报 400。
六、最重要的安全提醒
官方用警告框强调：上传的文件对整个工作区可见。 文件不是绑定到某个终端用户、某次对话或某个会话的，任何有权访问该工作区的 API 密钥，都能访问其中所有文件。因此：
- 绝不要接受来自终端用户或其他不可信来源的
file_id。 否则一个用户可以通过编号读到另一个用户上传的内容。file_id应当当作服务端内部的引用，用户和文件的对应关系由你自己的应用保存； - 必须隔离的文件，放进单独的工作区，并用只属于该工作区的密钥访问；
- 做多租户应用，官方建议每个租户一个工作区，工作区就是文件的隔离边界；每个组织最多 100 个工作区，不够可联系官方。
七、费用、保留与迁移说明
- 费用：上传、下载、列表、取元数据、删除都免费；文件内容在 Messages 请求里用到时按输入 token 计价，价格以官方价格页当天为准；
- 保留：官方标明 Files API 不符合零数据保留资格，文件会保留到你删除或它过期为止；
- beta 变化：Files API 已脱离 beta，不再需要
anthropic-beta请求头。仍带旧请求头files-api-2025-04-14的请求继续可用，但返回旧的 beta 响应形状（比如列表用before_id、after_id）；去掉请求头后列表改用page和next_page游标，expires_at总会返回。SDK 里建议用client.files，而不是旧的client.beta.files，具体 SDK 版本要求见官方迁移说明。
常见问题
Q：文件报 413 或 400？
文件超过 500 MB 返回 413；文件类型和内容块不匹配、放进 document 块的是二进制格式、内容超过上下文窗口，都会返回 400。整体排查见 /guides/claude-api-error-codes。
Q：为什么引用文件报 404？
编号不存在、不在当前工作区，或文件已过期。
Q：每次上传要不要重复？
同一份文件在同一工作区只要上传一次，保存好 file_id，直到你删除它或它过期。
Q：和提示词缓存是什么关系？
文件引用解决的是“不重传”，缓存解决的是“不重复计算同一段前缀”，两者可以配合，缓存见 /guides/claude-prompt-caching。
参考资料
- Claude 官方：Files API — https://platform.claude.com/docs/en/build-with-claude/files
- Claude 官方：PDF support — https://platform.claude.com/docs/en/build-with-claude/pdf-support
0 条评论
还没有评论，来抢沙发～