跳转到主要内容
Files API 让您可以上传和管理文件以与 Claude API 一起使用，而无需在每次请求时重新上传内容。这在使用代码执行工具提供输入（例如数据集和文档）然后下载输出（例如图表）时特别有用。您还可以使用 Files API 来避免在多个 API 调用中不断重新上传经常使用的文档和图像。您可以直接探索 API 参考，以及本指南。
Files API 目前处于测试版。请通过我们的反馈表单分享您对 Files API 的体验。

​
支持的模型

在 Messages 请求中引用 file_id 在所有支持给定文件类型的模型中都受支持。例如，图像在所有 Claude 3+ 模型中受支持，PDF 在所有 Claude 3.5+ 模型中受支持，以及各种其他文件类型用于 Claude 3.5 Haiku 及所有 Claude 3.7+ 模型中的代码执行工具。 Files API 目前在 Amazon Bedrock 或 Google Vertex AI 上不受支持。

​
Files API 如何工作

Files API 提供了一种简单的创建一次、使用多次的文件处理方法：
  • 上传文件到我们的安全存储并接收唯一的 file_id
  • 下载文件由技能或代码执行工具创建
  • 在 Messages 请求中引用文件使用 file_id 而不是重新上传内容
  • 管理您的文件通过列表、检索和删除操作

​
如何使用 Files API

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

​
上传文件

上传文件以在将来的 API 调用中引用： 
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"
上传文件的响应将包括： 
{
  "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 引用文件： 
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"
            }
          }
        ]
      }
    ]
  }'

​
文件类型和内容块

Files API 支持对应于不同内容块类型的不同文件类型：
文件类型MIME 类型内容块类型用例
PDFapplication/pdfdocument文本分析、文档处理
纯文本text/plaindocument文本分析、处理
图像image/jpeg, image/png, image/gif, image/webpimage图像分析、视觉任务
数据集、其他变化container_upload分析数据、创建可视化

​
使用其他文件格式

对于不支持作为 document 块的文件类型（.csv、.txt、.md、.docx、.xlsx），将文件转换为纯文本，并将内容直接包含在您的消息中： 
# 示例：读取文本文件并将其作为纯文本发送
# 注意：对于包含特殊字符的文件，请考虑 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
对于包含图像的 .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"

​
下载文件

下载由技能或代码执行工具创建的文件： 
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
您只能下载由技能或代码执行工具创建的文件。您上传的文件无法下载。

​
文件存储和限制

​
存储限制

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

​
文件生命周期

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

​
错误处理

使用 Files 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"
  }
}

​
使用和计费

Files API 操作是免费的：
  • 上传文件
  • 下载文件
  • 列表文件
  • 获取文件元数据
  • 删除文件
在 Messages 请求中使用的文件内容按输入令牌计费。您只能下载由技能或代码执行工具创建的文件。

​
速率限制

在测试版期间：
  • 与文件相关的 API 调用限制为每分钟大约 100 个请求
  • 如果您的用例需要更高的限制，请联系我们