Files API

Files API 让您可以上传和管理文件以便与 Claude API 一起使用，而无需在每次请求时重新上传内容。这在使用代码执行工具提供输入（例如数据集和文档）然后下载输出（例如图表）时特别有用。除本指南外，您还可以直接浏览 API 参考。

文件类型支持

在 Messages 请求中引用 file_id 在所有支持给定文件类型的模型上均受支持。图像在所有当前的 Claude 模型上均受支持。对于 PDF 和代码执行工具支持的其他文件类型，请参阅链接页面了解模型支持情况。

Files API 的工作原理

Files API 提供了一种"创建一次、多次使用"的文件处理方式：

• 上传文件到 Anthropic 的安全存储并获得唯一的 file_id
• 下载文件，这些文件由 skills 或代码执行工具创建
• 引用文件，在 Messages 请求中使用 file_id 而不是重新上传内容
• 管理您的文件，通过列出、检索和删除操作

如何使用 Files API

上传文件

上传文件以便在将来的 API 调用中引用：

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

上传文件的响应包括：

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

对于您上传的文件，downloadable 为 false。只有由 skills 或代码执行工具创建的文件才能下载。请参阅下载文件。

在消息中使用文件

上传后，通过将上传响应中的 id 作为 file_id 传递来引用该文件：

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": file_id,
                    },
                },
            ],
        }
    ],
)
print(response)

文件类型和内容块

Files API 支持不同的文件类型，它们对应不同的内容块类型：

文档块

对于 PDF 和文本文件，使用 document 内容块：

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}

图像块

对于图像，使用 image 内容块：

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

容器上传块

要将文件发送到代码执行工具，使用 container_upload 内容块：

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}

处理其他文件格式

对于 document 块不支持的文件类型（例如 .docx 和 .xlsx），请将文件转换为纯文本并将内容直接包含在您的消息中。已经是纯文本的文件（例如 .csv 和 .md 文件）既可以通过这种方式读取，也可以通过 Files API 以显式的 text/plain 内容类型上传。若要分析数据集而不是将其作为文本读取，请使用 container_upload 块将其上传给代码执行工具。

以下示例读取一个文本文件并将其内容作为纯文本发送：

client = anthropic.Anthropic()

# 读取文本文件
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

管理文件

列出文件

检索您已上传文件的列表。该端点是分页的：每个请求最多返回 limit 个文件（默认 20 个，最多 1,000 个），响应中的 next_page 游标在作为 page 参数传回时可获取下一页。文件按最新优先排序。请参阅列出文件 API 参考。SDK 返回第一页并提供自动分页辅助工具。CLI 示例使用 --max-items 限制总数：

client = anthropic.Anthropic()
files = client.files.list()
print(files)

若要在一个请求中检查一组已知文件而不是分页，请将最多 100 个文件 ID 作为 ids[] 查询参数传递。ids[] 请求始终返回单个页面（next_page 为 null），任何无法解析为您工作区中文件的 ID 都会从 data 中被静默省略；请将返回的 ID 与请求的 ID 进行比较以检测缺失项。ids[] 不能与 page 或 limit 组合使用。

获取文件元数据

检索特定文件的信息：

file = client.files.retrieve_metadata(file_id)
print(file)

删除文件

从您的工作区中移除文件：

client.files.delete(file_id)

下载文件

下载由 skills 或代码执行工具创建的文件。您上传的文件无法下载。生成文件的 file_id 出现在创建它的 Messages 响应的 bash_code_execution_tool_result 内容块中：

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

在 Claude API 上，Claude 使用代码执行工具生成的受支持的图像和视频文件（包括由 skills 创建的文件）在您下载时会携带已签名的 C2PA 内容凭证（Content Credentials）。请参阅生成文件上的内容凭证了解凭证包含的内容以及如何验证它。

文件存储和限制

存储限制

• 最大文件大小： 每个文件 500 MB
• 总存储量： 每个组织 1 TB

文件生命周期

• 文件限定于其上传所在的工作区。同一工作区中的任何请求都可以引用它们；切勿接受来自不受信任来源的文件 ID（请参阅工作区访问警告）
• 文件上传后无法修改或重命名。要更改文件的内容，请上传新文件并删除旧文件
• 文件会一直保留，直到您使用 DELETE /v1/files/{file_id} 端点删除它们，或它们到达其 expires_at
• 已删除的文件无法恢复
• 文件在删除后不久即无法通过 API 访问，但它们可能仍存在于活跃的 Messages API 调用和相关的工具使用中
• 用户删除的文件将根据 Anthropic 的数据保留政策进行删除。有关所有功能的 ZDR 资格，请参阅 API 和数据保留

文件过期

要让文件自动过期，请在上传时包含一个 expires_in_seconds 表单字段。该值是一个介于 3,600（1 小时）和 7,776,000（90 天）之间的整数秒数。生成的 expires_at 时间戳（RFC 3339）出现在每个文件响应中，对于未设置过期时间上传的文件则为 null。过期时间在上传时设置一次，之后无法更改。

当文件到达其 expires_at 时：

• 下载其内容（GET /v1/files/{file_id}/content）会返回 404 错误
• 引用该文件的 Messages 请求会在推理之前失败
• 其元数据（GET /v1/files/{file_id}）在最多 30 天内仍可读取，其中 expires_at 为过去的时间
• 在该时间窗口内，它会继续出现在列表响应中；请将 expires_at 与当前时间进行比较以过滤已过期的文件

使用 DELETE /v1/files/{file_id} 删除已过期的文件会立即移除其元数据，而无需等待 30 天窗口期结束。

审计日志

如果您的组织启用了 Compliance API，其活动源（Activity Feed）会记录使用 Claude API 密钥或从 Claude Console 进行的 Files API 操作：每次上传（POST /v1/files）、内容下载（GET /v1/files/{file_id}/content）和删除（DELETE /v1/files/{file_id}）分别显示为 platform_file_uploaded、platform_file_content_downloaded 或 platform_file_deleted 活动。列出文件和检索文件元数据不会被记录。在 Compliance API 关闭期间发生的操作不会被记录，且之后无法恢复，因此在依赖此审计记录之前，请先设置 Compliance API。在 Claude Platform on AWS 上，请改用 AWS CloudTrail 数据事件来审计文件操作。

从 files-api-2025-04-14 迁移

Files API 已结束 beta 阶段，不再需要 beta 标头。从 files-api-2025-04-14 迁移是可选的：仍然发送该标头的请求会继续正常工作并继续返回 beta 响应结构，因此现有集成在您更改之前会一直正常工作。移除该标头会将这些请求切换为本页所记录的结构：

迁移步骤：

1. 移除 beta 标头。 从您的请求中删除 anthropic-beta: files-api-2025-04-14。在 SDK 中，调用 client.files 而不是 client.beta.files；继续使用 client.beta.files 仅在不再发送该标头的 SDK 版本上有效。更早的版本即使没有 betas 参数也会从 client.beta.files 发送该标头。
2. 更新分页。 将 after_id/before_id 循环替换为 page/next_page 游标，或使用管理文件中展示的 SDK 自动分页辅助工具。
3. 读取 expires_at。 该字段仅在不使用该标头时出现；null 表示文件没有过期时间（请参阅文件过期）。

SDK beta 命名空间

从 Python SDK 1.2.0、TypeScript SDK 0.122.0、Go SDK 1.68.0、Java SDK 2.59.0、Ruby SDK 1.67.0 和 C# SDK 12.44.0 开始，client.beta.files 不再发送 files-api-2025-04-14，并返回与 client.files 相同的结构，类型名称带有 Beta 前缀。它接受一个 betas 参数，用于仍处于 beta 阶段的 Files 功能，例如在 Managed Agents beta 标头下的 scope_id 过滤。更早的 SDK 版本的类型定义对应 beta 结构；如果您依赖这些类型，请在迁移之前继续使用更早的版本。

携带 anthropic-beta: managed-agents-2026-04-01 但不携带 files-api-2025-04-14 的请求会收到本页所述的结构，并在 GET /v1/files 上有一项兼容性便利：before_id 和 after_id 仍被接受（不能与 page 或 ids[] 组合使用），且列表响应除 next_page 外还包含 has_more、first_id 和 last_id。更高版本的 Managed Agents beta 会收到普通结构。

错误处理

使用 Files API 时的常见错误包括：

• 文件未找到（404）： 指定的 file_id 不存在或您无权访问它
• 无效的文件类型（400）： 文件类型与内容块类型不匹配（例如，在文档块中使用图像文件）
• 不可下载（400）： 您上传的文件具有 "downloadable": false，无法下载。只有由 skills 或代码执行工具创建的文件才能下载
• 超出上下文窗口大小（400）： 文件大于上下文窗口大小（例如，在 /v1/messages 请求中使用 500 MB 的纯文本文件）
• 无效的文件名（400）： 文件名不符合长度要求（1-255 个字符）或包含禁用字符（<、>、:、"、|、?、*、\、/ 或 Unicode 字符 0-31）
• 文件过大（413）： 文件超过 500 MB 限制
• 超出存储限制（400）： 您的组织已达到 1 TB 存储限制

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

使用和计费

Files API 操作是免费的：

• 上传文件
• 下载文件
• 列出文件
• 获取文件元数据
• 删除文件

在 Messages 请求中使用的文件内容按输入令牌计费。

速率限制

与文件相关的 API 调用限制为每分钟约 500 个请求。如需申请更高的限制，请联系销售。

后续步骤

Compatibility