Files API
Files API 让您可以上传和管理文件,以便与 Anthropic API 一起使用,而无需在每次请求时重新上传内容。
Files API 让您可以上传和管理文件,以便与 Anthropic API 一起使用,而无需在每次请求时重新上传内容。这在使用代码执行工具提供输入(例如数据集和文档)然后下载输出(例如图表)时特别有用。您还可以使用 Files 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 调用中引用:
在消息中使用文件
上传后,使用其 file_id
引用文件:
文件类型和内容块
Files API 支持不同的文件类型,对应不同的内容块类型:
文件类型 | MIME 类型 | 内容块类型 | 用例 |
---|---|---|---|
application/pdf | document | 文本分析、文档处理 | |
纯文本 | text/plain | document | 文本分析、处理 |
图像 | image/jpeg , image/png , image/gif , image/webp | image | 图像分析、视觉任务 |
数据集、其他 | 各种 | container_upload | 分析数据、创建可视化 |
处理其他文件格式
对于不支持作为 document
块的文件类型(.csv、.txt、.md、.docx、.xlsx),将文件转换为纯文本,并直接在您的消息中包含内容:
对于包含图像的 .docx 文件,首先将它们转换为 PDF 格式,然后使用 PDF 支持来利用内置的图像解析功能。这允许使用来自 PDF 文档的引用。
文档块
对于 PDF 和文本文件,使用 document
内容块:
图像块
对于图像,使用 image
内容块:
管理文件
列出文件
检索您上传的文件列表:
获取文件元数据
检索特定文件的信息:
删除文件
从您的工作区中删除文件:
下载文件
下载由代码执行工具创建的文件:
您只能下载由代码执行工具创建的文件。您上传的文件无法下载。
文件存储和限制
存储限制
- 最大文件大小: 每个文件 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 存储限制
使用和计费
File API 操作是免费的:
- 上传文件
- 下载文件
- 列出文件
- 获取文件元数据
- 删除文件
在 Messages
请求中使用的文件内容按输入令牌定价。您只能下载由代码执行工具创建的文件。
速率限制
在测试期间:
- 与文件相关的 API 调用限制为大约每分钟 100 个请求
- 如果您的用例需要更高的限制,请联系我们