Files APIを使用すると、リクエストごとにコンテンツを再アップロードすることなく、Anthropic APIで使用するファイルをアップロードおよび管理できます。これは、コード実行ツールを使用して入力（データセットやドキュメントなど）を提供し、出力（チャートなど）をダウンロードする場合に特に便利です。また、Files 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"

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

Files APIは、異なるコンテンツブロックタイプに対応する異なるファイルタイプをサポートしています：

ファイルタイプMIMEタイプコンテンツブロックタイプユースケース
PDFapplication/pdfdocumentテキスト分析、ドキュメント処理
プレーンテキストtext/plaindocumentテキスト分析、処理
画像image/jpeg, image/png, image/gif, image/webpimage画像分析、視覚的タスク
データセット、その他様々container_uploadデータ分析、可視化の作成

​
ドキュメントブロック

PDFとテキストファイルには、documentコンテンツブロックを使用します：

{
  "type": "document",
  "source": {
    "type": "file",
    "file_id": "file_abc123"
  },
  "title": "Document Title", // オプション
  "context": "Context about the document", // オプション  
  "citations": {"enabled": true} // オプション、引用を有効にする
}

​
画像ブロック

画像には、imageコンテンツブロックを使用します：

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

​
ファイルの管理

​
ファイル一覧の取得

アップロードしたファイルのリストを取得します：

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_abc123 \
  -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_abc123 \
  -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_abc123/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

コード実行ツールによって作成されたファイルのみダウンロードできます。アップロードしたファイルはダウンロードできません。

​
ファイルストレージと制限

​
ストレージ制限

  • 最大ファイルサイズ： ファイルあたり32 MB
  • 総ストレージ： 組織あたり100 GB

​
ファイルのライフサイクル

  • ファイルはAPIキーのワークスペースにスコープされます。同じワークスペースに関連付けられた他のAPIキーは、他のAPIキーによって作成されたファイルを使用できます
  • ファイルは削除するまで保持されます
  • 削除されたファイルは復元できません
  • ファイルは削除後すぐにAPIからアクセスできなくなりますが、アクティブなMessages API呼び出しと関連するツールの使用では引き続き存在する場合があります

​
エラー処理

Files API使用時の一般的なエラーには以下が含まれます：

  • ファイルが見つかりません（404）： 指定されたfile_idが存在しないか、アクセス権がありません
  • 無効なファイルタイプ（400）： ファイルタイプがコンテンツブロックタイプと一致しません（例：ドキュメントブロックで画像ファイルを使用）
  • ファイルが大きすぎます（413）： ファイルが500 MBの制限を超えています
  • ストレージ制限を超えました（403）： 組織が100 GBのストレージ制限に達しました
  • 無効なファイル名（400）： ファイル名が長さの要件（1〜255文字）を満たしていないか、禁止文字（<、>、:、"、|、?、*、\、/、またはUnicode文字0-31）が含まれています
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "File not found: file_abc123"
  }
}

​
使用量と課金

File API操作は無料です：

  • ファイルのアップロード
  • ファイルのダウンロード
  • ファイル一覧の取得
  • ファイルメタデータの取得
  • ファイルの削除

Messagesリクエストで使用されるファイルコンテンツは入力トークンとして課金されます。コード実行ツールによって作成されたファイルのみダウンロードできます。

​
レート制限

ベータ期間中：

  • ファイル関連のAPI呼び出しは、約1分あたり100リクエストに制限されています
  • ユースケースに応じてより高い制限が必要な場合は、お問い合わせください