Files API

Files API 允许您上传和管理文件，以便在 Claude API 中使用，而无需在每次请求时重新上传内容。这在使用代码执行工具时特别有用，可以提供输入（例如数据集和文档），然后下载输出（例如图表）。您还可以使用 Files API 避免在多个 API 调用中反复重新上传常用的文档和图片。除了本指南外，您还可以直接查阅 API 参考文档。



支持的模型

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

Files API 可在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 上使用。目前在 Amazon Bedrock 或 Vertex AI 上不可用。



Files API 的工作原理

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

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



如何使用 Files API



上传文件

上传文件以便在后续 API 调用中引用：

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

上传文件的响应将包含：

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



在消息中使用文件

上传后，使用文件的 file_id 引用该文件：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)



文件类型和内容块

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



处理其他文件格式

对于不支持作为 document 块的文件类型（.csv、.txt、.md、.docx、.xlsx），请将文件转换为纯文本，并将内容直接包含在您的消息中：

import pandas as pd
# ...
# 示例：读取 CSV 文件
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# 作为纯文本在消息中发送
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)



Document 块

对于 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 块

对于图片，请使用 image 内容块：

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



管理文件



列出文件

检索您已上传文件的列表：

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



获取文件元数据

检索特定文件的信息：

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



删除文件

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

result = client.beta.files.delete(file_id)



下载文件

下载由技能或代码执行工具创建的文件：

file_content = client.beta.files.download(file_id)

# Save to file
file_content.write_to_file("downloaded_file.txt")



文件存储和限制



存储限制

• 最大文件大小： 每个文件 500 MB
• 总存储空间： 每个组织 500 GB



文件生命周期

• 文件的作用域限定在 API 密钥所属的工作区。其他 API 密钥可以使用由同一工作区关联的任何其他 API 密钥创建的文件
• 文件会一直保留，直到您删除它们
• 已删除的文件无法恢复
• 文件在删除后很快将无法通过 API 访问，但它们可能会在活跃的 Messages API 调用及相关工具使用中继续存在
• 用户删除的文件将按照 Anthropic 的数据保留政策进行删除。



数据保留

通过 Files API 上传的文件会一直保留，直到使用 DELETE /v1/files/{file_id} 端点显式删除。文件会被存储以便在多个 API 请求中重复使用。

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。



错误处理

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

• 文件未找到（404）： 指定的 file_id 不存在，或您无权访问该文件
• 无效的文件类型（400）： 文件类型与内容块类型不匹配（例如，在 document 块中使用图片文件）
• 超出上下文窗口大小（400）： 文件大于上下文窗口大小（例如，在 /v1/messages 请求中使用 500 MB 的纯文本文件）
• 无效的文件名（400）： 文件名不符合长度要求（1-255 个字符）或包含禁用字符（<、>、:、"、|、?、*、\、/ 或 Unicode 字符 0-31）
• 文件过大（413）： 文件超过 500 MB 限制
• 超出存储限制（403）： 您的组织已达到 500 GB 存储限制

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}



使用和计费

文件 API 操作是免费的：

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

在 Messages 请求中使用的文件内容按输入令牌计费。您只能下载由技能或代码执行工具创建的文件。



速率限制

在测试期间：

• 与文件相关的 API 调用限制为每分钟约 100 个请求
• 如果您的使用场景需要更高的限制，请联系我们