Files API

リクエストのたびに同じ内容を送り直す必要はありません。アップロードしたファイルは file_id で Messages リクエストから参照します。コード実行ツールと組み合わせると、データセットや文書を入力として渡し、グラフなどの出力をダウンロードできます。

Files API でアップロードしたファイルは、file_id を使って Messages リクエストから参照します。リクエストごとに内容を送り直す必要はありません。

ファイルの種類によって、対応する content block が異なります。

• PDF とプレーンテキスト: document content block
• 画像: image content block
• データセットなどその他のファイル: container_upload content block

保存したファイルは、list・retrieve・delete の操作で管理します。

ファイルは、DELETE /v1/files/{file_id} エンドポイントで削除するか、expires_at に達するまで保持されます。削除したファイルは復元できません。

• アップロード後にファイルを変更したり、名前を変えたりすることはできません。内容を変えるには、新しいファイルをアップロードし、古いファイルを削除します。
• 自動で失効させるには、アップロード時に expires_in_seconds のフォームフィールド (3,600 から 7,776,000 までの整数) を含めます。ファイルオブジェクトは expires_at を返します。
• 有効期限はアップロード時に一度だけ設定でき、後から変更できません。
• expires_at に達したファイルを参照する Messages リクエストは、推論の前に失敗します。

ファイル一覧のエンドポイントはページネーションに対応しており、1 回のリクエストで limit 件 (既定は 20 件、最大 1,000 件) までを新しい順に返します。ページの移動には page と next_page を使います。

特定のファイル群をまとめて確認するときは、最大 100 件のファイル ID を ids[] クエリパラメーターとして渡せます。ids[] は page や limit と組み合わせられません。

コード実行ツールが生成したファイルの file_id は、それを作成した Messages 応答の bash_code_execution_tool_result content block に含まれます。この file_id を使い、GET /v1/files/$FILE_ID/content または ant files download --file-id "$FILE_ID" --output downloaded_file.txt でダウンロードします。Claude API では、コード実行ツールで Claude が生成した対応形式の画像・動画・音声ファイル (skills が作成したファイルを含む) に、ダウンロード時に署名付きの C2PA Content Credentials が付きます。

• アップロードしたファイルは、エンドユーザー・会話・セッション単位で区切られません。ワークスペースにアクセスできる API キーであれば、そのワークスペースにアップロードされたどのファイルにもアクセスできます。
• 組織で Compliance API を有効にしている場合、Activity Feed には Files API のアップロード、内容のダウンロード、削除が記録されます。ファイル一覧の取得とメタデータの取得は記録されません。
• 削除したファイルは復元できません。

1. POST https://api.anthropic.com/v1/files にファイルを送ってアップロードします。CLI では ant files upload --file /path/to/document.pdf も使えます。
2. アップロードの応答に含まれる id を file_id として content block (たとえば source type が file の document block) に渡し、Messages リクエストからファイルを参照します。