Claude Files API：PDF 從每次內嵌 base64 改成上傳一次用 file_id，多出來的是一份要自己管的狀態

同一份 PDF 要問很多題，source 底下那個 type 到底該填 base64、url，還是 file？URL 能不能直接塞進 file_id？

這個疑問有人真的踩過。2026 年 10 月 17 日，有人在 GitHub 的 RouteHub 專案開了 issue #70，標題是「[BUG][anthropic._file_block][A file URL is sent to Claude as base64 data or a Files API id instead of a URL document]」。內容大意是：專案裡的 _file_block helper 把 URL 當成 file_id 送出去，Anthropic 的 Files API 就去找一個 id 等於那串 URL 的檔案，請求自然失敗；反過來，URL 若放進 file_data，又會被當成 base64 送出。

三種送法長得很像，差一個欄位就全盤皆錯。所以這篇我把同一件事的舊做法和新做法並排看一遍。

先講我的邊界：我只讀了官方的 Files API 文件、PDF support 文件和上面那則 issue，沒有實際呼叫過任何 API，下面所有範例都是官方原文，不是我跑出來的輸出。

舊做法：檔案跟著每一次請求走

PDF support 文件列了三種送 PDF 的方式：線上的 URL、document 區塊裡的 base64、以及 Files API 的 file_id。第二種的適用情境，官方寫的是「If you need to send PDFs from your local system or when a URL isn’t available」。

打個比方，你要請同一位顧問回答十個問題，舊做法等於每問一題，就把整份文件重新影印、裝訂、塞進信封再寄一次。信封裡永遠是完整的文件，顧問不需要記得你是誰，這是它的好處；每次都得整份重寄，這是它的代價。

下面是 PDF support 文件裡 base64 做法的 Python 範例，照原頁貼上，只省略了最後面的 print，沒有合併或改寫。官方預設從 URL 下載 PDF，本地檔的寫法被註解在裡面：

import base64
import httpx2

# First, load and encode the PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx2.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# Alternative: Load from a local file
# with open("document.pdf", "rb") as f:
#     pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

# Send to Claude using base64 encoding
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

問十題，這段 data 就要出現十次。官方在談請求上限時也點到這件事：32 MB 的請求大小和每次請求 600 頁（請求的 context window 小於 1M tokens 時是 100 頁），兩個限制算的都是整個請求 payload，包含跟 PDF 一起送的其他內容。

新做法：上傳一次，之後只帶一個 id

Files API 的官方定位只有一句：upload and manage files to use with the Claude API「without re-uploading content with each request」。文件稱這種做法是 create-once, use-many-times。PDF support 那頁對它的建議也很直白：「For PDFs you’ll use repeatedly, or when you want to avoid encoding overhead」，遇到大 PDF 則是「to keep request payloads small」。

上傳那一步，官方範例長這樣：

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

之後每次提問，source 換成 file 型，只帶 id（以下同樣出自 Files API 文件）：

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}},
    ]}],
)

換成櫃台的比喻：文件寄一次，櫃台給你一張編號條，之後每封信只寫「請看 11 號櫃」。信變薄了。RouteHub 那個 bug 就是在這裡出事：有人把「這是一個網址」和「這是櫃台編號」當成同一種東西往同一個欄位塞。官方範例裡 URL 型是 "type": "url"，file 型是 "type": "file" 加 file_id，兩條路各走各的，不能混。

這裡有一件我特別想講清楚的事：文件沒有說引用 file_id 會讓帳單變輕。它寫的是 Files API 本身的上傳、下載、列表、取 metadata、刪除都免費，而「File content used in Messages requests is priced as input tokens」。這句話沒有拿 base64 當對照，所以兩種做法在計費上差多少，我讀不到答案，也不替官方補一個。延遲有沒有差，文件同樣沒給量測。官方白紙黑字寫出來的好處，就是請求裡不用每次重送內容。