Claude Files API：上传一次，处处引用（正式版指南）

Claude Files API 允许你把文件上传到 https://api.anthropic.com/v1/files 一次，拿回 file_id，之后在任何 Messages 请求中引用该 ID，无需重复发送文件内容。截至 2026 年 8 月 20 日，它已在 Claude Platform 正式可用：无需 beta 请求头，每组织 1 TB 存储，速率限制是 beta 期的五倍。Anthropic 在生产级 Agent 公告中宣布了该变化，同时转正的还有 computer use、浏览器工具和 Skills API。

本文覆盖完整生命周期：上传、在消息中引用、下载生成文件、过期机制、工作区安全模型，以及生产环境中的限制。每一步都是 HTTP 调用，因此编码 Agent 可以把流程变成 Apifox CLI 测试场景，而不是一堆一次性 curl。

Files API 能做什么

Files API 是 Claude API 的“创建一次、多次使用”存储层。它解决一个具体成本：应用在数百次请求中针对同一份 40 页 PDF 提问时，每次重新上传会浪费带宽并让客户端更复杂。使用 Files API，你可以：

• 上传文件到 Anthropic 存储，获得唯一 file_id
• 通过内容块在 Messages 请求中引用该 ID
• 下载 skills 或代码执行工具生成的文件（图表、电子表格、演示文稿）
• 通过列表、获取元数据和删除操作管理文件

端点很少：

全部使用标准 x-api-key 和 anthropic-version: 2023-06-01 请求头。如果你还不熟悉 Messages API，Claude Opus 5 API 指南介绍了认证和请求结构。

正式版带来了哪些变化

Files API 在 beta 阶段需要额外请求头，持续了数月。2026 年 8 月 20 日正式版改变了四件影响生产规划的事：

1. 不再需要 beta 请求头。 标准请求头即可使用。
2. 速率限制提高 5 倍。 文件操作约每分钟 500 次请求，更高额度可联系销售。
3. 每组织 1 TB 存储，单文件上限 500 MB。
4. 平台覆盖更广。 支持 Claude API、beta 阶段的 Claude Platform on AWS，以及使用 Hosted on Anthropic 部署的 Microsoft Foundry。不适用于 Amazon Bedrock 或 Google Cloud Vertex AI，也不适用于零数据保留协议。

上传文件

上传使用 multipart 表单，而不是 JSON：

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@/path/to/report.pdf"

响应包含后续引用所需的全部信息：

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "report.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2026-08-24T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

两个字段值得注意。你上传的文件 downloadable 都是 false；只有 Claude 通过 skills 或代码执行生成的文件才能下载。除非上传时设置过期时间，否则 expires_at 为 null。

下文的 Apifox CLI 测试会把 id 保存为变量，后续请求引用 {{claude_file_id}}，而不是硬编码字符串。

在 Messages 请求中引用文件

上传后，文件会根据类型通过三种内容块之一接入请求：

PDF 摘要请求示例：

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Summarize this document."},
        {"type": "document", "source": {"type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"}}
      ]
    }]
  }'

document 块还接受可选的 title、context 和 citations 字段，因此可以针对已上传文件启用引用输出。图片请把块类型换成 image，source 结构不变。电子表格、需要分析的 CSV，或 document 不支持的格式，请用 container_upload 交给代码执行工具。

document 块不直接支持 .docx 和 .xlsx。把 Word 转成 PDF 可保留图片解析和引用；也可以提取纯文本后内联发送。

下载生成的文件

下载端点用于输出，而不是输入。Claude 通过代码执行生成图表，或通过 skill 生成电子表格时，响应会在 bash_code_execution_tool_result 块中包含 file_id，该 ID 可下载：

curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  --output chart.png

尝试下载自己上传的文件会返回 400。为下载逻辑加重试前，先检查元数据中的 downloadable 标志。这个“上传输入、生成输出”的循环正是 Skills API 工作流的骨架：skills 生成 Office 文档，你再通过同一端点拉取。Claude Skills 指南介绍了 skills 是什么以及如何执行。

过期与文件生命周期

文件会保留到删除或到达上传时设置的过期时间：

• 上传时以表单字段传入 expires_in_seconds，范围 3,600（1 小时）到 7,776,000（90 天）。只能设置一次，之后无法更改。
• expires_at 过后，内容下载返回 404，引用该文件的 Messages 请求会在推理前失败。
• 元数据在过期后最多仍可读取 30 天，过期文件在这段时间内仍会出现在列表响应中。过滤时请比较 expires_at 与当前时间。
• 删除立即生效且不可撤销。过期内容会从存储配额释放，但可能短暂保留用于安全审查，因此过期是生命周期工具，不是保证删除的控制手段。

安全模型：文件按工作区隔离

上传文件对整个工作区可见，而不是按最终用户、对话或会话隔离。同一工作区的任何 API 密钥都能读取其中的文件；除非分配到其他工作区，所有密钥都共享组织的 Default Workspace。

实用规则：

• 绝不接受最终用户传入的 file_id。 否则一个用户可以读取另一个用户的文件。把文件 ID 当作服务端引用，在数据库中维护用户与文件的映射。
• 多租户应用，每个租户一个工作区。 工作区是隔离边界。每组织最多 100 个工作区，Anthropic 客户团队可以上调。

如果你已按租户跟踪 API 密钥做成本归因（见如何降低 Claude API 账单），同样的工作区布局可以免费带来文件隔离。

限制与计费

上传、下载、列出和删除文件全部免费。只有文件内容进入 Messages 请求时才计费，按普通输入 token 计价。一份 100 页 PDF 在十次请求中引用，会产生十次相同的输入 token 费用；Files API 节省的是带宽和客户端复杂度，不是 token。要在 token 侧省钱，请配合提示缓存。

常见错误：文件超过 500 MB 返回 413；组织达到 1 TB 上限返回 400；文件类型与内容块不匹配返回 400（例如图片放进 document）；ID 不在工作区返回 404。

让 Claude Code 用 Apifox CLI 测试 Files API

Files API 是多步骤、有状态的流程，值得写成回归测试。Claude Code 或任何编码 Agent 都可以通过 Apifox CLI 构建并运行测试。先完成一次性配置：

npm install -g apifox-cli@latest
apifox login --with-token <YOUR_TOKEN>
npx -y skills add https://apifox.com   # 按提示选择你的 Agent

令牌来自 Apifox 的 Account Settings > API Access Token。然后给 Agent 一段提示：

Use Apifox CLI on project <id>. Add the Files API endpoints (upload, list,
metadata, download, delete) and POST /v1/messages, with x-api-key from
{{ANTHROPIC_API_KEY}} and the anthropic-version header. Build a test scenario:
upload with expires_in_seconds=3600 and assert expires_at is set, save the id
as claude_file_id, reference it in a Messages call and assert 200, delete it,
then assert the metadata call returns 404. Run it and summarize any failures.

它运行的命令（对照 Apifox CLI 2.2.7）：

apifox cli-schema get endpoint-create
apifox endpoint create --project <id> --file files-upload.json
apifox test-scenario create --project <id> --name "Files API lifecycle" --priority 1
apifox test-scenario import-steps <scenarioId> --project <id> --source endpoint \
  --ids <uploadId>,<messagesId>,<deleteId>,<metadataId> --sync manual
apifox cli-schema validate test-scenario-update --file lifecycle.json
apifox test-scenario update <scenarioId> --project <id> --file lifecycle.json
apifox run -t <scenarioId> --project <id> -e <envId> \
  --env-var "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" -r cli,json

Agent 会对每个端点重复 endpoint create，再把变量提取和断言写入场景。以后切换测试文件，只需改一个上传步骤，而不是每个请求。还可以让 Agent 为上传响应生成 mock（apifox mock create），让前端在后端代理存在前拿到 JSON 结构。同样的 apifox run 加 -r junit 可接入 CI；Claude Code 中的 Apifox CLI指南覆盖 Agent 配置。

常见问题

还需要 beta 请求头吗？ 不需要。自 2026 年 8 月 20 日正式版起，Files API 使用标准 x-api-key 和 anthropic-version 请求头。如果 SDK 或代理仍固定携带旧 beta 请求头，升级时移除。

可以更新文件内容吗？ 不可以。文件上传后不可变。请上传新文件，把引用指向新 ID，再删除旧文件。

Files API 能在 Bedrock 或 Vertex AI 上使用吗？ 不能。它可用于 Claude API、Claude Platform on AWS（beta），以及使用 Hosted on Anthropic 部署的 Microsoft Foundry。在 Bedrock 和 Vertex 上仍需内联 base64。

Files API 和 Skills API 的输出存储是同一个吗？ 是。Skills 和代码执行工具把生成的文档写入同一文件存储，你通过 GET /v1/files/{file_id}/content 下载。该工作流的 Skills API 部分适合配合自动化测试。

总结

Files API 转正后，把同一份文档用 base64 塞进每个请求的借口没有了。上传一次，按 ID 引用，设置过期时间，并把租户文件放在独立工作区。API 只有五个端点，每个都能在几分钟内测试：让编码 Agent 用 Apifox CLI 编写流程，通过变量串联 file_id，在用户发现边界情况前把生命周期检查纳入 CI。