檔案 API 讓您可以上傳和管理檔案，以便在 Anthropic API 中使用，而無需在每次請求時重新上傳內容。這在使用程式碼執行工具提供輸入（例如資料集和文件）然後下載輸出（例如圖表）時特別有用。您還可以使用檔案 API 避免在多個 API 呼叫中重複上傳經常使用的文件和圖像。

檔案 API 目前處於 beta 階段。請通過我們的意見表單分享您使用檔案 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，您需要包含 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"

​
檔案類型和內容區塊

檔案 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 請求中使用的檔案內容按輸入標記計費。您只能下載由程式碼執行工具創建的檔案。

​
速率限制

在 beta 期間：

  • 與檔案相關的 API 呼叫限制為每分鐘約 100 個請求
  • 如果您的使用案例需要更高的限制，請聯繫我們