Claude APIをPythonで動かす——モデル選択・認証・最初のリクエスト完全解説【CCA Foundations対策】

Anthropic Academyの「Claude APIを使用した構築」コースをもとに解説しています。

Claude APIを使ってアプリを作りたい——そう思って調べ始めると、「モデルは何を選べばいい？」「APIキーはどこに書く？」「レスポンスはどう受け取る？」と疑問が次々と出てくる。

この記事では、その疑問を一つずつ潰しながら、PythonでClaude APIにリクエストを送り、レスポンスを受け取るところまでを動かせるようにする。

この記事でわかること：

• Opus・Sonnet・Haikuの違いと選び方の考え方
• APIキーを安全に扱う方法（やってはいけないことも含めて）
• messages.create() の必須パラメータの意味と使い方
• レスポンスからテキストを取り出す方法
• stop_reason の読み方と、エージェント設計との関係

---

まず全体像を把握する

細かい説明の前に、Claude APIを使うときの構造をざっくり頭に入れておく。

ユーザー（ブラウザ・モバイル等）
  ↓
自分のサーバー（Python / Node.js など）← ここにAPIキーを置く
  ↓ HTTPリクエスト
Anthropic API
  ↓
Claudeがテキストを生成して返す

重要な原則：クライアント（ブラウザやモバイルアプリ）から直接APIを叩かない。

理由はシンプルで、APIキーがフロントエンドのコードに含まれると誰でも取り出せてしまう。自分のサーバーを経由させることで、キーを安全に管理できる。これはセキュリティだけでなく、「誰がAPIを呼び出す権限を持つか」をアーキテクチャで制御するという設計原則でもある。

---

モデルを選ぶ

Claude APIには現在3つのモデルファミリーがある。

モデル	特徴	向いているタスク
Opus	最高の推論能力・最高コスト	複雑な分析・長期的な計画・深い推論が必要なタスク
Sonnet	能力・速度・コストのバランス	ほとんどの実用的なユースケース・コーディング
Haiku	最速・最安	リアルタイム応答・大量処理・シンプルな分類

選び方の基準

• とにかく賢さが必要 → Opus
• 速さ・コストを重視 → Haiku
• 迷ったら → Sonnet

「迷ったらOpus」と思いがちだが、Opusは処理が遅く、コストも高い。開発中はSonnetで動かして、「これでは推論が足りない」と感じたときだけOpusに切り替えるのが現実的な進め方。

実務での使い分けパターン

1つのモデルに固定するより、タスクに応じて使い分ける設計が効率的。よくある例：

• ユーザーの入力を「質問 / 要求 / 雑談」に分類 → Haiku
• 分類結果に応じて詳細な回答を生成 → Sonnet
• 複雑な推論が必要な処理だけ → Opus

コスト・速度・品質のバランスを意識してモデルを選ぶのが設計の基本。

---

テキスト生成の仕組みを知っておく

実装に入る前に、APIが内部で何をしているかを理解しておくとパラメータの意味が腑に落ちやすくなる。

リクエストを送ってからレスポンスが返るまで、内部では以下が行われている：

1. トークン化 — 入力テキストを「単語・記号など」の単位（トークン）に分割
2. 埋め込み — 各トークンを意味を持つ数値ベクトルに変換
3. 文脈化 — 前後のトークンを考慮して意味を精緻化
4. 生成 — 次のトークンの確率分布を計算し、選択 → 繰り返す

ここで押さえておきたいのは「確率的な生成」という点。 Claudeは決まった答えを返すのではなく、確率的に次のトークンを選んでいる。同じプロンプトでも出力が微妙に変わることがあるのはこのため。

---

環境構築

パッケージのインストール

pip install anthropic python-dotenv

anthropic がSDK本体、python-dotenv はAPIキーを .env ファイルから読み込むためのライブラリ。

APIキーの取得と保存

1. console.anthropic.com でAPIキーを発行
2. プロジェクトのルートに .env ファイルを作成

# .env
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxx

3. .gitignore に .env を追加

# .gitignore
.env

やってはいけないこと： Pythonコードの中に api_key="sk-ant-..." と直書きしてGitHubにプッシュするのはAPIキー漏洩の典型的なパターン。環境変数経由での管理を徹底する。

クライアントの初期化

import anthropic
from dotenv import load_dotenv

load_dotenv()  # .envファイルを読み込む

client = anthropic.Anthropic()  # ANTHROPIC_API_KEYを自動で参照

Anthropic() はデフォルトで環境変数 ANTHROPIC_API_KEY を探して読み込む。明示的に渡す場合は Anthropic(api_key="...") と書けるが、コードにキーを直書きするのは避ける。

---

最初のリクエストを送る

基本的なリクエスト

import anthropic
from dotenv import load_dotenv

load_dotenv()

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-4-6",  # 使用するモデル
    max_tokens=1024,             # 生成の上限トークン数
    messages=[
        {"role": "user", "content": "Pythonでフィボナッチ数列を生成するコードを書いて"}
    ]
)

print(message.content[0].text)

実行すると、Claudeが生成したコードが出力される：

フィボナッチ数列を生成するPythonコードをいくつかの方法で示します。

# 方法1: ループを使う方法
def fibonacci_loop(n):
    fib = [0, 1]
    for i in range(2, n):
        fib.append(fib[i-1] + fib[i-2])
    return fib[:n]
...

パラメータを理解する

model
使用するモデルのID。最新のモデルIDはAnthropicのドキュメントで確認する。モデルIDは更新されることがあるため、コードにハードコードする場合は定期的に確認が必要。

max_tokens
生成するトークン数の上限。ここが初心者に誤解されやすいポイント。

• max_tokens=1024 を設定しても、1024トークン必ず生成されるわけではない
• 短い質問に短い回答が返ってくれば、100トークンで止まることもある
• 「上限値」であって「目標値」ではない

設定しないとエラーになるため、必須パラメータ。長い回答が必要なときは大きめに設定し、実際のコストは usage で確認する。

messages
会話履歴をリストで渡す。各メッセージは role と content を持つ辞書。

messages がリストになっているのは、マルチターン会話（複数のやり取り）を想定した設計だから。Claudeはリクエスト間で状態を保持しない——前の会話を覚えているように見えるのは、毎回履歴を渡しているから。この設計はマルチエージェントシステムにも影響する（サブエージェントは親の会話履歴を自動では引き継がない）。

---

レスポンスの構造を知る

# レスポンス全体を確認
print(message)

Message(
  id='msg_01XFDUDYJgAACzvnptvVoYEL',
  content=[ContentBlock(text='フィボナッチ数列を...', type='text')],
  model='claude-sonnet-4-6',
  stop_reason='end_turn',
  usage=Usage(input_tokens=21, output_tokens=256)
)

テキストを取り出すには：

print(message.content[0].text)

なぜ content[0] なのか？
content がリストになっているのは、複数のコンテンツタイプ（テキスト・ツール呼び出しなど）が混在できる設計だから。シンプルなテキスト応答では [0] で取れるが、ツール使用を組み合わせると content に複数の要素が入ってくることがある。

---

stop_reason の読み方

stop_reason はレスポンスの「終了理由」を教えてくれる値で、取りうる値は3種類ある。

値	意味
"end_turn"	正常に完了
"max_tokens"	上限に達して途中で切れた
"tool_use"	ツール（関数）の呼び出しが要求された

今の段階で意識するのは最初の2つで十分。ただし "tool_use" の存在を知っておくと、後のエージェント設計の記事で「なぜ stop_reason を条件分岐の軸にするのか」がすぐ理解できる。

📋 試験ガイドより
公式試験ガイドのDomain 1（Agentic Architecture & Orchestration）では、stop_reason の値によるループ制御がエージェント設計の基本フローとして取り上げられている。

エージェントループの基本構造はこうなっている：

• stop_reason == "tool_use" → ツールを実行して結果を返す → ループ継続
• stop_reason == "end_turn" → 完了 → ループ終了
• stop_reason == "max_tokens" → 途中で切れている → 要確認

"tool_use" の流れを擬似コードで示すと：

messages = [{"role": "user", "content": "今日の東京の天気を教えて"}]

while True:
    response = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=[weather_tool],  # 使えるツールを定義
        messages=messages,
    )

    if response.stop_reason == "end_turn":
        # Claudeが自分で回答を完結させた → 終了
        print(response.content[0].text)
        break

    elif response.stop_reason == "tool_use":
        # Claudeがツール呼び出しを要求 → 実行して結果を返す
        tool_result = run_tool(response)           # ツールを実行
        messages.append({"role": "assistant", "content": response.content})
        messages.append({"role": "user", "content": tool_result})
        # ループを続けてClaudeに結果を渡す

    elif response.stop_reason == "max_tokens":
        print("[警告] 回答が途中で切れています")
        break

stop_reason == "tool_use" のときはツールを実行して結果を messages に追加し、再度リクエストを送る——この繰り返しがエージェントループの骨格。ツールの詳細な定義方法と実装は #8（Tool Use基礎）で扱う。

# 今の段階での最小実装（ツールなし）
if message.stop_reason == "max_tokens":
    print(f"[警告] 回答が途中で切れています（{message.usage.output_tokens} tokens使用）")
elif message.stop_reason == "end_turn":
    print("正常に完了しました")

トークン使用量を確認：

print(f"入力: {message.usage.input_tokens} tokens")
print(f"出力: {message.usage.output_tokens} tokens")

入力: 21 tokens
出力: 256 tokens

コスト管理や max_tokens の適切な設定値を判断するのに役立つ。

---

動作確認コード

ここまでをまとめた動作確認用の関数：

import anthropic
from dotenv import load_dotenv

load_dotenv()

client = anthropic.Anthropic()

def ask_claude(question: str, max_tokens: int = 1024) -> str:
    message = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=max_tokens,
        messages=[{"role": "user", "content": question}]
    )

    # 途中で切れていないか確認
    if message.stop_reason == "max_tokens":
        print(f"[警告] 回答が途中で切れています（{message.usage.output_tokens} tokens使用）")

    return message.content[0].text

# 動作確認
response = ask_claude("日本の首都はどこですか？")
print(response)

これが動けばAPIの基本設定は完了。

---

よくある誤解まとめ

誤解	実際
max_tokens=1024 なら常に1024トークン生成される	上限値なので、短い回答なら少ないトークンで止まる
ブラウザから直接APIを叩いても問題ない	APIキーが漏洩する。必ずサーバー経由で呼び出す
迷ったらOpusを使えばいい	コストと速度の無駄が出る。まずSonnetで試す
stop_reason は確認しなくていい	"max_tokens" なら回答が途中で切れているため要確認

---

まとめ

• Claude APIには Opus・Sonnet・Haiku の3モデル。迷ったらSonnetから始める
• APIキーは 環境変数 で管理し、コードへの直書き・フロントエンドへの露出は避ける
• messages.create() の必須パラメータは model / max_tokens / messages
• max_tokens は 目標値ではなく上限値。短い回答なら自動的に少なくなる
• テキストは message.content[0].text で取り出す
• stop_reason は3値（"end_turn" / "max_tokens" / "tool_use"）を持つ。現時点では最初の2つを押さえておく

次回はマルチターン会話・システムプロンプト・Temperatureを扱う。APIを使って「キャラクターと設定を持つチャットボット」を作れるようになる。

---