處理檔案

Files API

使用 Files API 上傳和管理檔案，以便在 Claude API 中重複使用，無需每次請求都重新上傳內容。

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

Files API 目前處於測試版。請透過意見回饋表單分享您使用 Files 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+ 模型中受支援。

Files API 目前不支援 Amazon Bedrock 或 Google Vertex AI。

Files API 的運作方式

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

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

如何使用 Files API

若要使用 Files API，您需要在請求中加入測試版功能標頭：anthropic-beta: files-api-2025-04-14。

上傳檔案

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

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

上傳檔案的回應將包含：

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 引用該檔案：

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "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"
          }
        }
      ]
    }
  ]
}
EOF

檔案類型與內容區塊

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

檔案類型	MIME 類型	內容區塊類型	使用情境
PDF	`application/pdf`	`document`	文字分析、文件處理
純文字	`text/plain`	`document`	文字分析、處理
圖片	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	圖片分析、視覺任務
資料集及其他	不定	`container_upload`	分析資料、建立視覺化圖表

處理其他檔案格式

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

# 範例：讀取文字檔案並以純文字形式傳送
# 注意：對於含有特殊字元的檔案，請考慮使用 base64 編碼
# ...
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

對於包含圖片的 .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"
  }
}

管理檔案

列出檔案

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

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

取得檔案中繼資料

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

curl "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

刪除檔案

從您的工作區移除檔案：

curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

下載檔案

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

curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output 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)： 檔案類型與內容區塊類型不符（例如，在文件區塊中使用圖片檔案）
超過上下文視窗大小 (400)： 檔案大於上下文視窗大小（例如，在 /v1/messages 請求中使用 500 MB 的純文字檔案）
無效的檔案名稱 (400)： 檔案名稱不符合長度要求（1-255 個字元），或包含禁止的字元（<、>、:、"、|、?、*、\、/，或 unicode 字元 0-31）
檔案過大 (413)： 檔案超過 500 MB 的限制
超過儲存限制 (403)： 您的組織已達到 500 GB 的儲存限制

Output

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

使用量與計費

Files API 操作為免費：

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

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

速率限制

在測試版期間：

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

Was this page helpful?

處理檔案

Files API

使用 Files API 上傳和管理檔案，以便在 Claude API 中重複使用，無需每次請求都重新上傳內容。

Files API 目前處於測試版。請透過意見回饋表單分享您使用 Files API 的體驗。

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

支援的模型

Files API 目前不支援 Amazon Bedrock 或 Google Vertex AI。

Files API 的運作方式

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

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

如何使用 Files API

若要使用 Files API，您需要在請求中加入測試版功能標頭：anthropic-beta: files-api-2025-04-14。

上傳檔案

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

curl -X POST https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -F "file=@/path/to/document.pdf"

上傳檔案的回應將包含：

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 引用該檔案：

curl -X POST https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "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"
          }
        }
      ]
    }
  ]
}
EOF

檔案類型與內容區塊

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

檔案類型	MIME 類型	內容區塊類型	使用情境
PDF	`application/pdf`	`document`	文字分析、文件處理
純文字	`text/plain`	`document`	文字分析、處理
圖片	`image/jpeg`, `image/png`, `image/gif`, `image/webp`	`image`	圖片分析、視覺任務
資料集及其他	不定	`container_upload`	分析資料、建立視覺化圖表

處理其他檔案格式

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

# 範例：讀取文字檔案並以純文字形式傳送
# 注意：對於含有特殊字元的檔案，請考慮使用 base64 編碼
# ...
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d @- <<EOF
{
  "model": "claude-opus-4-6",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Here's the document content:\n\n${TEXT_CONTENT}\n\nPlease summarize this document."
        }
      ]
    }
  ]
}
EOF

對於包含圖片的 .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"
  }
}

管理檔案

列出檔案

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

curl https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

取得檔案中繼資料

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

curl "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

刪除檔案

從您的工作區移除檔案：

curl -X DELETE "https://api.anthropic.com/v1/files/$FILE_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

下載檔案

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

curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  --output 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)： 檔案類型與內容區塊類型不符（例如，在文件區塊中使用圖片檔案）
超過上下文視窗大小 (400)： 檔案大於上下文視窗大小（例如，在 /v1/messages 請求中使用 500 MB 的純文字檔案）
無效的檔案名稱 (400)： 檔案名稱不符合長度要求（1-255 個字元），或包含禁止的字元（<、>、:、"、|、?、*、\、/，或 unicode 字元 0-31）
檔案過大 (413)： 檔案超過 500 MB 的限制
超過儲存限制 (403)： 您的組織已達到 500 GB 的儲存限制

Output

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

使用量與計費

Files API 操作為免費：

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

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

速率限制

在測試版期間：

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

Was this page helpful?