Feb 23, 2026

Claude Files API 完整指南：檔案上傳、管理與跨請求引用的實戰解析

Files API 讓開發者能夠上傳和管理檔案，在 Claude API 中使用而無需每次請求都重新上傳。這對於需要重複使用的文件、搭配 Code Execution 處理資料集，以及與 Agent Skills 協作時特別有用。本文將完整解析 Files API 的使用方式、檔案類型對應、儲存限制與最佳實踐。

一、核心概念

Files API 提供「上傳一次、多次使用」的檔案管理模式：

上傳檔案到 Anthropic 的安全儲存空間，取得唯一的 file_id
在 Messages 請求中透過 file_id 引用檔案
下載由 Skills 或 Code Execution 產生的輸出檔案
透過 list、retrieve、delete 操作管理檔案

目前為 Beta 功能，需要在請求中加入 beta header：anthropic-beta: files-api-2025-04-14。

二、檔案上傳

基本上傳

import anthropic

client = anthropic.Anthropic()
file = client.beta.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
print(file.id)  # file_011CNha8iCJcU1wXNR6q4V8w

上傳回應包含：

{
  "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 欄位指示檔案是否可下載。只有由 Skills 或 Code Execution 產生的檔案才可下載，使用者上傳的檔案不可下載。

三、在 Messages 中引用檔案

檔案類型與 Content Block 對應

檔案類型	MIME Type	Content Block	使用場景
PDF	`application/pdf`	`document`	文字分析、文件處理
純文字	`text/plain`	`document`	文字分析、處理
圖片	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	圖片分析、視覺任務
資料集等	多種	`container_upload`	資料分析、視覺化

Document Block（PDF 和文字檔）

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "文件標題",
  "context": "文件背景說明",
  "citations": {"enabled": true}
}

支援的選用欄位：

title：文件標題
context：提供文件的背景說明
citations：啟用引用功能，Claude 會標註回應中引用的來源段落

Image Block（圖片檔）

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

完整使用範例

response = client.beta.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)

處理其他檔案格式

對於不直接支援為 document block 的檔案類型（.csv、.md、.docx、.xlsx），建議將檔案轉換為純文字後直接包含在訊息中：

import pandas as pd

df = pd.read_csv("data.csv")
csv_content = df.to_string()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze.",
        }
    ],
)

對於包含圖片的 .docx 檔案，建議先轉換為 PDF 格式，再利用 PDF Support 的內建圖片解析功能。

四、檔案管理操作

列出檔案

files = client.beta.files.list()

取得檔案 metadata

file = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w")

刪除檔案

result = client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w")

下載檔案

只有由 Skills 或 Code Execution 產生的檔案才可下載：

file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w")

with open("downloaded_file.txt", "w") as f:
    f.write(file_content.decode("utf-8"))

五、儲存限制與生命週期

儲存限制

項目	限制
單一檔案大小上限	500 MB
組織總儲存空間	100 GB

檔案生命週期

檔案的範圍為 API key 所屬的 workspace，同一 workspace 的其他 API key 可以使用
檔案持續存在直到手動刪除
刪除的檔案無法恢復
刪除後很快就無法透過 API 存取，但可能仍在進行中的 Messages API 呼叫中可用
檔案刪除依照 Anthropic 的資料保留政策執行

檔案名稱規範

長度：1-255 個字元
禁止字元：<、>、:、"、|、?、*、\、/，以及 unicode 字元 0-31

六、錯誤處理

錯誤	HTTP 狀態碼	原因
File not found	404	`file_id` 不存在或無存取權限
Invalid file type	400	檔案類型與 content block 不匹配
Exceeds context window	400	檔案大於 context window 大小
Invalid filename	400	檔名不符合規範
File too large	413	檔案超過 500 MB 限制
Storage limit exceeded	403	組織已達 100 GB 儲存上限

七、計費

Files API 操作本身免費：

上傳、下載、列出、取得 metadata、刪除都不收費

在 Messages 請求中使用的檔案內容按 input tokens 計費。

速率限制

Beta 期間，檔案相關 API 呼叫限制約為每分鐘 100 次請求。

八、支援的模型

在 Messages 請求中引用 file_id 支援所有能處理對應檔案類型的模型：

圖片：所有 Claude 3+ 模型
PDF：所有 Claude 3.5+ 模型
其他檔案類型（透過 Code Execution）：Claude Haiku 4.5 和所有 Claude 3.7+ 模型

目前 Files API 不支援 Amazon Bedrock 或 Google Vertex AI。

總結

Files API 提供了簡潔的檔案管理解決方案，讓開發者能夠「上傳一次、多次使用」，特別適合搭配 Code Execution 進行資料分析、與 Agent Skills 協作處理文件，以及需要在多次 API 呼叫中重複引用相同文件的場景。雖然目前仍為 Beta 功能，但其「操作免費、按使用 token 計費」的定價模式和 500 MB 的單檔上限，已經足以覆蓋大多數實際應用場景。