ホーム / チュートリアル / Claude API の Files API

Claude API の Files API

Claude API エンジニアリング 7分で読めます

Files API は、ファイルを一度アップロードして file_id を受け取り、以降の Messages リクエストではその ID を指定するだけで参照できるようにする機能です。同じ PDF や画像を毎回リクエストに埋め込み直す必要がなくなり、コード実行ツールの入力・出力の受け渡しにも使えます。

本ページは Anthropic 公式ドキュメントをもとにした非公式の日本語解説です。仕様は変更されることがあるため、実装前に必ず公式ドキュメントで最新の内容をご確認ください。Files API は本記事の作成時点でベータ機能です。

Files API とは

Files API は「一度作って、何度も使う」ための仕組みです。できることは大きく4つあります。

特に効くのは、コード実行ツールにデータセットや文書を渡し、生成されたグラフなどを受け取るという流れです。入力を毎回送り直さずに済み、出力は file_id 経由で取り出せます。

利用するには、ベータ機能のヘッダを付ける必要があります。

anthropic-beta: files-api-2025-04-14

各言語の SDK では、beta.files 名前空間のメソッドを呼ぶとこのヘッダが自動的に付きます。ただし、ファイルを参照する Messages リクエスト側には別途 betas パラメータで指定が必要です。ここは取り違えやすい部分です。

提供範囲は Claude API、Claude Platform on AWS、Microsoft Foundry です。Microsoft Foundry では Hosted on Anthropic のデプロイが前提になります。Amazon Bedrock と Google Cloud では現時点で利用できません。

アップロードと参照

アップロードは POST /v1/files にマルチパートでファイルを送ります。

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_id になります）のほか、filename、mime_type、size_bytes、created_at、downloadable が含まれます。

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file",
  "filename": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false
}

自分でアップロードしたファイルの downloadable は false です。ダウンロードできるのはスキルまたはコード実行ツールが生成したファイルだけ、という点は最初に押さえておいてください。

Python SDK では次のように書きます。

uploaded = client.beta.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id

参照するときは、Messages リクエストのコンテンツブロックで source.type を "file" にし、file_id を渡します。

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file_id},
                },
            ],
        }
    ],
    betas=["files-api-2025-04-14"],
)

ここで betas=["files-api-2025-04-14"] を忘れないでください。アップロード側だけベータ指定して Messages 側で落ちる、というのはよくある詰まり方です。

ファイル形式とコンテンツブロック

ファイルの種類によって、使うコンテンツブロックが変わります。

ファイル種別MIME タイプコンテンツブロック用途
PDFapplication/pdfdocumentテキスト解析・文書処理
プレーンテキストtext/plaindocumentテキスト解析・処理
画像image/jpeg, image/png, image/gif, image/webpimage画像解析・視覚タスク
データセットなど種類によるcontainer_uploadデータ分析・可視化の生成

PDF とテキストは document ブロックです。任意で title、context、citations を付けられます。

{
  "type": "document",
  "source": { "type": "file", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" },
  "title": "Document Title",
  "context": "Context about the document",
  "citations": { "enabled": true }
}

画像は image ブロック、コード実行ツールへ渡す場合は container_upload ブロックを使います。container_upload だけは source でくるまず、直接 file_id を書く点が他と違います。

{ "type": "container_upload", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w" }

document ブロックが対応しない形式

.docx や .xlsx は document ブロックでは扱えません。プレーンテキストに変換してメッセージ本文へ直接含めるのが基本方針です。.csv や .md のようにもともとテキストのものは、本文へ含めても、text/plain を明示して Files API にアップロードしても構いません。

データセットとして分析させたい場合は、テキストとして読ませるのではなく container_upload でコード実行ツールに渡します。画像を含む .docx は、いったん PDF に変換すると PDF サポートの画像解析と引用が使えます。

ファイルの管理とダウンロード

一覧

GET /v1/files でアップロード済みファイルを取得します。ページングされており、1回のリクエストで返るのは既定 20 件です。before_id と after_id で前後のページを取ります。SDK には自動ページングのヘルパーがあります。

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"

メタデータ取得と削除

個別のファイル情報は GET /v1/files/{file_id}、削除は DELETE /v1/files/{file_id} です。削除したファイルは復元できません。

ダウンロード

ダウンロードは GET /v1/files/{file_id}/content です。対象になるのは、スキルまたはコード実行ツールが生成したファイルだけです。生成されたファイルの file_id は、それを作った Messages レスポンスの bash_code_execution_tool_result コンテンツブロックに現れます。

curl -X GET "https://api.anthropic.com/v1/files/$FILE_ID/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

メタデータの downloadable が true のときだけ成功します。自分がアップロードしたファイルをダウンロードしようとすると 400 エラーになります。

ライフサイクル

制限と料金

サイズと容量

料金

Files API の操作そのもの（アップロード・ダウンロード・一覧・メタデータ取得・削除）は無料です。課金されるのは、Messages リクエストで実際に使われたファイル内容で、これは入力トークンとして計上されます。

つまり、アップロードしただけでは費用は発生せず、参照して初めてトークン課金になります。同じファイルを何度も参照すれば、そのつど入力トークンがかかる点は変わりません。Files API が削減するのは転送の手間であって、トークンではないということです。

レート制限

ベータ期間中、ファイル関連の API 呼び出しはおおよそ毎分 100 リクエストに制限されています。それ以上が必要な場合は Anthropic への問い合わせが案内されています。

よくあるエラー

公式ドキュメントに挙げられている主なエラーは次のとおりです。原因が分かれば対処は速いので、対応表として持っておくと役立ちます。

エラー原因
File not found (404)指定した file_id が存在しない、またはアクセス権がない
Invalid file type (400)ファイル種別とコンテンツブロックの型が合っていない（画像ファイルを document ブロックで使った等）
Not downloadable (400)自分でアップロードしたファイルをダウンロードしようとした
Exceeds context window size (400)ファイルがコンテキストウィンドウより大きい（500 MB のテキストを /v1/messages で使う等）
Invalid filename (400)ファイル名が 1〜255 文字の範囲外、または禁止文字を含む
File too large (413)500 MB の上限を超えている
Storage limit exceeded (400)組織の 500 GB 上限に達している

ファイル名の禁止文字は <、>、:、"、|、?、*、\、/、および Unicode の 0〜31 です。日本語のファイル名をそのまま扱う場合は、この範囲に触れていないかを確認してください。

エラーレスポンスの形は次のとおりで、request_id が付きます。問い合わせるときはこれを添えます。

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "File `file_011CNha8iCJcU1wXNR6q4V8w` not found."
  },
  "request_id": "req_011CQFYcrRp7mCHLDsAYT8Qt"
}

実際に多いのは、ベータヘッダの付け忘れ（特に Messages 側）と、container_upload と document の取り違えです。まずこの2つを疑うと切り分けが速くなります。

関連チュートリアル

Claude API のメモリツール（Memory tool）の使い方 Claude API の構造化出力（Structured outputs）の使い方 Claude API のコンテキスト編集（Context editing）の使い方
← チュートリアル一覧へ戻る カテゴリで探す