Claude Files API 使用指南：上传复用、多租户隔离与文件过期

Claude Files API 的核心价值是把文件上传和模型调用拆开：文件只上传一次，后续 Messages 请求通过 file_id 重复引用。但它并不会自动替你解决用户级权限，也不会让后续文件内容免除输入 token 计费。对多租户应用，最重要的第一步不是写上传代码，而是先划定 workspace 隔离边界；对临时文件，则应在上传时确定过期时间。本文依据 Anthropic 2026 年 8 月 24 日的官方文档整理，示例未在生产账号中实测。

当前状态：Anthropic 于 2026 年 8 月 20 日宣布 Files API 正式 GA，同时加入自动过期、约 5 倍更高的文件 API 速率限制和组织级 1 TB 存储。旧 beta 集成可以继续工作并逐步迁移；新项目应以当前官方文档和所用 SDK 的现行命名空间为准。

它解决什么

过去如果同一份 PDF、图片或数据集要参与多轮任务，应用往往需要反复传输文件。Files API 把文件放进 Claude Platform 的存储，返回唯一的 file_id；之后可以在不同 Messages 请求中引用这个 ID，还能通过 list、metadata 和 delete 操作管理生命周期。

这能减少重复上传和应用侧传输逻辑，但有三件事不会因此自动发生：

• 不会免除推理费用：上传、列举、读取元数据、删除以及可下载文件的下载操作本身免费；文件内容进入 Messages 请求后仍按输入 token 计费。
• 不会按最终用户隔离：文件属于上传 API key 所在的 workspace，同一 workspace 内的其他 API key 也能引用。
• 不会把所有格式直接变成 document：PDF、纯文本、图片和供 code execution 使用的数据集对应不同 content block。

如果只是偶尔分析一个小文件，直接随单次请求传入可能更简单。Files API 更适合重复引用、需要集中列举/删除、要给 Skills 或 code execution 提供输入，或者必须管理明确过期时间的工作流。

上传并复用

前置条件是服务端持有 Claude API key，并使用支持当前 Files API 的 Anthropic SDK。API key 不应进入浏览器或移动端；file_id 也应作为服务端引用保存，不应由客户端自由指定。

上传文件

当前 Python 文档使用 client.files.upload。以下代码只展示上传与保存 ID，模型名称应由应用配置提供，不要在长期代码里锁死本文核验时的示例模型。

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("document.pdf", "rb") as source:
    uploaded = client.files.upload(
        file=("document.pdf", source, "application/pdf"),
    )

file_id = uploaded.id
# 在服务端数据库保存 tenant_id / user_id -> file_id 映射
print(file_id)

上传结果包含文件名、MIME type、字节大小、创建时间、downloadable 和 expires_at。文件上传后不能直接修改或重命名；内容变化时，需要上传新文件、验证新 ID，再替换应用中的映射。

在消息中引用

response = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "请概括这份文档的关键结论。"},
            {
                "type": "document",
                "source": {
                    "type": "file",
                    "file_id": file_id,
                },
            },
        ],
    }],
)

调用前应先用当前登录用户和租户查询服务端映射，再把查询得到的 file_id 放入请求。不要接收前端传来的任意 ID 后直接转发给 Claude API。旧教程可能仍展示 client.beta.files 和 files-api-2025-04-14 beta header；Anthropic 已说明既有 beta 集成迁移期间仍可工作，但新代码应跟随当前 SDK 文档。

文件类型

.docx 和 .xlsx 不能简单假定为 document block。官方建议将可读文本转换为纯文本；包含图片的 Word 文档可先转成 PDF。如果目标是分析表格数据，应考虑 container_upload，而不是把整个二进制文件伪装成文本。

隔离租户

Files API 最容易被低估的风险是访问范围。官方文档明确说明：上传文件对整个 workspace 可访问，不按最终用户、对话或会话隔离。默认情况下，组织中的 key 还可能共享 Default Workspace。

危险设计：把所有客户放在同一 workspace，让浏览器提交 file_id，后端只检查字符串格式就发起 Messages 请求。攻击者一旦得到其他文件 ID，就可能让应用读取另一个用户上传的内容。

官方建议的硬隔离：多租户应用为每个租户建立独立 workspace，并为 API key 指定对应 workspace。应用数据库仍要保存租户、用户、业务对象和文件 ID 的映射，但这属于授权检查；真正阻断跨租户文件访问的是 workspace 边界。

1. 请求进入后，从认证上下文确定 tenant_id，不要相信请求体中的租户字段。
2. 选择该租户对应 workspace 的服务端凭据。
3. 只从该租户自己的数据库记录中读取 file_id。
4. 操作前校验文件状态、用途和有效期；操作后记录调用与删除事件。

每个组织默认最多 100 个 workspace，归档的 workspace 不计入该默认上限；需要更多时应联系 Anthropic account team。不要因为租户数超过 100，就自行把共享 workspace 宣称为同等级的硬隔离方案。

过期与替换

临时文件可以在上传时填写 expires_in_seconds，允许范围为 3600 秒（1 小时）至 7776000 秒（90 天）。该值设置一次后不能修改；未设置时，expires_at 为 null，文件会持续存在，直到主动删除。

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@document.pdf" \
  -F "expires_in_seconds=86400"

这里的 86400 表示 24 小时。上线前应按数据用途选择寿命，而不是统一给所有文件 90 天。一次性转换可用小时级；短期协作可按业务周期设置；长期知识库文件则应结合内容更新与删除策略决定是否不设自动过期。

到达 expires_at 后，内容下载返回 404，引用该文件的 Messages 请求会在推理前失败，存储配额也会释放；但元数据最多仍可读取和出现在列表中 30 天。底层内容还可能因安全审查在有限时间内保留。因此，过期是生命周期控制，不是“到点立即物理擦除”。Files API 当前也标注为不符合 Zero Data Retention。

更换有效期

有效期不能原地延长或缩短。安全替换顺序是：

1. 上传同一内容的新文件，并设置新的过期时间。
2. 用代表性 Messages 请求验证新 file_id 可用。
3. 以事务或可回滚配置把业务映射切换到新 ID。
4. 观察没有旧任务继续引用后，再删除旧文件。

删除不可恢复。如果上传新文件或验证失败，保留旧映射即可回滚；不要先删除旧文件再尝试上传替代项。

下载与计费

“Files API 支持下载文件”只适用于元数据中 downloadable:true 的产物，也就是 Skills 或 code execution 创建的文件。你主动上传的文件通常是 downloadable:false，调用下载端点会返回 400。应用如果需要让用户重新取得原始上传文件，应在自己的对象存储中保留授权副本，而不是把 Files API 当成通用下载网盘。

文件上限与上下文窗口不是一回事。例如 500 MB 纯文本即使上传成功，也可能在 Messages 请求中因超过上下文窗口而返回 400。应在上传前限制文件用途与大小，并在进入推理前做页数、字符数或数据集规模检查。

上线检查

• API key 是否只存在服务端，并明确绑定 workspace？
• 是否拒绝来自最终用户或不可信来源的任意 file_id？
• 多租户是否按 workspace 隔离，并保存 tenant → workspace → file 的服务端映射？
• 是否根据 MIME 和任务选择 document、image 或 container_upload？
• 临时文件是否在上传时设置有效期，长期文件是否有主动删除策略？
• 替换文件时是否先上传并验证新 ID，再切换映射，最后删除旧文件？
• 下载前是否检查 downloadable，没有把上传文件误当成可下载对象？
• 是否把每次 Messages 的文件输入 token 纳入预算，而不是只看文件操作免费？
• 是否处理 400、404、413、存储满额和速率限制，并避免对不可恢复删除盲目重试？
• 隐私要求是否允许使用当前不符合 ZDR 的 Files API？

想先了解 Claude 产品入口和普通使用范围，可以查看 WarpNav 的 Claude AI 详情页。Files API 属于开发者平台能力，不应与 Claude.ai 对话中的附件功能混为一谈。

主要官方资料（核验于 2026 年 8 月 24 日）：GA 公告 https://claude.com/blog/computer-use-skills-api-files-api；Files API 文档 https://platform.claude.com/docs/en/build-with-claude/files；Workspace 文档 https://platform.claude.com/docs/en/manage-claude/workspaces。配额、速率、SDK 命名空间、平台支持和数据保留资格可能变化，实施前请再次回读当前官方文档。