能力

文件 API

使用文件 API 上传和管理文件，在 Claude API 中使用，无需在每次请求时重新上传内容。

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

文件 API 目前处于测试版。请通过我们的反馈表单分享你对文件 API 的体验。

支持的模型

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

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

文件 API 如何工作

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

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

如何使用文件 API

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

上传文件

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

上传文件的响应将包括：

{
  "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"
  }
}

管理文件

列表文件

检索你上传的文件列表：

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

获取文件元数据

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

curl https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

删除文件

从你的工作区删除文件：

curl -X DELETE https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

下载文件

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

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

文件存储和限制

存储限制

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

文件生命周期

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

错误处理

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

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

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

使用和计费

文件 API 操作是免费的：

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

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

速率限制

在测试版期间：

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

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

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

# 示例：读取文本文件并将其作为纯文本发送
# 注意：对于包含特殊字符的文件，考虑 base64 编码
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

curl -X GET "https://api.anthropic.com/v1/files/file_011CNha8iCJcU1wXNR6q4V8w/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output downloaded_file.txt