文件与资源

Files API

Files API 允许您上传和管理文件，以便与 Claude API 配合使用，无需在每次请求时重新上传内容。

Files API 允许您上传和管理文件，以便与 Claude API 配合使用，无需在每次请求时重新上传内容。这在使用代码执行工具提供输入（例如数据集和文档）然后下载输出（例如图表）时特别有用。您还可以使用 Files API 来避免在多次 API 调用中反复重新上传常用的文档和图像。除了本指南外，您还可以直接查看 API 参考。

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

This feature is in beta and is not eligible for Zero Data Retention (ZDR). Beta features are excluded from ZDR.

支持的模型

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

Files API 目前不支持 Amazon Bedrock 或 Google Vertex AI。

Files API 的工作原理

Files API 提供了一种简单的一次创建、多次使用的文件处理方式：

上传文件到我们的安全存储并获得唯一的 file_id
下载文件，这些文件由技能或代码执行工具创建
在 Messages 请求中使用 file_id 引用文件，而无需重新上传内容
通过列表、检索和删除操作管理您的文件

如何使用 Files API

要使用 Files API，您需要包含 Beta 功能头：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-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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

文件类型和内容块

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

文件类型	MIME 类型	内容块类型	用途
PDF	`application/pdf`	`document`	文本分析、文档处理
纯文本	`text/plain`	`document`	文本分析、处理
图像	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	图像分析、视觉任务
数据集及其他	各种	`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-opus-4-6",
  "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"
  }
}

使用和计费

File API 操作是免费的：

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

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

速率限制

在 Beta 期间：

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

Was this page helpful?

文件与资源

Files API

Files API 允许您上传和管理文件，以便与 Claude API 配合使用，无需在每次请求时重新上传内容。

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

This feature is in beta and is not eligible for Zero Data Retention (ZDR). Beta features are excluded from ZDR.

支持的模型

Files API 目前不支持 Amazon Bedrock 或 Google Vertex AI。

Files API 的工作原理

Files API 提供了一种简单的一次创建、多次使用的文件处理方式：

上传文件到我们的安全存储并获得唯一的 file_id
下载文件，这些文件由技能或代码执行工具创建
在 Messages 请求中使用 file_id 引用文件，而无需重新上传内容
通过列表、检索和删除操作管理您的文件

如何使用 Files API

要使用 Files API，您需要包含 Beta 功能头：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-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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

文件类型和内容块

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

文件类型	MIME 类型	内容块类型	用途
PDF	`application/pdf`	`document`	文本分析、文档处理
纯文本	`text/plain`	`document`	文本分析、处理
图像	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	图像分析、视觉任务
数据集及其他	各种	`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-opus-4-6",
  "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"
  }
}

使用和计费

File API 操作是免费的：

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

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

速率限制

在 Beta 期间：

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

Was this page helpful?