功能

Files API

Files API 讓您上傳和管理檔案，以便與 Claude API 搭配使用，無需在每次請求時重新上傳內容。

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

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

支援的模型

在 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 提供簡單的一次建立、多次使用的檔案處理方式：

上傳檔案到我們的安全儲存空間並接收唯一的 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"

上傳檔案的回應將包含：

{
  "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 '{
    "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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

檔案類型和內容區塊

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 編碼
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

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_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w/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
**總儲存空間：**每個組織 100 GB

檔案生命週期

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

錯誤處理

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

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

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

使用量和計費

File API 操作是免費的：

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

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

速率限制

在測試版期間：

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

Was this page helpful?

功能

Files API

Files API 讓您上傳和管理檔案，以便與 Claude API 搭配使用，無需在每次請求時重新上傳內容。

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

支援的模型

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

Files API 的運作方式

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

上傳檔案到我們的安全儲存空間並接收唯一的 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"

上傳檔案的回應將包含：

{
  "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 '{
    "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_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

檔案類型和內容區塊

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 編碼
TEXT_CONTENT=$(cat document.txt | jq -Rs .)

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_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w \
  -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_011CNha8iCJcU1wXNR6q4V8w/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
**總儲存空間：**每個組織 100 GB

檔案生命週期

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

錯誤處理

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

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

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

使用量和計費

File API 操作是免費的：

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

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

速率限制

在測試版期間：

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

Was this page helpful?