Files API

Files API 讓您可以上傳並管理檔案以搭配 Claude API 使用，而無需在每次請求時重新上傳內容。這在使用程式碼執行工具提供輸入（例如資料集與文件）並接著下載輸出（例如圖表）時特別有用。除了本指南之外，您也可以直接探索 API 參考文件。

檔案類型支援

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

Files API 的運作方式

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

• 上傳檔案至 Anthropic 的安全儲存空間，並取得唯一的 file_id
• 下載檔案，這些檔案由 skills 或程式碼執行工具所建立
• 參照檔案，在 Messages 請求中使用 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 為 false。只有由 skills 或程式碼執行工具所建立的檔案才能下載。請參閱下載檔案。

在訊息中使用檔案

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

response = client.messages.create(
    model="claude-opus-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）類型：

Document 區塊

對於 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 區塊

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

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

Container upload 區塊

若要將檔案傳送至程式碼執行工具，請使用 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",
    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)

管理檔案

列出檔案

擷取您已上傳檔案的清單。此端點採分頁方式：每次請求最多回傳 limit 個檔案（預設為 20，最多 1,000），而回應中的 next_page 游標在作為 page 參數傳回時可取得下一頁。檔案依最新優先排序。請參閱 List Files API 參考文件。SDK 會回傳第一頁並提供自動分頁輔助工具。CLI 範例以 --max-items 限制總數：

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 透過程式碼執行工具所產生的受支援圖片與影片檔案（包括由 skills 建立的檔案），在您下載時會帶有已簽署的 C2PA Content Credentials（內容憑證）。請參閱所產生檔案上的 Content Credentials，以了解憑證包含的內容以及如何驗證。

檔案儲存與限制

儲存限制

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

檔案生命週期

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

檔案到期

若要讓檔案自動到期，請在上傳時包含 expires_in_seconds 表單欄位。其值為介於 3,600（1 小時）與 7,776,000（90 天）之間的整數秒數。所產生的 expires_at 時間戳記（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 版本上可行。較早的版本即使沒有 betas 引數，也會從 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、Ruby SDK 1.67.0 與 C# SDK 12.44.0 起，client.beta.files 不再傳送 files-api-2025-04-14，並回傳與 client.files 相同的結構，但型別名稱帶有 Beta 前綴。它接受 betas 引數以用於仍處於 beta 階段的 Files 功能，例如在 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）： 檔案類型與內容區塊類型不符（例如在 document 區塊中使用圖片檔案）
• 不可下載（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 次請求。若要申請更高的限制，請聯繫銷售團隊。

後續步驟

Compatibility