Claude API 圖片輸入（vision）怎麼傳：base64、url、file_id 三種寫法，數量、大小和 token 怎麼算

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

適用於誰

• 想讓 Claude 識別截圖、票據、圖表、照片的開發者；
• 在網頁或應用裏的 Claude 能看圖，卻不知道 API 裏怎麼傳的人；
• 圖片多、請求慢或報錯，想弄清上限和 token 的人。

在 claude.ai 裏直接上載圖片的說明，不屬於本文範圍，網頁端文件限制見 /guides/claude-file-upload-limits。

結論先說

1. 圖片放進 image 內容塊，和 text 塊一起放在用戶消息的 content 數組裏。
2. 三種來源：base64（把圖片編碼進請求）、url（給一個公開圖片網址）、file（用 Files API 先上載，再引用 file_id）。
3. 支持 JPEG、PNG、GIF、WebP。 GIF 動圖只用第一幀。
4. 數量：每個請求最多 100 張（上下文窗口為 200k token 的模型）或 600 張（其他模型）；單張在 Claude API 上最大 10 MB（base64 編碼後）。
5. 圖片放在文字前面，官方說這樣效果更好。

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

一、方式一：base64

把圖片讀成字節、編碼成 base64 字符串，放進請求。Python：

python
import base64
import anthropic

client = anthropic.Anthropic()

with open("chart.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-opus-5-5",  # 以官方模型頁當天為準
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "請描述這張圖裏的主要資訊。"},
            ],
        }
    ],
)
print(message.content[0].text)

media_type 要和圖片真實格式一致：PNG 寫 image/png，JPEG 寫 image/jpeg。TypeScript 裏把文件讀成 base64 的寫法是 fs.readFileSync("chart.png").toString("base64")，其餘結構完全相同。

二、方式二：url

圖片已經在公開網址上，就不必自己編碼：

python
message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "url", "url": "https://example.com/chart.png"},
                },
                {"type": "text", "text": "這張圖表說明了什麼？"},
            ],
        }
    ],
)

官方提示：如果你用的是 Amazon Bedrock 或 Google 託管的 Claude 模型，這些平台只支持 base64 來源。所以代碼要換平台時，不要預設 url 一定能用。網址必須是伺服器能訪問到的公開地址。

三、方式三：先上載，再引用 file_id

多輪對話裏，每一輪請求都會把完整歷史重發一遍。如果圖片是 base64，圖片字節就會在每一輪重複發送，請求會越來越大、越來越慢。官方的建議是用 Files API 上載一次，之後只引用 file_id：

python
{"type": "image", "source": {"type": "file", "file_id": "file_xxx"}}

上載、管理、限制等細節見 /guides/claude-api-files-api。

四、多張圖、順序和提示詞

一個 content 數組裏可以放多個 image 塊。本站的建議是在每張圖前面用文字標一下，例如“圖 1：”，再放圖片，最後寫問題，這樣模型更容易分清哪句話指哪張圖。這只是一種寫法習慣，官方沒有強制要求。

提醒兩點：

• 官方建議“先圖後文”，但先文後圖也能正常工作；
• Claude 不會讀取圖片的元數據（比如拍攝時間、位置），只看畫面內容。

五、數量和大小限制

兩點補充：

• 超過 20 張圖時有更嚴格的單圖尺寸限制。 它按請求裏所有 image 塊算，包括你重發的歷史輪次裏的圖。被拒絕時錯誤訊息會提到 “many-image requests”。官方給的避免辦法是每邊縮到 3000 像素以內，或把圖片與文檔塊控制在 20 個以內；
• 圖多時請求總大小常比張數先到上限，這時用 Files API 引用 file_id 可以讓請求體變小。

六、token 怎麼估算

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

官方的算法：圖片按 28 乘 28 像素的補丁處理，每個補丁算一個視覺 token，所以一張圖約等於

向上取整（寬 ÷ 28）× 向上取整（高 ÷ 28）個 token。

每個模型有“長邊上限”和“視覺 token 上限”，超過任一個，圖片會先按比例縮小。官方分了兩檔：

官方表格裏的例子：1000 乘 1000 像素的圖，兩檔都是 1296 個 token，不會縮小；1920 乘 1080 的圖，標準檔縮到 1456 乘 819，約 1560 個 token，高解像度檔不縮小，約 2691 個 token。官方還提醒：高解像度檔同一張圖可能比標準檔多用約三倍視覺 token，不需要那麼高保真時，先自己縮小再發，能省 token、降延遲。

真實費用請用官方的 token 計數接口先量一下，見 /guides/claude-api-count-tokens，價格以官方價格頁當天為準。

七、官方列出的侷限

• 低質素、旋轉過、小於 200 像素的圖，容易出錯甚至“幻覺”；
• 位置和座標是近似值，使用前要自己核對；
• 數物體的個數只能給近似值，物體多又小時容易不準；
• 不能判斷一張圖是不是 AI 生成的，別依賴它做這件事；
• 複雜的醫學影像（如 CT、MRI）不是它的設計用途，輸出不能替代專業診斷。

壓縮圖片會減小請求，但 JPEG 壓縮過重會讓文字難以辨認，官方建議檢查實際發出的圖片。

常見問題

Q：圖片能和 PDF 一起發嗎？

可以。PDF 用 document 塊，寫法見 /guides/claude-api-pdf-support。

Q：同一張圖反覆問，能省錢嗎？

可以配合提示詞緩存，見 /guides/claude-prompt-caching。

Q：報錯 400 或 413？

圖片過大、格式不對、數量超限都可能觸發，整體排查見 /guides/claude-api-error-codes。

參考資料

• Claude 官方：Vision — https://platform.claude.com/docs/en/build-with-claude/vision