功能

Files API

使用 Files API 上傳和管理檔案以供 Claude API 使用，無需在每次請求時重新上傳內容。

Files API 讓您上傳和管理檔案以供 Claude API 使用，無需在每次請求時重新上傳內容。這在使用程式碼執行工具提供輸入（例如資料集和文件）然後下載輸出（例如圖表）時特別有用。您也可以使用 Files API 來避免在多個 API 呼叫中持續重新上傳常用的文件和圖像。您可以直接探索 API 參考，除了本指南外。

Files API 目前處於測試版。請透過我們的意見回饋表單分享您對 Files API 的體驗。

支援的模型

在 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 時的常見錯誤包括：

檔案未找到 (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 請求中使用的檔案內容按輸入令牌計費。您只能下載由技能或程式碼執行工具建立的檔案。

速率限制

在測試版期間：

檔案相關的 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-sonnet-4-5",
    "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-sonnet-4-5",
  "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