Files API
Anthropic APIで使用するファイルをアップロードおよび管理するためのFiles APIについて学びます。
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呼び出しで参照するファイルをアップロードします:
メッセージでのファイルの使用
アップロード後、file_id
を使用してファイルを参照します:
ファイルタイプとコンテンツブロック
Files APIは、異なるコンテンツブロックタイプに対応する異なるファイルタイプをサポートしています:
ファイルタイプ | MIMEタイプ | コンテンツブロックタイプ | 使用例 |
---|---|---|---|
application/pdf | document | テキスト分析、ドキュメント処理 | |
プレーンテキスト | text/plain | document | テキスト分析、処理 |
画像 | image/jpeg , image/png , image/gif , image/webp | image | 画像分析、視覚的タスク |
データセット、その他 | 様々 | container_upload | データ分析、可視化の作成 |
その他のファイル形式での作業
document
ブロックとしてサポートされていないファイルタイプ(.csv、.txt、.md、.docx、.xlsx)については、ファイルをプレーンテキストに変換し、コンテンツを直接メッセージに含めてください:
画像を含む.docxファイルの場合、まずPDF形式に変換してから、PDFサポートを使用して組み込み画像解析を活用してください。これにより、PDFドキュメントからの引用を使用できます。
ドキュメントブロック
PDFおよびテキストファイルの場合、document
コンテンツブロックを使用します:
画像ブロック
画像の場合、image
コンテンツブロックを使用します:
ファイルの管理
ファイルのリスト
アップロードしたファイルのリストを取得します:
ファイルメタデータの取得
特定のファイルに関する情報を取得します:
ファイルの削除
ワークスペースからファイルを削除します:
ファイルのダウンロード
コード実行ツールによって作成されたファイルをダウンロードします:
コード実行ツールによって作成されたファイルのみダウンロードできます。アップロードしたファイルはダウンロードできません。
ファイルストレージと制限
ストレージ制限
- 最大ファイルサイズ: ファイルあたり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ストレージ制限に達しています
使用と課金
File API操作は無料です:
- ファイルのアップロード
- ファイルのダウンロード
- ファイルのリスト
- ファイルメタデータの取得
- ファイルの削除
Messages
リクエストで使用されるファイルコンテンツは入力トークンとして価格設定されます。コード実行ツールによって作成されたファイルのみダウンロードできます。
レート制限
ベータ期間中:
- ファイル関連のAPI呼び出しは1分あたり約100リクエストに制限されています
- 使用例でより高い制限が必要な場合は、お問い合わせください