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 呼叫中引用：

上傳檔案的回應將包含：

{
  "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 引用檔案：

檔案類型與內容區塊

Files API 支援不同的檔案類型，對應不同的內容區塊類型：

檔案類型	MIME 類型	內容區塊類型	使用情境
PDF	`application/pdf`	`document`	文字分析、文件處理
純文字	`text/plain`	`document`	文字分析、處理
圖片	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	圖片分析、視覺任務
資料集及其他	不定

處理其他檔案格式

對於不支援作為 document 區塊的檔案類型（.csv、.txt、.md、.docx、.xlsx），請將檔案轉換為純文字，並直接在訊息中包含內容：

對於包含圖片的 .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"

下載檔案

下載由技能或程式碼執行工具建立的檔案：

您只能下載由技能或程式碼執行工具建立的檔案。您上傳的檔案無法被下載。

檔案儲存與限制

儲存限制

最大檔案大小： 每個檔案 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 的限制
您的組織已達到 100 GB 的儲存限制

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

使用與計費

Files API 操作是免費的：

上傳檔案
下載檔案
列出檔案
取得檔案中繼資料
刪除檔案

在 Messages 請求中使用的檔案內容將按輸入 token 計費。您只能下載由技能或程式碼執行工具建立的檔案。

速率限制

在測試期間：

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

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"

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"
            }
          }
        ]
      }
    ]
  }'

# 範例：讀取文字檔案並以純文字傳送
# 注意：對於含有特殊字元的檔案，請考慮使用 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

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