Claude Citationsのトークンコストの仕組み — cited_textが出力トークンに数えられない理由

Citationsを有効にすると入力トークンはどう変わるか

Citationsは、Claudeの回答に文書中の該当箇所を具体的な引用として添える機能です。ドキュメントブロックにcitations.enabled: trueを指定するだけで、応答の各文に出典となる位置情報が付きます。稼働中のすべてのモデルが対応し、Claude API本体だけでなくAmazon BedrockやGoogle Cloud、Microsoft Foundry経由でも同じ仕組みが使えます。

コストへの影響はまず入力側に出ます。Citationsを有効にすると入力トークンがわずかに増えます。理由は2つです。システムプロンプトへの追加と、ドキュメントの内部的なチャンク分割です。プレーンテキストとPDFは文単位で自動的にチャンク分割され、その処理のぶんだけ入力トークンの見積もりが変わります。増加量は公式ドキュメントでも「わずか」としか書かれておらず、具体的な割合は公開されていません。自分のドキュメントで正確な影響を知りたい場合は、リクエストを送る前にToken Counting APIで見積もる方法があります。

入力側の増加は小さく、出力側の削減が本題です。有効化そのものは、ドキュメントブロックに1行加えるだけで済みます。

見落としやすい点が1つあります。ドキュメントブロックのtitleとcontextは、Claudeに渡されるものの引用の対象にはなりません。つまり、この2つのフィールドに長いメタデータを詰め込んでも「引用元として無料になる」わけではなく、普通のテキストと同じく入力トークンとして課金されます。無料になるのは応答側のcited_textだけで、入力側に特別扱いのフィールドはありません。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "The grass is green. The sky is blue."
          },
          "title": "My Document",
          "citations": {"enabled": true}
        },
        {"type": "text", "text": "What color is the grass and sky?"}
      ]
    }]
  }'

cited_textが出力トークンに数えられない仕組み

Citationsを有効にした応答は、内部的には標準化されたフォーマットで引用位置を出力します。それがパースされ、cited_text(引用元テキスト本体)とdocument_location(文書内の位置情報)に分かれてAPIレスポンスに載ります。

ここが課金上の分岐点です。cited_textフィールドは応答を読みやすくするための便宜的な項目であり、出力トークンとしてカウントされません。プレーンテキスト文書からの引用例で確認すると、レスポンスの形は次のようになります。

{
  "type": "char_location",
  "cited_text": "The exact text being cited",
  "document_index": 0,
  "document_title": "Document Title",
  "start_char_index": 0,
  "end_char_index": 50
}

cited_textに入る文字列がどれだけ長くても、usage.output_tokensには反映されません。課金対象になるのは、Claudeが独自に生成した地の文と、位置情報そのものだけです。長い引用を何箇所も返す用途ほど、この非課金の効果は相対的に大きくなります。

レスポンス構造を見るとなぜ非課金なのかが分かる

cited_textがなぜ出力トークンに数えられないのかは、レスポンスの構造を見ると理解しやすくなります。Citationsを有効にした応答は、1つの長い文章ではなく、複数のtextブロックの連なりとして返ってきます。

{
  "content": [
    { "type": "text", "text": "According to the document, " },
    {
      "type": "text",
      "text": "the grass is green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green.",
          "document_index": 0,
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": " and " }
  ]
}

課金対象になっているのは、各textブロックのtextフィールド(Claudeが書いた本文)です。citations配列の中にぶら下がるcited_textは、その主張を裏付ける原文そのものの抜粋で、「この主張はどこから来たか」を示す添付メタデータという扱いです。本文とは別のフィールドにあるからこそ、Claudeが新たに生成したトークン列とは別枠で扱われ、出力トークンとしては計上されません。

ストリーミングで応答を受け取る場合も、この構造は保たれます。引用はcitations_deltaという専用のイベント種別で、現在のtextブロックに1件ずつ追加される形で届きます。地の文のtext_deltaとは別のイベントとして流れてくるため、クライアント側で両者を混同しない実装にしておくと、cited_textをトークン数として誤って積算する事故を避けられます。

会話を続けてもcited_textは入力トークンに戻ってこない

もう一段効くのが複数ターンの会話です。通常、Claudeの前の応答をそのまま次のターンの入力として送り返すと、その全文が入力トークンとして再課金されます。Citationsはここでも例外を作ります。

前のターンで返したcited_textを含む応答をそのまま次のリクエストに含めても、cited_text部分は再送信時の入力トークンとしてもカウントされません。長い文書から何度も引用しながら対話を続けるRAG(検索拡張生成)的な使い方で、この特性がそのまま累積コストの差になります。

プロンプトで逐語引用させる方法と何が違うか

Citationsを使わなくても、「該当箇所を直接引用してください」とプロンプトで指示すれば、似たような出力は得られます。公式ドキュメントは3つの観点でCitations機能のほうが優れているとしています。

厳密なコスト差の数値は公開されていません。ただし引用が長く・頻度が高い用途ほど、出力トークンを介さないcited_textの恩恵は大きくなります。逆に、文書が短く一問一答で終わる用途では、入力側のわずかな増加のほうが体感されやすく、コスト差は縮まります。

正確性の面でも設計が違います。プロンプトで「引用符内に原文をそのまま書き写して」と指示しても、Claudeが書き写す過程で1文字でもずれれば、それはもう「正確な引用」ではありません。APIが文書から直接抽出する方式なら、cited_textは必ず文書内の実在する範囲を指すため、ずれそのものが発生しません。書き写し精度を検証するための追加リクエストが要らなくなる分、間接的なコスト削減にもつながります。

Prompt Cachingと組み合わせたときの扱い

CitationsとPrompt Cachingは併用できます。ただし対象が非対称です。応答に含まれる引用ブロック自体はキャッシュできません。キャッシュできるのは、引用元となるドキュメントのコンテンツブロック側だけです。

同じ文書に対して繰り返し質問するワークフローでは、ドキュメントブロックにcache_controlを付けて文書側をキャッシュし、Citationsで応答側の出力トークンを削る、という二重の最適化が成立します。片方だけでは効果が半減するので、両方を意識して設計する価値があります。Prompt Cachingの仕組み自体は別記事で扱っているので、キャッシュの基礎から知りたい場合はそちらを先に確認してください。

Citationsはバッチ処理とも組み合わせられます。大量の文書に対して非同期でリクエストをまとめて投げる構成でも、cited_textが出力トークンとして計上されない仕組みは変わりません。1件あたりの削減幅は小さくても、件数が数千・数万に達するバッチでは無視できない差になります。

Agent SDKで動くアプリケーションのように、リクエストが自動的に何度も発生する構成では、見積もりだけでなく実際の消費量を継続的に追う仕組みも要ります。Agent SDKのコスト集計では、total_cost_usdやモデル別使用量の取得方法を扱っているので、Citationsを組み込んだアプリのコストを継続監視したい場合はあわせて参照できます。

Citationsのコスト効果はどんな用途で効くか

プレーンテキストとPDFはデフォルトで文単位に自動分割されますが、RAGのチャンクをそのまま引用単位にしたい場合は、チャンクごとに1つのプレーンテキスト文書として渡すか、追加分割なしのカスタムコンテンツ文書に載せるかを選べます。分割の粒度をどう設計するかによって、1回の応答に含まれる引用の数、ひいてはcited_textとして非課金になる範囲の広さも変わってきます。

RAGのように、長い文書から何度も裏取りしながら会話を続けるアプリケーションでは、cited_textが出力トークン・再送信時の入力トークンの両方から外れる効果が積み重なります。カスタマーサポートのFAQ検索や、社内ナレッジベースへの質問応答のように、同じ文書セットに対して1日に何百回もリクエストが飛ぶ構成ほど、この非課金の恩恵は総コストへ効いてきます。

一方で、1回限りの短い要約タスクや、文書自体が数百字程度しかない用途では、入力トークンのわずかな増加が相対的に目立ちます。コスト最適化だけを目的にCitationsを入れる判断は、引用の頻度と文書の長さを見てからのほうが確実です。引用の正確性そのものを目的にするなら、コストに関わらずCitationsを選ぶ理由があります。

用途別に整理すると、コスト面での効き方はおおむね次のようになります。

まとめ

Citationsは入力側でわずかにトークンを増やす一方、応答に含まれるcited_textは出力トークン・再送信時の入力トークンのどちらからも外れます。この非対称な課金ロジックが、プロンプトで逐語引用させる方式との実質的なコスト差を生みます。差が効くのは、文書が長く、引用の頻度が高く、会話やバッチの件数が多い用途です。逆に短い一問一答では、入力側のわずかな増加のほうが目立ちます。

titleやcontextフィールドは引用対象にならないだけで課金は免除されない、という点も見落としやすいところです。Prompt Cachingと組み合わせるときは、キャッシュできるのが文書側だけである点に注意します。厳密な増加率は公開されていないため、自分のワークロードでの実際の差はToken Counting APIで確認するのが確実です。スキャンPDFのようにそもそもCitationsの対象にならない文書もあるので、スキャンPDFがCitationsで引用できない理由もあわせて確認しておくと、文書側の準備で手戻りが減ります。