文件 API 允许您上传和管理文件以便与 Anthropic API 一起使用,而无需在每次请求中重新上传内容。这在使用代码执行工具提供输入(例如数据集和文档)然后下载输出(例如图表)时特别有用。您还可以使用文件 API 避免在多个 API 调用中不断重新上传经常使用的文档和图像。

文件 API 目前处于测试阶段。请通过我们的反馈表单分享您使用文件 API 的体验。

支持的模型

在 Messages 请求中引用 file_id 在所有支持给定文件类型的模型中都受支持。例如,图像在所有 Claude 3+ 模型中都受支持,PDF在所有 Claude 3.5+ 模型中都受支持,以及各种其他文件类型用于 Claude 3.5 Haiku 和所有 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 调用中引用:

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"

文件类型和内容块

文件 API 支持与不同内容块类型对应的不同文件类型:

文件类型MIME 类型内容块类型用例
PDFapplication/pdfdocument文本分析、文档处理
纯文本text/plaindocument文本分析、处理
图像image/jpeg, image/png, image/gif, image/webpimage图像分析、视觉任务
数据集、其他多种container_upload分析数据、创建可视化

文档块

对于 PDF 和文本文件,使用 document 内容块:

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

图像块

对于图像,使用 image 内容块:

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

管理文件

列出文件

检索已上传文件的列表:

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_abc123 \
  -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_abc123 \
  -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_abc123/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

您只能下载由代码执行工具创建的文件。您上传的文件不能被下载。


文件存储和限制

存储限制

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

文件生命周期

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

错误处理

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

  • 文件未找到 (404): 指定的 file_id 不存在或您无权访问它
  • 无效的文件类型 (400): 文件类型与内容块类型不匹配(例如,在文档块中使用图像文件)
  • 文件太大 (413): 文件超过 500 MB 限制
  • 存储限制已超出 (403): 您的组织已达到 100 GB 存储限制
  • 无效的文件名 (400): 文件名不符合长度要求(1-255 个字符)或包含禁止的字符(<>:"|?*\/ 或 Unicode 字符 0-31)
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_abc123"
  }
}

使用和计费

文件 API 操作是免费的

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

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

速率限制

在测试期间:

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