檔案 API

Files API

檔案 API 讓您上傳和管理檔案以供 Claude API 使用，無需在每次請求時重新上傳內容。這在使用程式碼執行工具提供輸入（例如資料集和文件）然後下載輸出（例如圖表）時特別有用。您也可以使用檔案 API 來避免在多個 API 呼叫中持續重新上傳常用的文件和圖像。您可以直接探索 API 參考，除了本指南外。

檔案 API 處於測試版。請透過意見回饋表單分享您對檔案 API 的體驗。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

支援的模型

在 Messages 請求中參考 file_id 在所有支援該檔案類型的模型中都受支援。例如，圖像在所有 Claude 3+ 模型中受支援，PDF 在所有 Claude 3.5+ 模型中受支援，以及各種其他檔案類型在 Claude Haiku 4.5 及所有 Claude 3.7+ 模型中用於程式碼執行工具。

檔案 API 目前在 Amazon Bedrock 或 Google Vertex AI 上不受支援。

檔案 API 如何運作

檔案 API 提供了一個簡單的一次上傳、多次使用的方法來處理檔案：

上傳檔案到 Anthropic 的安全儲存空間並接收唯一的 file_id
下載由技能或程式碼執行工具建立的檔案
在 Messages 請求中參考檔案，使用 file_id 而不是重新上傳內容
管理您的檔案，進行列表、檢索和刪除操作

如何使用檔案 API

要使用檔案 API，您需要包含測試版功能標頭：anthropic-beta: files-api-2025-04-14。

上傳檔案

上傳檔案以在未來的 API 呼叫中參考：

上傳檔案的回應將包括：

Output

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}

在訊息中使用檔案

上傳後，使用其 file_id 參考檔案：

檔案類型和內容區塊

檔案 API 支援對應於不同內容區塊類型的不同檔案類型：

檔案類型	MIME 類型	內容區塊類型	使用案例
PDF	`application/pdf`	`document`	文字分析、文件處理
純文字	`text/plain`	`document`	文字分析、處理
圖像	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	圖像分析、視覺任務
資料集、其他	變動

使用其他檔案格式

對於不支援作為 document 區塊的檔案類型（.csv、.txt、.md、.docx、.xlsx），將檔案轉換為純文字，並直接在您的訊息中包含內容：

對於包含圖像的 .docx 檔案，請先將其轉換為 PDF 格式，然後使用PDF 支援以利用內建的圖像解析。這允許使用 PDF 文件中的引用。

文件區塊

對於 PDF 和文字檔案，使用 document 內容區塊：

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // 選用
  "context": "Context about the document", // 選用
  "citations": { "enabled": true } // 選用，啟用引用
}

圖像區塊

對於圖像，使用 image 內容區塊：

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

管理檔案

列出檔案

檢索您上傳的檔案列表：

取得檔案中繼資料

檢索特定檔案的資訊：

刪除檔案

從您的工作區中移除檔案：

下載檔案

下載由技能或程式碼執行工具建立的檔案：

您只能下載由技能或程式碼執行工具建立的檔案。您上傳的檔案無法下載。

檔案儲存和限制

儲存限制

最大檔案大小： 每個檔案 500 MB
總儲存空間： 每個組織 500 GB

檔案生命週期

檔案的範圍限於 API 金鑰的工作區。其他 API 金鑰可以使用由與同一工作區相關聯的任何其他 API 金鑰建立的檔案
檔案會持續存在，直到您刪除它們
已刪除的檔案無法恢復
檔案在刪除後不久將無法透過 API 存取，但它們可能會在活躍的 Messages API 呼叫和相關工具使用中持續存在
使用者刪除的檔案將根據 Anthropic 的資料保留政策進行刪除。

資料保留

透過檔案 API 上傳的檔案會保留，直到使用 DELETE /v1/files/{file_id} 端點明確刪除為止。檔案會儲存以供在多個 API 請求中重複使用。

如需所有功能的 ZDR 資格，請參閱 API 和資料保留。

錯誤處理

使用檔案 API 時的常見錯誤包括：

檔案未找到 (404)： 指定的 file_id 不存在或您無法存取它
無效的檔案類型 (400)： 檔案類型與內容區塊類型不符（例如，在文件區塊中使用圖像檔案）
超過內容視窗大小 (400)： 檔案大於內容視窗大小（例如在 /v1/messages 請求中使用 500 MB 純文字檔案）
無效的檔案名稱 (400)： 檔案名稱不符合長度要求（1-255 個字元）或包含禁止的字元（<、>、:、"、|、?、*、\、/ 或 unicode 字元 0-31）
檔案太大 (413)： 檔案超過 500 MB 限制
您的組織已達到 500 GB 儲存限制

Output

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

使用和計費

檔案 API 操作免費：

上傳檔案
下載檔案
列出檔案
取得檔案中繼資料
刪除檔案

在 Messages 請求中使用的檔案內容按輸入令牌計費。您只能下載由技能或程式碼執行工具建立的檔案。

速率限制

在測試版期間：

檔案相關的 API 呼叫限制為每分鐘約 100 個請求
如果您的使用案例需要更高的限制，請聯絡我們

response = client.beta.messages.create(
    model="claude-opus-4-6",
    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,
                    },
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)
print(response)

import pandas as pd
# ...
# 範例：讀取 CSV 檔案
df = pd.read_csv("data.csv")
csv_content = df.to_string()

# 在訊息中作為純文字發送
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": f"Here's the CSV data:\n\n{csv_content}\n\nPlease analyze this data.",
                }
            ],
        }
    ],
)

print(response.content[0].text)