Files API

Files API 讓您可以上傳並管理檔案以搭配 Claude API 使用，而無需在每次請求時重新上傳內容。這在使用程式碼執行工具提供輸入（例如資料集與文件）並接著下載輸出（例如圖表）時特別有用。除了本指南之外，您也可以直接探索 API 參考文件可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。。

檔案類型支援

在 Messages 請求中參照 file_id，支援所有支援該檔案類型的模型。圖片在所有目前的 Claude 模型上皆受支援。關於 PDF 以及搭配程式碼執行工具使用的其他檔案類型，請參閱連結頁面以了解模型支援情況。

Files API 的運作方式

Files API 提供一種「建立一次、多次使用」的檔案處理方式：

• 上傳檔案至 Anthropic 的安全儲存空間，並取得唯一的 file_id
• 下載檔案，這些檔案由 skills 或程式碼執行工具所建立
• 參照檔案，在 Messages可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 請求中使用 file_id，而非重新上傳內容
• 管理您的檔案，透過列出、擷取與刪除操作

如何使用 Files API

上傳檔案

上傳檔案以便在之後的 API 呼叫中引用：

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

上傳檔案的回應包含：

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "expires_at": null
}

對於您上傳的檔案，downloadable可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 為 false。只有由 skills 或程式碼執行工具建立的檔案才能下載。請參閱下載檔案。

API 參考文件說明了檔案物件的每個欄位。

在訊息中使用檔案

上傳完成後，將上傳回應中的 id 作為 file_id 傳入以參照該檔案：

response = client.messages.create(
    model="claude-opus-5-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_id,
                    },
                },
            ],
        }
    ],
)
print(response)

檔案類型與內容區塊

Files API 支援不同的檔案類型，分別對應不同的內容區塊（content block）類型：

文件區塊

對於 PDF 與文字檔案，請使用 document 內容區塊：

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}

圖片區塊

對於圖片，請使用 image 內容區塊：

{
  "type": "image",
  "source": {
    "type": "file",
    "file_id": "file_011CPMxVD3fHLUhvTqtsQA5w"
  }
}

容器上傳區塊

若要將檔案傳送至程式碼執行工具，請使用 container_upload 內容區塊：

{
  "type": "container_upload",
  "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
}

處理其他檔案格式

對於 document 區塊不支援的檔案類型（例如 .docx 和 .xlsx），請將檔案轉換為純文字，並直接將內容包含在您的訊息中。本身已是純文字的檔案（例如 .csv 和 .md 檔案），可以用這種方式讀取，也可以透過 Files API 以明確的 text/plain 內容類型上傳。若要分析資料集而非以文字方式讀取，請使用 container_upload 區塊將其上傳給程式碼執行工具（請參閱上傳並分析您自己的檔案）。

以下範例讀取一個文字檔案，並將其內容以純文字傳送：

client = anthropic.Anthropic()

# 讀取文字檔案
with open("document.txt") as f:
    text_content = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the document content:\n\n{text_content}\n\nPlease summarize this document.",
                }
            ],
        }
    ],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

管理檔案

列出檔案

取得您已上傳檔案的清單。此端點採用「pagination」（分頁）：每個請求最多傳回 limit可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 個檔案（預設為 20 個，最多 1,000 個），而回應中的 next_page可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 游標在作為 page可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 參數傳回時，會取得下一頁。檔案依最新優先排序。請參閱列出檔案 API 參考文件可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。。SDK 會傳回第一頁，並提供自動分頁輔助工具。

client = anthropic.Anthropic()
files = client.files.list()
print(files)

若要在單一請求中檢查一組已知的檔案而非逐頁查詢，請以 ids[] 查詢參數傳入最多 100 個檔案 ID。ids[] 請求一律回傳單一頁面（next_page 為 null），且任何無法解析為您工作區中檔案的 ID 都會從 data 中靜默省略；請將回傳的 ID 與請求的 ID 進行比對以偵測遺漏。ids[] 不能與 page 或 limit 合併使用。

取得檔案中繼資料

擷取特定檔案的相關資訊：

file = client.files.retrieve_metadata(file_id)
print(file)

刪除檔案

從您的工作區刪除檔案：

client.files.delete(file_id)

下載檔案

下載由 skills 或程式碼執行工具所建立的檔案。您上傳的檔案無法下載。所產生檔案的 file_id 會出現在建立該檔案的 Messages 回應中的 bash_code_execution_tool_result 內容區塊裡：

file_content = client.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")

在 Claude API 上，Claude 透過程式碼執行工具產生的受支援圖片、影片和音訊檔案（包括由技能建立的檔案），在您下載時會附帶已簽署的 C2PA「Content Credentials」（內容憑證）。請參閱產生之檔案上的 Content Credentials，以了解憑證包含的內容以及如何驗證。

檔案儲存與限制

儲存限制

• 最大檔案大小： 每個檔案 500 MB
• 總儲存空間： 每個組織 1 TB

檔案生命週期

• 檔案的範圍限定於其上傳時所在的工作區。同一工作區中的任何請求都可以參照它們；切勿接受來自不受信任來源的檔案 ID（請參閱工作區存取警告）。
• 檔案上傳後無法修改或重新命名。若要變更檔案內容，請上傳新檔案並刪除舊檔案。
• 檔案會持續保留，直到您使用 DELETE /v1/files/{file_id} 端點將其刪除，或達到其 expires_at 為止。
• 已刪除的檔案無法復原。
• 檔案在刪除後不久即無法透過 API 存取，但它們可能仍存在於進行中的 Messages API 呼叫及相關的工具使用中。
• 使用者刪除的檔案將依照 Anthropic 的資料保留政策予以刪除。

檔案到期

若要讓檔案自動到期，請在上傳時加入 expires_in_seconds可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 表單欄位。其值為介於 3,600（1 小時）到 7,776,000（90 天）之間的整數秒數。產生的 expires_at可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 時間戳記（RFC 3339）會出現在每個檔案回應中，對於未設定到期時間而上傳的檔案，其值為 null。到期時間僅在上傳時設定一次，之後無法變更。

當檔案到達其 expires_at 時：

• 下載其內容（GET /v1/files/{file_id}/content）會傳回 404 錯誤。
• 引用該檔案的 Messages 請求會在推論前失敗。
• 其中繼資料（GET /v1/files/{file_id}）在最多 30 天內仍可讀取，且 expires_at 為過去的時間。
• 在此期間內，它會繼續出現在列表回應中；請將 expires_at 與目前時間比較，以篩選出已到期的檔案。

使用 DELETE /v1/files/{file_id} 刪除已到期的檔案會立即移除其中繼資料，而非等待 30 天期間結束。

稽核記錄

如果您的組織已啟用 Compliance API，其 Activity Feed 會記錄以 Claude API 金鑰或從 Claude Console 進行的 Files API 操作：每次上傳（POST /v1/files）、內容下載（GET /v1/files/{file_id}/content）與刪除（DELETE /v1/files/{file_id}）分別會以 platform_file_uploaded、platform_file_content_downloaded 或 platform_file_deleted 活動的形式出現。列出檔案與擷取檔案中繼資料不會被記錄。在 Compliance API 關閉期間發生的操作不會被記錄，且之後無法復原，因此在您依賴此稽核軌跡之前，請先設定 Compliance API。在 Claude Platform on AWS 上，請改用 AWS CloudTrail 資料事件來稽核檔案操作。

從 files-api-2025-04-14 遷移

Files API 已結束 beta 階段，不再需要 beta 標頭。從 files-api-2025-04-14 遷移是選擇性的：傳送該標頭的請求會繼續運作，並繼續回傳 beta 回應結構，因此現有的整合在您變更之前會持續運作。移除該標頭會將這些請求切換為本頁所記載的結構：

遷移步驟：

1. 移除 beta 標頭。 從您的請求中移除 anthropic-beta: files-api-2025-04-14。使用 SDK 時，請呼叫 client.files，而非 client.beta.files；保留 client.beta.files 僅在不再傳送此標頭的 SDK 版本上有效。較早的版本即使在您未傳入任何 beta 名稱時，也會從 client.beta.files 傳送此標頭。
2. 更新分頁。 將 after_id/before_id 迴圈替換為 page/next_page 游標，或使用管理檔案中所示的 SDK 自動分頁輔助工具。
3. 讀取 expires_at。 此欄位僅在不使用該標頭時出現；null 表示檔案沒有到期時間（請參閱檔案到期）。

SDK beta 命名空間

從 Python SDK 1.2.0、TypeScript SDK 0.122.0、Go SDK 1.68.0、Java SDK 2.59.0、PHP SDK 0.45.0、Ruby SDK 1.67.0 和 C# SDK 12.44.0 開始，client.beta.files 不再傳送 files-api-2025-04-14，並傳回與 client.files 相同的格式，但型別名稱帶有 Beta 前綴（在 PHP 中為 Anthropic\Beta 命名空間中的類別）。對於處於 beta 階段的 Files 功能，它透過 betas 接受 beta 名稱，例如在 Managed Agents beta 標頭下的 scope_id 篩選。較早的 SDK 版本的型別對應 beta 格式；如果您依賴這些型別，請在遷移之前繼續使用較早的版本。

帶有 anthropic-beta: managed-agents-2026-04-01 但不帶 files-api-2025-04-14 的請求會收到本頁的結構，並在 GET /v1/files 上有一項相容性便利措施：before_id 與 after_id 仍被接受（不可與 page 或 ids[] 合併使用），且列出回應除了 next_page 之外還包含 has_more、first_id 與 last_id。較新的 Managed Agents beta 版本則收到一般結構。

錯誤處理

使用 Files API 時的常見錯誤包括：

• 找不到檔案（404）： 指定的 file_id 不存在，或您沒有存取權限。
• 無效的檔案類型（400）： 檔案類型與內容區塊類型不符（例如在文件區塊中使用圖片檔案）。
• 無法下載（400）： 您上傳的檔案具有 "downloadable": false，因此無法下載。只有由 skills 或程式碼執行工具建立的檔案才能下載。
• 超出上下文視窗大小（400）： 檔案大於「context window」（上下文視窗）大小（例如在 /v1/messages 請求中使用 500 MB 的純文字檔案）。
• 無效的檔案名稱（400）： 檔案名稱不符合長度要求（1–255 個字元），或包含禁止使用的字元（<、>、:、"、|、?、*、\、/，或 Unicode 字元 0–31）。
• 檔案過大（413）： 檔案超過 500 MB 的限制。
• 超出儲存限制（400）： 您的組織已達到 1 TB 的儲存限制。

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

用量與計費

Files API 操作免費：

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

在 Messages 請求中使用的檔案內容以輸入 token 計價。

速率限制

與檔案相關的 API 呼叫限制為每分鐘約 500 次請求。若要申請更高的限制，請聯繫銷售團隊。

後續步驟

可用性