檔案 API
檔案 API 讓您可以上傳和管理檔案,以便在 Anthropic API 中使用,而無需在每次請求時重新上傳內容。這在使用程式碼執行工具提供輸入(例如資料集和文件)然後下載輸出(例如圖表)時特別有用。您還可以使用檔案 API 避免在多個 API 呼叫中重複上傳經常使用的文件和圖像。
檔案 API 目前處於 beta 階段。請通過我們的意見表單分享您使用檔案 API 的體驗。
支援的模型
在 Messages 請求中引用 file_id
在所有支援該檔案類型的模型中都受支援。例如,圖像在所有 Claude 3+ 模型中都受支援,PDF在所有 Claude 3.5+ 模型中都受支援,以及各種其他檔案類型在 Claude 3.5 Haiku 和所有 Claude 3.7+ 模型中的程式碼執行工具都受支援。
檔案 API 目前不支援 Amazon Bedrock 或 Google Vertex AI。
檔案 API 的工作原理
檔案 API 提供了一種簡單的「建立一次,多次使用」的檔案處理方式:
- 上傳檔案到我們的安全儲存空間並接收唯一的
file_id
- 下載檔案,這些檔案是由程式碼執行工具創建的
- 在Messages請求中使用
file_id
引用檔案,而不是重新上傳內容 - 通過列表、檢索和刪除操作管理您的檔案
如何使用檔案 API
要使用檔案 API,您需要包含 beta 功能標頭:anthropic-beta: files-api-2025-04-14
。
上傳檔案
上傳檔案以便在未來的 API 呼叫中引用:
檔案類型和內容區塊
檔案 API 支援不同的檔案類型,這些類型對應於不同的內容區塊類型:
檔案類型 | MIME 類型 | 內容區塊類型 | 使用案例 |
---|---|---|---|
application/pdf | document | 文本分析、文件處理 | |
純文本 | text/plain | document | 文本分析、處理 |
圖像 | image/jpeg , image/png , image/gif , image/webp | image | 圖像分析、視覺任務 |
資料集、其他 | 各種 | container_upload | 分析數據、創建視覺化 |
文件區塊
對於 PDF 和文本檔案,使用 document
內容區塊:
圖像區塊
對於圖像,使用 image
內容區塊:
管理檔案
列出檔案
檢索您上傳的檔案列表:
獲取檔案元數據
檢索有關特定檔案的信息:
刪除檔案
從您的工作區中移除檔案:
下載檔案
下載由程式碼執行工具創建的檔案:
您只能下載由程式碼執行工具創建的檔案。您上傳的檔案無法下載。
檔案儲存和限制
儲存限制
- 最大檔案大小: 每個檔案 32 MB
- 總儲存空間: 每個組織 100 GB
檔案生命週期
- 檔案的範圍限於 API 金鑰的工作區。與同一工作區相關聯的其他 API 金鑰可以使用由任何其他 API 金鑰創建的檔案
- 檔案會一直保存,直到您刪除它們
- 已刪除的檔案無法恢復
- 檔案在刪除後不久就無法通過 API 訪問,但它們可能會在活動的
Messages
API 呼叫和相關工具使用中持續存在
錯誤處理
使用檔案 API 時常見的錯誤包括:
- 找不到檔案 (404): 指定的
file_id
不存在或您沒有訪問權限 - 無效的檔案類型 (400): 檔案類型與內容區塊類型不匹配(例如,在文件區塊中使用圖像檔案)
- 檔案太大 (413): 檔案超過 500 MB 限制
- 超出儲存限制 (403): 您的組織已達到 100 GB 儲存限制
- 無效的檔案名 (400): 檔案名不符合長度要求(1-255 個字符)或包含禁止的字符(
<
、>
、:
、"
、|
、?
、*
、\
、/
或 Unicode 字符 0-31)
使用和計費
檔案 API 操作是免費的:
- 上傳檔案
- 下載檔案
- 列出檔案
- 獲取檔案元數據
- 刪除檔案
在 Messages
請求中使用的檔案內容按輸入標記計費。您只能下載由程式碼執行工具創建的檔案。
速率限制
在 beta 期間:
- 與檔案相關的 API 呼叫限制為每分鐘約 100 個請求
- 如果您的使用案例需要更高的限制,請聯繫我們