Claude API入門とプロンプトキャッシュ

Claude APIを使うと、数行のコードでAI会話機能をアプリケーションに組み込めます。プロンプトキャッシュを活用することで、繰り返しリクエストのコストを最大90%削減できます。

Claude APIの基礎

APIキーの取得と設定

Claude APIとは、Anthropicが提供するHTTPベースのインターフェースで、プログラムからClaudeモデルを呼び出すための仕組みです。APIキーによる認証が必要です。

APIキーは Anthropic Console から取得します。取得後は環境変数として設定することを推奨します。コード中にAPIキーをハードコードするとセキュリティリスクがあるため、必ず環境変数を使用してください。

# 環境変数にAPIキーを設定（~/.zshrc や ~/.bashrc に追加）
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

Python SDKのインストール

Anthropic Python SDKは pip でインストールできます。

pip install anthropic

Python 3.8以上が必要です。インストール後、以下のコードでSDKが正しく動作するか確認できます。

基本的なメッセージ送信（Python）

# Python 3.8以上が必要
import anthropic

# クライアントを初期化（ANTHROPIC_API_KEY 環境変数を自動参照）
client = anthropic.Anthropic()

# メッセージを送信
message = client.messages.create(
    model="claude-sonnet-4-6",        # 使用するモデルID
    max_tokens=1024,                   # 出力の最大トークン数
    messages=[
        {"role": "user", "content": "Pythonでフィボナッチ数列を生成する関数を書いてください。"}
    ]
)

# レスポンスを出力
print(message.content[0].text)
# 出力例: def fibonacci(n): ...（コードが返される）

TypeScript / Node.jsの例

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
// ANTHROPIC_API_KEY 環境変数を自動参照

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

console.log(message.content[0].text);

---

APIの主要パラメータ

メッセージAPIの構造

Claude APIは Messages API を中心に構成されています。リクエストには以下の主要パラメータを指定します。

パラメータ	型	必須	説明
model	string	必須	使用するモデルID（例: claude-sonnet-4-6）
max_tokens	integer	必須	出力の最大トークン数（最大8192）
messages	array	必須	会話履歴（role と content のペア）
system	string	任意	システムプロンプト（モデルの役割・制約を定義）
temperature	float	任意	出力のランダム性（0.0〜1.0、デフォルト: 1.0）
stream	boolean	任意	ストリーミングレスポンスを有効化

# システムプロンプトとtemperatureを指定した例
message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="あなたはPythonの専門家です。コードの説明は日本語で行い、コメントも日本語で書いてください。",
    temperature=0.3,       # 低い値ほど一貫した出力（コード生成に推奨）
    messages=[
        {"role": "user", "content": "リスト内包表記の使い方を教えてください。"},
        {"role": "assistant", "content": "リスト内包表記は、既存のリストから新しいリストを簡潔に作成する構文です。"},
        {"role": "user", "content": "もう少し具体的な例を見せてください。"}
    ]
)

ストリーミングレスポンス

ストリーミングレスポンスとは、生成されたテキストをリアルタイムに順次受信する機能です。チャットUIなど、応答の一部をすぐに表示したい場合に使用します。

# ストリーミングレスポンスの例
with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "長い物語を書いてください。"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)  # テキストをリアルタイム出力

---

レート制限とコスト構造

レート制限

Claude APIには Tokens Per Minute（TPM） と Requests Per Minute（RPM） の2種類のレート制限があります。

制限の種類	説明
TPM（Tokens Per Minute）	1分間に処理できる最大トークン数
RPM（Requests Per Minute）	1分間に送信できる最大リクエスト数

レート制限の上限はAPIプランによって異なります。制限に達した場合、APIは 429 Too Many Requests エラーを返します。指数バックオフ（exponential backoff）による再試行実装を推奨します。

コスト構造

Claude APIのコストは 入力トークン（input tokens） と 出力トークン（output tokens） で課金されます。

• 入力トークン: システムプロンプト・ユーザーメッセージ・会話履歴の合計
• 出力トークン: Claudeが生成したテキストのトークン数

一般的に出力トークンの単価は入力トークンより高くなります。コスト削減には、不必要な出力を避けるために max_tokens を適切に設定し、システムプロンプトを簡潔にまとめることが効果的です。

# トークン使用量の確認
print(f"入力トークン: {message.usage.input_tokens}")
print(f"出力トークン: {message.usage.output_tokens}")
print(f"合計トークン: {message.usage.input_tokens + message.usage.output_tokens}")

---

プロンプトキャッシュ（Prompt Caching）

プロンプトキャッシュとは

プロンプトキャッシュ（Prompt Caching）とは、同一のプロンプトプレフィックスを複数回送信する場合に、そのトークン処理コストを大幅に削減する機能です。

通常、APIにリクエストを送るたびにシステムプロンプト全体のトークンが課金されます。プロンプトキャッシュを有効にすると、同一のプレフィックス部分はキャッシュから参照されるため、処理コストが最大90%削減されます。

graph TD
  subgraph キャッシュなし
    R1[リクエスト1: システムプロンプト全体を処理] --> C1[100%コスト]
    R2[リクエスト2: システムプロンプト全体を処理] --> C2[100%コスト]
    R3[リクエスト3: システムプロンプト全体を処理] --> C3[100%コスト]
  end

  subgraph キャッシュあり
    R4[リクエスト1: キャッシュ書き込み] --> C4[100%コスト]
    R5[リクエスト2: キャッシュ読み取り] --> C5[10%コスト]
    R6[リクエスト3: キャッシュ読み取り] --> C6[10%コスト]
  end

キャッシュの設定方法（cache_control: ephemeral）

cache_control パラメータに {"type": "ephemeral"} を指定することでキャッシュを有効化します。

import anthropic

client = anthropic.Anthropic()

# 長いシステムプロンプトをキャッシュする例
# （実際の使用では、ここに数千トークンのシステムプロンプトが入る）
LONG_SYSTEM_PROMPT = """
あなたはPythonとデータサイエンスの専門家です。
以下のガイドラインに従って回答してください：
1. コードは常に型アノテーションを含める
2. docstringはGoogle形式で記述する
3. エラーハンドリングを必ず含める
... （数千トークンの詳細なガイドライン）
"""

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": LONG_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"}  # このセクションをキャッシュ
        }
    ],
    messages=[
        {"role": "user", "content": "pandasでCSVを読み込む関数を書いてください。"}
    ]
)

# キャッシュの使用状況を確認
print(f"キャッシュ書き込みトークン: {message.usage.cache_creation_input_tokens}")
print(f"キャッシュ読み取りトークン: {message.usage.cache_read_input_tokens}")
print(f"通常入力トークン: {message.usage.input_tokens}")

キャッシュのTTLと注意事項

項目	内容
TTL（生存時間）	最後のアクセスから5分間
最小キャッシュサイズ	1024トークン以上のブロックにのみ適用可能
課金	キャッシュ書き込みは通常の入力トークンよりわずかに高い（1.25倍）
キャッシュ読み取りのコスト削減	最大90%削減（通常の10%のコスト）

キャッシュが有効なユースケース

プロンプトキャッシュは以下のユースケースで特に効果的です。

• 長いシステムプロンプト: 数千トークンのガイドライン・役割定義を毎回送信する場合
• ドキュメントの繰り返し参照: 同一のコードベースや技術文書に対して複数の質問をする場合
• RAG（検索拡張生成）: 検索で取得した同一のドキュメントを複数の質問に使用する場合
• マルチターン会話: 長い会話履歴を持つチャットボット

# RAGでのキャッシュ活用例
# 検索で取得したドキュメントをキャッシュ対象に設定
retrieved_document = "... （検索で取得した長いドキュメント）..."

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": retrieved_document,
                    "cache_control": {"type": "ephemeral"}  # ドキュメントをキャッシュ
                },
                {
                    "type": "text",
                    "text": "このドキュメントの主なポイントは何ですか？"
                }
            ]
        }
    ]
)

---

Batches API（大量処理）

Batches APIとは

Batches API（バッチAPI）とは、大量のリクエストを非同期で処理する機能です。通常のAPIと比較して 50%のコスト削減 が可能です。リアルタイムの応答が不要なタスクに適しています。

graph LR
  SUBMIT[バッチリクエスト送信] --> QUEUE[処理キュー]
  QUEUE --> PROCESS[非同期処理]
  PROCESS --> RESULT[結果取得（最大24時間）]

Batches APIの基本的な使い方

import anthropic

client = anthropic.Anthropic()

# バッチリクエストの作成
batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "request-1",  # リクエストを識別するID
            "params": {
                "model": "claude-haiku-4-5",   # バッチ処理にはHaikuが推奨
                "max_tokens": 100,
                "messages": [
                    {"role": "user", "content": "「東京」を英語に翻訳してください。"}
                ]
            }
        },
        {
            "custom_id": "request-2",
            "params": {
                "model": "claude-haiku-4-5",
                "max_tokens": 100,
                "messages": [
                    {"role": "user", "content": "「大阪」を英語に翻訳してください。"}
                ]
            }
        }
        # ... 最大10,000リクエストまで一括送信可能
    ]
)

print(f"バッチID: {batch.id}")
print(f"ステータス: {batch.processing_status}")

# バッチの完了を確認（ポーリング）
import time

while True:
    batch_status = client.messages.batches.retrieve(batch.id)
    if batch_status.processing_status == "ended":
        break
    time.sleep(60)  # 1分待機してから再確認

# 結果の取得
for result in client.messages.batches.results(batch.id):
    print(f"ID: {result.custom_id}, 結果: {result.result.message.content[0].text}")

Batches APIが適したユースケース

ユースケース	説明
データ分析・ラベリング	大量のテキストデータの分類・タグ付け
評価・ベンチマーク	モデルの応答品質を大量のテストケースで評価
一括翻訳	大量の文書を一括で翻訳
オフラインレポート生成	定期的な分析レポートの生成

---

まとめとベストプラクティス

実装時の推奨事項

1. APIキーは必ず環境変数で管理 — コード中にAPIキーをハードコードしない
2. モデルは用途に応じて選択 — デフォルトはSonnet、コスト優先はHaiku、高精度はOpus（モデル選定ガイド参照）
3. max_tokensは適切に設定 — 不要に大きな値を設定するとコストが増加する
4. プロンプトキャッシュを活用 — 長いシステムプロンプトや繰り返し参照するドキュメントには必ず設定する
5. リアルタイム不要な処理はBatches APIを使用 — 50%のコスト削減が可能
6. エラーハンドリングを実装 — レート制限エラー（429）には指数バックオフで再試行する

# ベストプラクティスを含む実装例
import anthropic
import time

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY 環境変数を使用

def create_message_with_retry(messages, system=None, max_retries=3):
    """指数バックオフによるリトライ付きメッセージ送信"""
    for attempt in range(max_retries):
        try:
            kwargs = {
                "model": "claude-sonnet-4-6",
                "max_tokens": 1024,
                "messages": messages
            }
            if system:
                kwargs["system"] = system

            return client.messages.create(**kwargs)

        except anthropic.RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait_time = (2 ** attempt) * 1  # 1秒、2秒、4秒と増加
            print(f"レート制限に達しました。{wait_time}秒待機します...")
            time.sleep(wait_time)

        except anthropic.APIError as e:
            print(f"APIエラー: {e}")
            raise

---

よくある質問

Q: max_tokens はどのくらいの値を設定すればよいですか？

タスクに必要な出力量の1.5〜2倍を目安に設定します。コード生成なら500〜2048、短い要約なら100〜500が一般的です。過大な値を設定すると不必要なトークンが生成されコストが増加する場合があります。

Q: プロンプトキャッシュはすべてのモデルで使えますか？

Claude 3以降のモデル（Opus・Sonnet・Haiku）でサポートされています。利用可能なモデルの最新情報は Anthropic公式ドキュメント で確認してください。

Q: ストリーミングとBatches APIはどう使い分けますか？

ストリーミングはユーザーに即時フィードバックが必要なチャットUIなどに使用します。Batches APIはリアルタイム応答が不要で大量処理が求められるデータ分析・評価パイプラインに使用します。

Q: レート制限エラー（429）が頻繁に発生する場合はどうすればよいですか？

まず指数バックオフによる再試行を実装することを推奨します。それでも不十分な場合は、Anthropic Consoleでより上位のプランへのアップグレードを検討してください。

---

関連リンク

• Anthropic 公式ドキュメント - Messages API
• Anthropic 公式ドキュメント - Prompt Caching
• Anthropic 公式ドキュメント - Message Batches API
• Claudeモデル比較・選定ガイド

---

このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]

参考文献

1. Anthropic, Claude Code documentation
2. Anthropic, Claude API documentation