Claude API Files API 怎麼用：上載一次、用 file_id 反覆引用，500 MB 單文件、過期時間和工作區權限

本文根據 Claude 官方《Files API》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。代碼裏的模型名取自官方當天示例，請以官方模型頁為準。本站（bigolab.com）不是 Anthropic 官方網站。API 是按用量計費的獨立服務，與 Claude 訂閱分開計算，Key 的獲取見 /guides/claude-api-key-console。

適用於誰

• 同一份 PDF、圖片要在很多請求裏反覆使用的開發者；
• 多輪對話裏帶圖片，發現請求體越來越大、越來越慢的人；
• 要用代碼執行工具分析數據文件，並下載生成結果（圖表、報告）的人。

結論先說

1. 上載一次拿到 file_id，之後只引用編號，不再重傳文件內容。
2. 引用寫法：PDF 和純文本用 document 塊，圖片用 image 塊，source 都是 {"type": "file", "file_id": "..."}。
3. 單文件最大 500 MB，每個組織總存儲 1 TB。
4. 你上載的文件不能下載；只有技能或代碼執行工具生成的文件可以下載。
5. 文件對整個工作區可見，所以絕不能接受用戶傳來的 file_id，這是官方的明確警告。
6. 上載、下載、列表、刪除都免費，文件內容在請求裏用到時按輸入 token 計費。

圖：本站根據 Claude 官方《Files API》 整理的示意圖

一、上載文件

Python：

python
import anthropic

client = anthropic.Anthropic()

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

TypeScript：

typescript
import fs from "node:fs";
import Anthropic, { toFile } from "@anthropic-ai/sdk";

const client = new Anthropic();

const uploaded = await client.files.upload({
  file: await toFile(fs.createReadStream("document.pdf"), undefined, {
    type: "application/pdf",
  }),
});
console.log(uploaded.id);

官方提醒，TypeScript 裏要顯式指定內容類型，因為 Files API 不會替你推斷。返回的元數據裏有 id、filename、mime_type、size_bytes、created_at、downloadable 和 expires_at。上載的文件 downloadable 是 false。

二、在請求裏引用

python
response = client.messages.create(
    model="claude-opus-5-5",  # 以官方模型頁當天為準
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "請總結這份文件。"},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": uploaded.id},
                },
            ],
        }
    ],
)

文件類型和內容塊的對應：

document 塊還有三個可選字段：title、context，以及 citations（設 {"enabled": true} 啟用引用）。docx、xlsx 這類二進制格式不能放進 document 塊，需要先轉成文字或 PDF。PDF 的詳細規則見 /guides/claude-api-pdf-support，圖片見 /guides/claude-api-image-input。

三、管理文件

• 列表：client.files.list()，按創建時間由新到舊，預設一頁 20 個，最多 1000 個；SDK 提供自動翻頁。想一次核對已知的一批文件，可以最多傳 100 個 ids[] 參數，不存在的編號會被靜默忽略，要自己對照返回結果；
• 元數據：Python 是 client.files.retrieve_metadata(file_id)，TypeScript 是 client.files.retrieveMetadata(id)；
• 刪除：client.files.delete(file_id)。刪除後無法恢復，文件在刪除後很快無法通過 API 訪問，但可能仍存在於正在進行的 Messages 調用中；
• 修改：文件創建後不能改內容也不能改名，想換內容只能重新上載、再刪除舊的。

四、下載：只有生成的文件可以

圖：本站根據 Claude 官方《Files API》 整理的示意圖

官方規定：只有技能或代碼執行工具創建的文件能下載，元數據裏 downloadable 為 true。你自己上載的文件下載會返回 400。生成文件的 file_id 出現在產生它的那次 Messages 響應的 bash_code_execution_tool_result 內容塊裏。Python 下載的寫法是：

python
file_content = client.files.download(file_id)
file_content.write_to_file("downloaded_file.txt")

五、限制和過期

• 大小：單文件最大 500 MB；每個組織總存儲 1 TB；
• 文件名：1 到 255 個字符，不能包含 <、>、:、"、|、?、*、\、/ 以及控制字符；
• 速率：文件相關調用約每分鐘 500 次請求，需要更高請聯絡官方銷售；
• 過期：上載時可加表單字段 expires_in_seconds，範圍是 3600 秒（1 小時）到 7776000 秒（90 天）。到期後，下載返回 404，引用它的 Messages 請求會在推理前失敗，元數據最多還能讀 30 天，expires_at 的值在過去。過期時間只能在上載時設定，之後不能改。官方強調，過期是生命週期功能，不是保證刪除的手段；想提前刪除，用 DELETE；
• 大小超窗口：文件內容仍受模型上下文窗口限制，比如把 500 MB 的純文本放進請求會報 400。

六、最重要的安全提醒

官方用警告框強調：上載的文件對整個工作區可見。 文件不是綁定到某個終端用戶、某次對話或某個會話的，任何有權訪問該工作區的 API 密鑰，都能訪問其中所有文件。因此：

• 絕不要接受來自終端用戶或其他不可信來源的 file_id。 否則一個用戶可以通過編號讀到另一個用戶上載的內容。file_id 應當當作服務端內部的引用，用戶和文件的對應關係由你自己的應用儲存；
• 必須隔離的文件，放進單獨的工作區，並用只屬於該工作區的密鑰訪問；
• 做多租戶應用，官方建議每個租戶一個工作區，工作區就是文件的隔離邊界；每個組織最多 100 個工作區，不夠可聯絡官方。

七、費用、保留與遷移說明

• 費用：上載、下載、列表、取元數據、刪除都免費；文件內容在 Messages 請求裏用到時按輸入 token 計價，價格以官方價格頁當天為準；
• 保留：官方標明 Files API 不符合零數據保留資格，文件會保留到你刪除或它過期為止；
• beta 變化：Files API 已脫離 beta，不再需要 anthropic-beta 請求頭。仍帶舊請求頭 files-api-2025-04-14 的請求繼續可用，但返回舊的 beta 響應形狀（比如列表用 before_id、after_id）；去掉請求頭後列表改用 page 和 next_page 遊標，expires_at 總會返回。SDK 裏建議用 client.files，而不是舊的 client.beta.files，具體 SDK 版本要求見官方遷移說明。

常見問題

Q：文件報 413 或 400？

文件超過 500 MB 返回 413；文件類型和內容塊不匹配、放進 document 塊的是二進制格式、內容超過上下文窗口，都會返回 400。整體排查見 /guides/claude-api-error-codes。

Q：為什麼引用文件報 404？

編號不存在、不在當前工作區，或文件已過期。

Q：每次上載要不要重複？

同一份文件在同一工作區只要上載一次，儲存好 file_id，直到你刪除它或它過期。

Q：和提示詞緩存是什麼關係？

文件引用解決的是“不重傳”，緩存解決的是“不重複計算同一段前綴”，兩者可以配合，緩存見 /guides/claude-prompt-caching。

參考資料

• Claude 官方：Files API — https://platform.claude.com/docs/en/build-with-claude/files
• Claude 官方：PDF support — https://platform.claude.com/docs/en/build-with-claude/pdf-support