文件 API

Files API

文件 API 让你可以上传和管理文件以与 Claude API 一起使用，而无需在每次请求时重新上传内容。这在使用代码执行工具提供输入（例如数据集和文档）然后下载输出（例如图表）时特别有用。你也可以使用文件 API 来避免在多个 API 调用中不断重新上传经常使用的文档和图像。你可以直接探索 API 参考，除了本指南之外。

文件 API 处于测试阶段。通过反馈表单分享你对文件 API 的体验。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

支持的模型

在 Messages 请求中引用 file_id 在所有支持给定文件类型的模型中都受支持。例如，图像在所有 Claude 3+ 模型中受支持，PDF 在所有 Claude 3.5+ 模型中受支持，以及各种其他文件类型用于 Claude Haiku 4.5 及所有 Claude 3.7+ 模型中的代码执行工具。

文件 API 目前在 Amazon Bedrock 或 Google Vertex AI 上不受支持。

文件 API 如何工作

文件 API 提供了一种简单的一次上传、多次使用的方法来处理文件：

上传文件到 Anthropic 的安全存储并接收唯一的 file_id
下载文件由技能或代码执行工具创建
在 Messages 请求中引用文件使用 file_id 而不是重新上传内容
管理你的文件通过列表、检索和删除操作

如何使用文件 API

要使用文件 API，你需要包含测试版功能头：anthropic-beta: files-api-2025-04-14。

上传文件

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

上传文件的响应将包括：

Output

{
  "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 引用文件：

文件类型和内容块

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

文件类型	MIME 类型	内容块类型	用例
PDF	`application/pdf`	`document`	文本分析、文档处理
纯文本	`text/plain`	`document`	文本分析、处理
图像	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	图像分析、视觉任务
数据集、其他	变化

使用其他文件格式

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

对于包含图像的 .docx 文件，首先将其转换为 PDF 格式，然后使用 PDF 支持来利用内置的图像解析。这允许使用 PDF 文档中的引用。

文档块

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // 可选
  "context": "Context about the document", // 可选
  "citations": { "enabled": true } // 可选，启用引用
}

图像块

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

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

管理文件

列出文件

检索你上传的文件列表：

获取文件元数据

检索有关特定文件的信息：

删除文件

从你的工作区删除文件：

下载文件

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

你只能下载由技能或代码执行工具创建的文件。你上传的文件无法下载。

文件存储和限制

存储限制

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

文件生命周期

文件的范围限于 API 密钥的工作区。其他 API 密钥可以使用由与同一工作区关联的任何其他 API 密钥创建的文件
文件持续存在直到你删除它们
删除的文件无法恢复
删除后不久，文件将无法通过 API 访问，但它们可能会在活跃的 Messages API 调用和相关工具使用中持续存在
用户删除的文件将根据 Anthropic 的数据保留政策被删除。

数据保留

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

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

错误处理

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

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

Output

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

使用和计费

文件 API 操作是免费的：

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

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

速率限制

在测试版期间：

文件相关的 API 调用限制为每分钟约 100 个请求
如果你的用例需要更高的限制，请联系我们

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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)

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

# 在消息中作为纯文本发送
response = client.messages.create(
    model="claude-opus-4-7",
    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)