Files API

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



檔案類型支援

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



Files API 的運作方式

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

• 上傳檔案至 Anthropic 的安全儲存空間，並取得唯一的 file_id
• 下載檔案，即由技能或程式碼執行工具所建立的檔案
• 在 Messages 請求中使用 file_id 參照檔案，而無需重新上傳內容
• 透過列出、擷取和刪除操作來管理您的檔案



如何使用 Files API



上傳檔案

上傳檔案以便在未來的 API 呼叫中參照：

uploaded = client.beta.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
}

對於您上傳的檔案，downloadable 為 false。只有由技能或程式碼執行工具建立的檔案才能下載。請參閱下載檔案。



在訊息中使用檔案

上傳後，透過將上傳回應中的 id 作為 file_id 傳遞來參照檔案：

response = client.beta.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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)



檔案類型與內容區塊

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



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 個），而 before_id 和 after_id 參數可擷取相鄰的頁面。請參閱 List Files API 參考文件。SDK 會回傳第一頁並提供自動分頁輔助工具。CLI 範例使用 --max-items 限制總數：

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



取得檔案中繼資料

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

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



刪除檔案

從您的工作區移除檔案：

client.beta.files.delete(file_id)



下載檔案

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

file_content = client.beta.files.download(file_id)

file_content.write_to_file("downloaded_file.txt")



檔案儲存與限制



儲存限制

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



檔案生命週期

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



錯誤處理

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

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

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



使用量與計費

Files API 操作是免費的：

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

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



速率限制

在 beta 期間：

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



後續步驟