Claude Media
Files APIとcode executionでCSVを集計する — 貼り付けとの25問比較
Anthropic解説

Files APIとcode executionでCSVを集計する — 貼り付けとの25問比較

CSVをプロンプトに貼ると毎リクエスト約9.1万入力トークン、Sonnet 5は25問中7問正解。Files APIでアップロードしcode executionで集計すると25問全問正解で、費用は約12分の1でした。

読了目安 約12分

CSVや表データを集計させるなら、プロンプトに貼らず、Files APIでアップロードしてcode executionに読ませるほうが安く、しかも正確です。Anthropicの測定では、1,862行のCSVに25問の集計を投げたところ、貼り付けのSonnet 5は7問正解で$5.01、アップロード+code executionは25問全問正解で$0.40でした。

差は費用で約12分の1、正解数で18問分です。

25問テストの結果 — 貼ると7問、渡すと25問

測定は、Anthropicが費用と知能のバランスを論じる公式ガイドの「Keep data files out of the prompt」節に載っています。問いは合計・条件付きの件数・グループ別集計・日付での絞り込みを含む25問の集計で、正解はpandasで計算してあります。

Opus 5でも同じ傾向でした。数字はSonnet 5のものを使っています。

数字

25問テストの結果(Sonnet 5)

  • 貼り付け

    7 / 25 問

    費用 $5.01

  • アップロード+code execution

    25 / 25 問

    費用 $0.40

  • 表1つあたりの入力

    約9.1万 tokens

    貼ると毎リクエスト。アップロードでは表がコンテナに置かれる

1,862行のCSV・pandas算出の正解で採点

条件を読み違えない

この測定には限定条件があります。数字を自分の案件に当てはめる前に押さえておくと、過大に期待せずに済みます。

  • データは公開の酒類販売CSVの1,862行分で、採点は完全一致です
  • thinkingは無効、出力上限は4,000トークン、プロンプトキャッシュなしで測っています。貼り付け側は既定設定では完走できないため、この設定にしたと注記があります
  • 各構成3回ずつ実行しています。貼り付けのSonnet 5は6問・7問・7問の正解で、グラフと本文の「7問」は平均6.67を最も近い整数に丸めた値です
  • 実施は2026年8月19日です

キャッシュを使った貼り付けの費用は、この比較に含まれていません。キャッシュで再送のコストを抑える方法はプロンプトキャッシュの仕組みにまとめています。ただし、この測定が示すのは正解数の差でもあるので、費用だけの話にはなりません。

なぜ貼ると高くつくのか

貼り付けの費用は、表のサイズ × リクエスト数で決まります。この表は約9.1万入力トークンで、質問を投げるたびにその全体が入力として課金されます。25問を別々のリクエストで尋ねれば、同じ表を25回送ることになります。

アップロードでは、表はFiles APIに保存され、code executionのコンテナにファイルとして置かれます。モデルはコードを書いて実行し、結果を読んで答えます。Files APIの操作(アップロード・一覧・削除など)自体は無料です。

正解数が違う理由は、このガイドには書かれていません。事実として言えるのは、この条件下で、モデルが表を読んで数えるより、pandasで計算した結果を読むほうが全問一致したことまでです。

手順 — Files APIにアップロードしてcode executionに渡す

必要な部品は3つです。Files APIでのアップロード、container_uploadブロックでのファイル参照、リクエストへのcode executionツールの追加。公式のcURL例に沿った形は次のとおりです。

FILE_ID=$(curl --fail-with-body -sS https://api.anthropic.com/v1/files \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -F "file=@sales.csv" | jq -r '.id')
 
curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 4096,
    "messages": [{"role": "user", "content": [
      {"type": "text", "text": "2025年の県別売上合計を出して"},
      {"type": "container_upload", "file_id": "'"$FILE_ID"'"}
    ]}],
    "tools": [{"type": "code_execution_20260120", "name": "code_execution"}]
  }'

公式の例ではcode_execution_20250825が使われていますが、現行の3つのツールバージョンはどれも対応モデルで受け付けられます。REPLの状態保持やプログラム的なツール呼び出しが要るときはcode_execution_20260120以降を選びます。この測定でファイル側が使ったのもcode_execution_20260120です。

手順

CSV集計をAPIで回す流れ

  1. 1

    アップロード

    Files APIにCSVを送り、file_idを受け取ります。1ファイル500MB、組織全体で1TBが上限です。

  2. 2

    参照とツール指定

    メッセージにcontainer_uploadブロックでfile_idを入れ、toolsにcode executionを足します。

  3. 3

    使用量の確認

    レスポンスのusageで入力トークンとserver_tool_useを見て、表が入力に入っていないことを確かめます。

CSVのほか、Excel(.xlsx、.xls)・JSON・XMLもこの経路で扱えます。.docxや.xlsxなどdocumentブロックが受けない形式を、テキストに変換して貼る方法もありますが、集計目的なら貼らずにアップロードする側が向いています。上限の詳細はFiles APIの容量上限で扱っています。

アップロードしても「貼ったのと同じ」になる落とし穴

Files APIにアップロードしたからといって、集計向きの経路になるとは限りません。ファイルをメッセージに載せるブロックの種類で、扱われ方が変わります。

ファイルブロック用途
PDF・プレーンテキスト(text/plain)ブロックdocument用途テキスト解析・文書処理
画像ブロックimage用途画像解析
データセットなどブロックcontainer_upload用途データ分析・可視化(code execution向け)

CSVは、text/plainを明示してアップロードすればdocumentブロックでも渡せます。ただしこちらは文書として読ませる経路で、集計に使うのはcontainer_uploadです。コード内でdocumentブロックを選んでいないか、container_uploadとcode executionツールがそろっているかを、最初に見直してください。レスポンスのusageで入力トークンが表のサイズ分に膨らんでいたら、貼り付けと同じ経路を通っています。

Claudeへの指示は「計算結果から答える」に寄せる

アップロードしても、モデルが表を推測で埋めてしまっては意味がありません。同じ質問を繰り返す運用なら、システムプロンプトで集計の作法を固定しておくと安定します。例えば次のような形にできます(公式のテストで検証された文言ではなく、設計の一案です)。

添付のCSVはcode executionでpandasを使って読み込むこと。
最初に行数と列名を出力し、数値は必ずコードの実行結果から答えること。
絞り込み条件(期間・除外した行)を回答に書くこと。

行数を最初に出させるのは、読み込みの取りこぼしに気づくためです。1,862行のCSVなら、最初の出力が1,862行になっているかを見るだけで、読み込みの失敗を見分けられます。

回答は正解に照らして採点する

運用に入れる前に、測定と同じ型で自前の評価を作れます。手元のCSVで答えが決まる質問を20〜30問用意し、pandasで正解を出して完全一致で採点します。貼り付け構成とアップロード構成を同じ質問群で比べれば、自分のデータで差が出るかを確かめられます。モデルやeffortを評価データで探索する手順は/claude-api hillclimbで扱っています。

費用の見方 — code executionは実行時間で課金される

アップロード側の費用はゼロではありません。code executionのルールは次のとおりです。

  • ウェブ検索またはウェブフェッチ(web_search_20260209、web_fetch_20260209以降)と一緒に使うと、code execution自体の追加課金はありません
  • 併用しない場合は実行時間で課金され、最低5分が単位になります
  • 組織ごとに月1,550時間の無料枠があり、超えた分はコンテナ1つにつき1時間あたり$0.05です
  • リクエストにファイルを含めると、ツールが呼ばれなくてもファイルがコンテナに事前配置されるため、実行時間が課金されます

無料枠に収まる範囲なら、CSV集計の費用の中心はトークンです。無料になる条件の詳細はコード実行ツールが無料になる条件にあります。

向かないケースと、使う前の確認事項

次の条件に当てはまるときは、貼り付けのほうが合うか、そもそもこの経路が使えません。

状況理由
ZDR(ゼロデータ保持)が必須理由Files APIもcode executionも、ZDRの対象外と記載されています
表が数十行で、質問も1回きり理由貼っても数千トークンで済み、手順を増やす利点が薄い
メモリ5GiB・ディスク5GiB・1 CPUを超える規模の処理理由コンテナの資源上限です
外部のAPIやパッケージが必要理由コンテナはインターネットに接続できず、プリインストール済みのライブラリしか使えません

ファイルの扱いで押さえる点

  • アップロードしたファイルはワークスペース全体からアクセスできます。ユーザーや会話単位では分離されません。顧客ごとにデータを分けるなら、ワークスペースを分けます。リスクはfile_idのセキュリティで整理しています
  • ファイルは変更・改名できません。CSVを更新するときは新しくアップロードして、古いほうを削除します
  • 自動で消したいときは、アップロード時にexpires_in_seconds(3,600秒〜7,776,000秒)を指定します
  • アップロードしたファイルはdownloadable: falseで、ダウンロードできません。ダウンロードできるのは、code executionが生成したファイルだけです。エラーの出方はFiles APIの400エラーにあります

まとめ

表を何度も参照して計算させる用途では、貼り付けを前提にしないほうが有利です。測定の再現条件(thinking無効・キャッシュなし・完全一致採点)を踏まえても、25問の集計で7問と25問という差は、設定の微調整で埋まる大きさではありません。

一方で、効果の大きさは表のサイズと質問数に比例します。まず自分のCSVと質問群で、貼り付けとアップロードを同じ採点で比べてください。API全体のコスト削減レバーの順番は/claude-api cost-optimizeが扱っています。claude.aiのチャットでCSVを分析する方法はClaude CSV分析の使い方にあります。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →