文件与资源

Files API

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

支持的模型

在 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，您需要包含测试版功能标头：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 上传的文件将保留，直到使用 DELETE /v1/files/{file_id} 端点明确删除为止。文件被存储以便在多个 API 请求中重复使用。

有关所有功能的 ZDR 资格，请参阅 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 请求中使用的文件内容按输入 token 计费。您只能下载由技能或代码执行工具创建的文件。

速率限制

在测试期间：

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

Was this page helpful?

文件与资源

Files API

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

支持的模型

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-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 上传的文件将保留，直到使用 DELETE /v1/files/{file_id} 端点明确删除为止。文件被存储以便在多个 API 请求中重复使用。

有关所有功能的 ZDR 资格，请参阅 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 请求中使用的文件内容按输入 token 计费。您只能下载由技能或代码执行工具创建的文件。

速率限制

在测试期间：

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

Was this page helpful?