Files APIを使用すると、リクエストごとにコンテンツを再アップロードすることなく、Claude APIで使用するファイルをアップロードして管理できます。これは、コード実行ツールを使用して入力（データセットやドキュメントなど）を提供し、出力（チャートなど）をダウンロードする際に特に便利です。また、Files APIを使用して、複数のAPI呼び出しで頻繁に使用されるドキュメントや画像を継続的に再アップロードする必要を防ぐこともできます。このガイドに加えて、APIリファレンスを直接探索することもできます。
Files APIは現在ベータ版です。Files APIでの体験を共有するために、フィードバックフォームからお問い合わせください。

​
サポートされているモデル

Messagesリクエストでfile_idを参照することは、指定されたファイルタイプをサポートするすべてのモデルでサポートされています。例えば、画像はすべてのClaude 3+モデルでサポートされ、PDFはすべてのClaude 3.5+モデルでサポートされ、その他のさまざまなファイルタイプはClaude 3.5 HaikuとすべてのClaude 3.7+モデルのコード実行ツールでサポートされています。 Files APIは現在、Amazon BedrockやGoogle Vertex AIではサポートされていません。

​
Files APIの仕組み

Files APIは、ファイルを扱うためのシンプルな一度作成して何度でも使用するアプローチを提供します：
  • ファイルをアップロードして安全なストレージに保存し、一意のfile_idを受け取る
  • ファイルをダウンロードしてコード実行ツールから作成されたファイルを取得する
  • ファイルを参照して、コンテンツを再アップロードする代わりにfile_idを使用してMessagesリクエストで使用する
  • ファイルを管理してリスト、取得、削除操作を行う

​
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-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "このドキュメントを要約してください。"          
          },
          {
            "type": "document",
            "source": {
              "type": "file",
              "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
            }
          }
        ]
      }
    ]
  }'

​
ファイルタイプとコンテンツブロック

Files APIは、異なるコンテンツブロックタイプに対応する異なるファイルタイプをサポートしています：
ファイルタイプMIMEタイプコンテンツブロックタイプ使用例
PDFapplication/pdfdocumentテキスト分析、ドキュメント処理
プレーンテキストtext/plaindocumentテキスト分析、処理
画像image/jpeg, image/png, image/gif, image/webpimage画像分析、視覚的タスク
データセット、その他様々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-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "ドキュメントの内容は以下の通りです：\n\n${TEXT_CONTENT}\n\nこのドキュメントを要約してください。"
        }
      ]
    }
  ]
}
EOF
画像を含む.docxファイルについては、まずPDF形式に変換してから、PDFサポートを使用して組み込みの画像解析を活用してください。これにより、PDFドキュメントからの引用を使用できます。

​
ドキュメントブロック

PDFとテキストファイルについては、documentコンテンツブロックを使用します： 
{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_011CNha8iCJcU1wXNR6q4V8w"
  },
  "title": "ドキュメントタイトル", // オプション
  "context": "ドキュメントに関するコンテキスト", // オプション  
  "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文字）を満たしていないか、禁止文字（<、>、:、"、|、?、*、\、/、またはユニコード文字0-31）が含まれています
  • ファイルが大きすぎる（413）： ファイルが500 MB制限を超えています
  • ストレージ制限を超過（403）： 組織が100 GBストレージ制限に達しています
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_011CNha8iCJcU1wXNR6q4V8w"
  }
}

​
使用量と請求

File API操作は無料です：
  • ファイルのアップロード
  • ファイルのダウンロード
  • ファイルのリスト表示
  • ファイルメタデータの取得
  • ファイルの削除
Messagesリクエストで使用されるファイルコンテンツは入力トークンとして価格設定されます。コード実行ツールによって作成されたファイルのみダウンロードできます。

​
レート制限

ベータ期間中：
  • ファイル関連のAPI呼び出しは1分あたり約100リクエストに制限されています
  • 使用例でより高い制限が必要な場合は、お問い合わせください