視覺

本指南說明如何在 Claude 中使用圖片，包括最佳實踐、程式碼範例以及需要注意的限制。



如何使用視覺功能

您可以透過以下方式使用 Claude 的視覺能力：

• claude.ai。像上傳檔案一樣上傳圖片，或直接將圖片拖放到聊天視窗中。
• Console Workbench。每個 User 訊息區塊的右上角會出現一個新增圖片的按鈕。
• API 請求。請參閱本指南中的範例。

單一請求中可以包含多張圖片，Claude 在制定回應時會一併分析這些圖片。這對於比較或對照圖片很有幫助。



上傳前須知



一般限制

每則訊息或請求的最大圖片數量為：

• 在 claude.ai 上每則訊息 20 張。
• 透過 API，對於具有 200k token「context window」（上下文視窗）的模型，每個請求 100 張。
• 透過 API，對於所有其他模型，每個請求 600 張。

每張圖片的最大尺寸為 8000x8000 像素。

如果單一 API 請求包含超過 20 張圖片，則會套用更嚴格的單張圖片尺寸限制。在 Amazon Bedrock 和 Vertex AI 上，PDF 等文件區塊也會計入此門檻。超過此更嚴格限制的圖片會被拒絕，並回傳 invalid_request_error，其訊息會提及「many-image requests」並說明目前的像素限制。若要在所有平台上保持在限制範圍內，請將每張圖片調整大小，使任一邊都不超過 2000 像素，或將請求中的圖片和文件區塊總數控制在 20 個以內。

每張圖片的最大大小為：

• 直接使用 Claude API 時為 10 MB（base64 編碼）。
• 在 Amazon Bedrock 和 Vertex AI 上為 5 MB（base64 編碼）。
• 在 claude.ai 上為 10 MB。



評估圖片大小

Claude 以區塊（patch）而非像素的方式檢視圖片。每個區塊是圖片中 28×28 像素的方塊，稱為視覺 token。因此，一張圖片的成本為 ⌈width / 28⌉ × ⌈height / 28⌉ 個視覺 token。

如果 Claude 收到過大的圖片，會將其調整大小。最大原生圖片解析度為：

• 對於 Claude Fable 5 和 Claude Mythos 5：4784 個 token，且長邊最多 2576 像素。
• 對於 Claude Opus 4.8：4784 個 token，且長邊最多 2576 像素。
• 對於 Claude Opus 4.7：4784 個 token，且長邊最多 2576 像素。
• 對於其他模型：1568 個 token，且長邊最多 1568 像素。

為了最小化「latency」（延遲）並簡化基於座標的工作流程，您應優先在上傳前調整圖片大小。



計算圖片成本

您在請求中包含的每張圖片都會計入您的 token 使用量。若要計算大約成本，請將圖片的視覺 token 數量（請參閱評估圖片大小）乘以您所使用模型的每 token 價格。

以下是在 API 大小限制範圍內，基於 Claude Sonnet 4.6 每百萬輸入 token 3 美元的價格，不同圖片大小的 token 化和大約成本範例：

請注意，最後三張圖片超過原生解析度，會在處理前被縮小（分別縮小至 1456x819 px、1270x952 px 和 1456x819 px），這限制了它們的 token 成本。4K 圖片的成本不會高於 1920x1080 圖片，因為兩者都縮小到相同的尺寸；額外的解析度會被捨棄。



高解析度圖片支援

Claude Opus 4.7 是第一個支援高解析度圖片的 Claude 模型；Claude Opus 4.8、Claude Fable 5、Claude Mythos 5 及後續模型也支援此功能。最大圖片解析度為長邊 2576 像素，高於先前模型的 1568 像素。這為視覺密集型工作負載帶來效能提升，對於電腦使用、螢幕截圖理解和文件分析特別有價值。

在 Claude Opus 4.7 及後續模型上，高解析度支援是自動啟用的，不需要 beta 標頭或用戶端選擇加入。

在 Claude Opus 4.7、Claude Opus 4.8、Claude Fable 5 和 Claude Mythos 5 上，高解析度圖片可能使用比先前模型多約 3 倍的圖片 token（每張圖片 4784 個 token 對比 1568 個 token）。如果您不需要額外的精細度，請在傳送前對圖片進行降採樣以控制 token 成本。

以下是相同圖片大小在 Claude Opus 4.7 和 Claude Opus 4.8 上的 token 化結果，基於其每百萬輸入 token 5 美元的價格：

只有最後一張圖片超過較高的限制：4K 圖片在處理前會被縮小至 2576x1449 px。高解析度支援提高了解析度限制，但並未移除限制；長邊超過 2576 像素（或 4784 個視覺 token）的圖片仍會被縮小。



確保圖片品質

向 Claude 提供圖片時，請注意以下事項以獲得最佳結果：

• 圖片格式：使用支援的圖片格式：JPEG、PNG、GIF 或 WebP。
  不支援動畫，只會使用第一個影格。
• 圖片清晰度：確保圖片清晰，不要太模糊或像素化。
• 文字：如果圖片包含重要文字，請確保文字清晰可讀且不會太小。避免為了放大文字而裁切掉關鍵的視覺上下文。
• 調整大小：請考慮到如果圖片太大可能會被調整大小（見上文）；這可能會使文字變得較難辨識。請考慮預先調整圖片大小、裁切圖片，或兩者並用。
• 圖片壓縮：在傳送前使用有損格式（如 JPEG 或 WebP 有損模式）壓縮圖片，可以透過減少請求大小來降低延遲。然而，這可能會引入對模型效能有害的雜訊，尤其是在套用多次壓縮時。例如，過度的 JPEG 壓縮可能使文字難以閱讀。請檢查實際傳送到 API 的圖片，以確認您的壓縮設定適合該任務。



使用座標和邊界框

Claude 可以定位並標記圖片中的區域（例如，回傳表格、表單欄位、圖表元素或 UI 元件的邊界框）。

座標遵循標準圖片慣例：原點 (0, 0) 位於圖片的左上角，x 向右遞增，y 向下遞增。Claude 回傳的座標是 Claude 所見圖片中的像素位置：即您的圖片經 Claude 調整大小以符合模型原生解析度後的圖片（請參閱 Claude 如何調整圖片大小和填充）。若要取得可直接使用的座標，請預先調整圖片大小，使座標與您手上的圖片一一對應（請參閱上傳前調整圖片大小），或重新縮放 Claude 回傳的座標（請參閱無法預先調整大小時重新縮放座標）。



Claude 如何調整圖片大小和填充

Claude 會找出同時滿足模型兩項圖片限制的最大保持長寬比尺寸：

1. 邊長限制： 任一邊都不超過最大邊長（大多數模型為 1568 像素，Claude Opus 4.7 及後續模型為 2576 像素）。
2. 視覺 token 限制： 圖片的 token 成本 ⌈width / 28⌉ × ⌈height / 28⌉ 不超過模型的視覺 token 預算（大多數模型為 1568 個 token，Claude Opus 4.7 及後續模型為 4784 個）。

對於大多數照片和螢幕截圖，觸發調整大小的是邊長限制。對於直向文件，通常是視覺 token 限制先觸發，而忽略這一點是座標錯位最常見的原因。例如，以 130 DPI 掃描的 A4 頁面為 1075×1520 像素：兩邊都低於 1568 像素，但其成本為 39 × 55 = 2145 個視覺 token，因此 Claude 會將其調整為 924×1307。

接著，Claude 會對每張圖片（無論是否經過調整大小）在底部和右側邊緣填充至下一個 28 像素的倍數（在此範例中，924×1307 變為 924×1316）。填充區域不包含任何內容：Claude 感知的是填充後的圖片，但頁面內容只會佔據未填充的調整後區域。請始終以調整後的尺寸進行正規化或重新縮放，而非填充後的尺寸；除以填充後的尺寸會使每個座標產生微小的縮放偏差。



上傳前調整圖片大小

最可靠的方法是在上傳前自行調整圖片大小，這樣您手上的圖片就與 Claude 所見的圖片完全相同，Claude 回傳的座標無需轉換。

以下參考實作會計算 Claude 將圖片調整到的確切尺寸：

import math


def count_image_tokens(width: int, height: int) -> int:
    """Visual tokens consumed by an image: one token per 28x28 pixel patch."""
    return math.ceil(width / 28) * math.ceil(height / 28)


def resized_size(
    width: int,
    height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[int, int]:
    """The size Claude resizes an image to before padding.

    Defaults are for most models. For Claude Opus 4.7 and later models, use
    max_edge=2576 and max_tokens=4784. Returns (width, height). Images that
    already fit within the limits are returned unchanged.
    """

    def fits(w: int, h: int) -> bool:
        return (
            math.ceil(w / 28) * 28 <= max_edge
            and math.ceil(h / 28) * 28 <= max_edge
            and count_image_tokens(w, h) <= max_tokens
        )

    if fits(width, height):
        return (width, height)
    if height > width:
        resized_h, resized_w = resized_size(height, width, max_edge, max_tokens)
        return (resized_w, resized_h)

    # 沿長邊進行二分搜尋，找出保持長寬比且能容納的最大尺寸。
    # 
    aspect_ratio = width / height
    lo, hi = 1, width  # lo always fits; hi never fits
    while lo + 1 < hi:
        mid = (lo + hi) // 2
        if fits(mid, max(round(mid / aspect_ratio), 1)):
            lo = mid
        else:
            hi = mid
    return (lo, max(round(lo / aspect_ratio), 1))


# 來自「Claude 如何調整圖片大小與填充」的 A4 範例：
print(resized_size(1075, 1520))  # (924, 1307)

1. 將圖片調整為 resized_size 回傳的尺寸。如果圖片已符合模型的限制，resized_size 會回傳其原始尺寸，無需調整大小。
2. 將調整大小後的圖片傳送至 API。不要自行填充；Claude 會處理填充，且填充不會移動座標原點。
3. 在提示中明確要求像素座標。例如：「以像素座標回傳每個表格的邊界框，格式為 [x1, y1, x2, y2]。」
4. 直接將回傳的座標用於您傳送的圖片。如果您需要正規化座標，請除以您傳送的圖片尺寸，而非原始圖片的尺寸，也非填充後的尺寸。



無法預先調整大小時重新縮放座標

如果您無法預先調整大小（例如，當圖片來自您無法修改的上游系統時），請使用上傳前調整圖片大小中的 resized_size 來還原 Claude 所見的尺寸，然後將 Claude 回傳的座標對應為正規化座標或對應回您的原始圖片。此方法需要知道您上傳圖片的像素尺寸，因此不適用於 PDF 上傳。

def to_relative_coordinates(
    x: float,
    y: float,
    original_width: int,
    original_height: int,
    max_edge: int = 1568,
    max_tokens: int = 1568,
) -> tuple[float, float]:
    """Map a pixel coordinate returned by Claude to relative coordinates in [0, 1].

    Pass the dimensions of the image you uploaded. For Claude Opus 4.7 and
    later models, use max_edge=2576 and max_tokens=4784.
    """
    resized_w, resized_h = resized_size(
        original_width, original_height, max_edge, max_tokens
    )
    return (x / resized_w, y / resized_h)


# 若要將座標轉換為原始影像的像素空間，請將
# 相對座標乘以原始尺寸：
# (rel_x * original_width, rel_y * original_height)

填充僅套用於底部和右側邊緣，因此原點不會移動，按軸線性重新縮放即已足夠。



提示範例

許多適用於與 Claude 進行文字互動的提示技巧也可以應用於基於圖片的提示。

這些範例展示了涉及圖片的最佳實踐提示結構。



關於提示範例

以下範例展示如何使用各種程式語言和方法來使用 Claude 的視覺能力。您可以透過三種方式向 Claude 提供圖片：

1. 在 image 內容區塊中作為 base64 編碼的圖片
2. 作為線上託管圖片的 URL 引用
3. 使用 Files API（上傳一次，多次使用）

base64 範例提示使用以下變數：

import base64
import httpx

# 對於 base64 編碼的圖片
image1_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image1_media_type = "image/jpeg"
image1_data = base64.standard_b64encode(httpx.get(image1_url).content).decode("utf-8")

image2_url = "https://upload.wikimedia.org/wikipedia/commons/b/b5/Iridescent.green.sweat.bee1.jpg"
image2_media_type = "image/jpeg"
image2_data = base64.standard_b64encode(httpx.get(image2_url).content).decode("utf-8")

# 對於基於 URL 的圖片，您可以直接在請求中使用 URL

以下是如何使用 base64 編碼圖片和 URL 引用在 Messages API 請求中包含圖片的範例：



Base64 編碼圖片範例

image1_data = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC"
image1_media_type = "image/png"

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image1_media_type,
                        "data": image1_data,
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)



基於 URL 的圖片範例

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)
print(message)



Files API 圖片範例

對於您會重複使用的圖片，或當您想避免編碼開銷時，請使用 Files API。上傳圖片一次，然後在後續訊息中引用回傳的 file_id，而不是重新傳送 base64 資料。

client = anthropic.Anthropic()

# 上傳圖片檔案
with open("image.jpg", "rb") as f:
    file_upload = client.beta.files.upload(file=("image.jpg", f, "image/jpeg"))

# 在訊息中使用已上傳的檔案
message = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "Describe this image."},
            ],
        }
    ],
)

print(message.content)

更多範例程式碼和參數詳細資訊，請參閱 Messages API 範例。



限制

雖然 Claude 的圖片理解能力處於領先地位，但仍有一些需要注意的限制：

• 人物識別：Claude 不能用於識別圖片中人物的姓名，並會拒絕這樣做。
• 準確性：在解讀低品質、旋轉或小於 200 像素的極小圖片時，Claude 可能會產生幻覺或出錯。
• 空間推理：Claude 的座標和定位輸出是近似值。請遵循使用座標和邊界框中的指引，並在依賴輸出前進行驗證。
• 計數：Claude 可以給出圖片中物件的大約數量，但可能並非總是精確無誤，尤其是在有大量小物件的情況下。
• AI 生成的圖片：Claude 不知道圖片是否為 AI 生成，如果被詢問可能會回答錯誤。請勿依賴它來偵測假圖片或合成圖片。
• 不當內容：Claude 不會處理違反可接受使用政策的不當或露骨圖片。
• 醫療應用：雖然 Claude 可以分析一般醫療圖片，但它並非設計用於解讀複雜的診斷掃描，如 CT 或 MRI。Claude 的輸出不應被視為專業醫療建議或診斷的替代品。

請務必仔細審查和驗證 Claude 的圖片解讀，尤其是在高風險的使用案例中。對於需要完美精確度或敏感圖片分析的任務，請勿在沒有人工監督的情況下使用 Claude。



常見問題



深入了解視覺功能

準備好開始使用 Claude 處理圖片了嗎？以下是一些有用的資源：

• 多模態 cookbook：此 cookbook 包含開始使用圖片的技巧和最佳實踐技術，以確保使用圖片時獲得最高品質的效能。了解如何有效地使用圖片向 Claude 提示以執行任務，例如解讀和分析圖表或從表單中擷取內容。
• API 參考：Messages API 的文件，包括涉及圖片的 API 呼叫範例。

如果您有任何其他問題，請聯絡支援團隊。您也可以加入開發者社群，與其他創作者交流並獲得 Anthropic 專家的協助。