Files API

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



支援的模型

在 Messages 請求中引用 file_id 的功能，在所有支援該檔案類型的模型上均可使用。圖片在所有目前的 Claude 模型上均受支援。關於 PDF 和程式碼執行工具支援的其他檔案類型，請參閱連結頁面以了解模型支援情況。

Files API 可在 Claude API、AWS 上的 Claude Platform 和 Microsoft Foundry 上使用。目前尚未在 Amazon Bedrock 或 Vertex AI 上提供。



Files API 的運作方式

Files API 提供了一種簡單的「一次建立、多次使用」方法來處理檔案：

• 上傳檔案至 Anthropic 的安全儲存空間，並取得唯一的 file_id
• 下載檔案，這些檔案由技能（skills）或程式碼執行工具所建立
• 在 Messages 請求中使用 file_id 引用檔案，而無需重新上傳內容
• 透過列出、擷取和刪除操作來管理您的檔案



如何使用 Files API



上傳檔案

上傳檔案以便在未來的 API 呼叫中引用：

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

上傳檔案的回應將包含：

{
  "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 來引用檔案：

response = client.beta.messages.create(
    model="claude-opus-4-8",
    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)



檔案類型與內容區塊

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



處理其他檔案格式

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

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

# 以純文字形式在訊息中傳送
response = client.messages.create(
    model="claude-opus-4-8",
    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)



Document 區塊

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

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "Document Title", // Optional
  "context": "Context about the document", // Optional
  "citations": { "enabled": true } // Optional, enables citations
}



Image 區塊

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

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



管理檔案



列出檔案

擷取您已上傳檔案的清單：

client = anthropic.Anthropic()
files = client.beta.files.list()



取得檔案中繼資料

擷取特定檔案的相關資訊：

file = client.beta.files.retrieve_metadata(file_id)



刪除檔案

從您的工作區移除檔案：

result = client.beta.files.delete(file_id)



下載檔案

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

file_content = client.beta.files.download(file_id)

# Save to file
file_content.write_to_file("downloaded_file.txt")



檔案儲存與限制



儲存限制

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



檔案生命週期

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



資料保留

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

關於所有功能的 ZDR 資格，請參閱 API 與資料保留。



錯誤處理

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

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

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



使用量與計費

File API 操作是免費的：

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

在 Messages 請求中使用的檔案內容會以輸入 token 計價。您只能下載由技能或程式碼執行工具所建立的檔案。



速率限制

在測試期間：

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