Claude API Python入門｜Anthropic SDKコピペレシピ集

Claude APIをPythonから使うには、公式SDK anthropic を入れて client.messages.create() を呼ぶのが基本です。 model・max_tokens・messages の3つを渡せば最小の呼び出しになり、ストリーミングやツール呼び出し（tool use）、構造化出力などもすべて同じ messages の仕組みの上に乗っています。

この記事では、2026年10月1日時点の最新版 anthropic 1.11.0（PyPI で確認、2026-09-30公開） を使い、よく使う機能をコピペ用のレシピにまとめました。モデル名と料金は公式ドキュメント（platform.claude.com）で確認した値だけを載せています。また、SDKの動作（送られるリクエストの中身、例外の型、自動リトライ）は、自分のPCに立てたモックサーバーに接続して実際に確かめた結果を載せています。APIキーを使った本物の呼び出しはしていないため、モデルの回答文は載せていません（本文の「応答」はすべてモックの固定文です）。

Claude API（Python SDK）の早見表

モデルと料金の選び方（公式で確認した値）

2026年10月1日時点の現行モデルは次の4つです。 値は公式の Models overview と Pricing ページで確認しました（価格は100万トークンあたりの米ドル、MTok＝100万トークン）。

料金を下げる仕組みも公式で確認しました。

迷ったときの判断表です。

モデル名は変わっていくので、コードでは定数や設定ファイルにまとめておくと、切り替えが1か所で済みます。SDKの anthropic.types.Model にも、1.11.0 時点で使えるモデル名の一覧が型として入っています。

準備：インストールとAPIキー

SDKは PyPI の anthropic です。 1.11.0 は Python 3.10 以上が対象です。

pip install -U anthropic        # 2026-10-01 時点の最新は 1.11.0
python -c "import anthropic; print(anthropic.__version__)"

1.11.0

APIキーは Claude Console で発行し、環境変数 ANTHROPIC_API_KEY に入れます。 anthropic.Anthropic() は引数なしでこの環境変数を読みます。コードに直接書くと、Gitにコミットしてしまう原因になるので、.env ファイル＋.gitignore で管理すると安心です（詳しくは別記事「.envの使い方と注意点」）。

export ANTHROPIC_API_KEY="sk-ant-..."   # macOS / Linux

キーが設定されていない状態で呼び出すと、1.11.0 では次の例外になりました（実行して確認）。

TypeError | "Could not resolve authentication method. Expected one of api_key, auth_token, or credentials to be set. Or for one of the `X-Api-Key` or `Authorization` headers to be explicitly omitted"

この記事の検証方法（モックサーバー）

APIキーなしでSDKの動きを確かめるため、Messages API の形をまねたモックサーバーを http://127.0.0.1:7811 に立てました。 SDKは base_url を差し替えるだけでモックに接続できます。

client = anthropic.Anthropic(api_key="sk-ant-dummy", base_url="http://127.0.0.1:7811")

モックはあらかじめ決めた固定の応答を返すだけです。以下の「実行結果」に出てくる回答文はモックの固定文で、Claude の出力ではありません。 実際に使うときは base_url を外し、環境変数のAPIキーで呼び出してください。

レシピ1：最小のメッセージ送信と system

import anthropic

client = anthropic.Anthropic()   # ANTHROPIC_API_KEY を自動で読む

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,                     # 出力の上限（必須）
    system="あなたは備品管理の担当者です。簡潔に答えてください。",
    messages=[{"role": "user", "content": "付箋の在庫を確認する手順は？"}],
)
print(msg.content[0].text)
print(msg.stop_reason, msg.usage.input_tokens, msg.usage.output_tokens)

モックでの実行結果（戻り値の型と属性の確認）：

Message end_turn text '（モックサーバーの固定応答です）'
Usage(cache_creation=None, cache_creation_input_tokens=0, cache_read_input_tokens=0, inference_geo=None, input_tokens=12, output_tokens=8, output_tokens_details=None, server_tool_use=None, service_tier=None)

戻り値は Message オブジェクトで、本文は content（ブロックのリスト）に入ります。 テキスト以外のブロック（tool_use など）が入ることもあるので、確実に取り出すなら次のように書きます。

text = "".join(b.text for b in msg.content if b.type == "text")

stop_reason の主な値は end_turn（自然に終了）、max_tokens（上限に到達）、stop_sequence、tool_use（ツール呼び出し待ち）です。max_tokens で止まったときは回答が途中で切れているので、上限を上げるか続きを依頼します。

レシピ2：マルチターン（会話を続ける）

APIは前の会話を覚えていません。 続けるときは、これまでのやり取りを毎回 messages に入れて送ります。

history = []

def chat(user_text: str) -> str:
    history.append({"role": "user", "content": user_text})
    msg = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024, messages=history)
    reply = "".join(b.text for b in msg.content if b.type == "text")
    history.append({"role": "assistant", "content": reply})
    return reply

chat("備品の棚卸しを月1回にしたいです。")
chat("さっきの頻度で、1年に何回になりますか？")   # 前の発言を踏まえて答えられる

会話が長くなると入力トークンが毎回増えます。 長い会話ではレシピ7のプロンプトキャッシュを組み合わせると、2回目以降の入力料金を抑えられます。

レシピ3：ストリーミング（少しずつ表示）

client.messages.stream() を with 文で使うと、生成された文字を順に受け取れます。 チャット画面のように待ち時間を短く感じさせたいときに使います。

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "こんにちは"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final = stream.get_final_message()     # 最後にまとめた Message も取れる
print()
print(final.stop_reason, final.usage.output_tokens)

モックが3つに分けて返したテキストを、SDKが順に渡してくることを確認しました。

chunk: '（モック'
chunk: 'の固定'
chunk: '応答です）'
final: （モックの固定応答です） end_turn 8

max_tokens を大きくする長い出力では、ストリーミングを使うのが基本です。 SDK 1.11.0 は、max_tokens から処理が10分を超えそうだと見積もった非ストリーミングのリクエストを、送信前に ValueError にします。モックで試すと、max_tokens=21000 は通り、22000 と 64000 では次のエラーになりました。

ValueError: Streaming is required for operations that may take longer than 10 minutes. See https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#long-requests for more details

レシピ4：tool use（関数を呼ばせる）

tool use は「Claude が関数を呼びたいと返し、こちらで実行して結果を返す」往復の仕組みです。 関数を実行するのは自分のコードです。

sequenceDiagram
    participant App as 自分のコード
    participant API as Claude API
    App->>API: messages + tools
    API-->>App: stop_reason=tool_use（name, input）
    App->>App: get_stock(item="付箋") を実行
    App->>API: tool_result を追加して再送
    API-->>App: stop_reason=end_turn（最終回答）

import json
import anthropic

client = anthropic.Anthropic()
STOCK = {"付箋": 8, "ホッチキス": 1}

def get_stock(item: str) -> dict:
    return {"item": item, "stock": STOCK.get(item, 0)}

tools = [{
    "name": "get_stock",
    "description": "備品名を受け取り、現在の在庫数を返す",
    "input_schema": {
        "type": "object",
        "properties": {"item": {"type": "string", "description": "備品名"}},
        "required": ["item"],
    },
}]
messages = [{"role": "user", "content": "付箋の在庫は？"}]

while True:
    resp = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
                                  tools=tools, messages=messages)
    if resp.stop_reason != "tool_use":
        break
    messages.append({"role": "assistant", "content": resp.content})
    results = []
    for block in resp.content:
        if block.type == "tool_use":
            out = get_stock(**block.input)
            print("ツール実行:", block.name, block.input, "→", out)
            results.append({"type": "tool_result", "tool_use_id": block.id,
                            "content": json.dumps(out, ensure_ascii=False)})
    messages.append({"role": "user", "content": results})

print("".join(b.text for b in resp.content if b.type == "text"))

モックで往復させた結果と、2回目に送られた messages：

ツール実行: get_stock {'item': '付箋'} → {'item': '付箋', 'stock': 8}
最終: （モックサーバーの固定応答です） | 往復: 3

[{"role": "user", "content": "付箋の在庫は？"},
 {"role": "assistant", "content": [{"id": "toolu_mock_1", "input": {"item": "付箋"}, "name": "get_stock", "type": "tool_use"}]},
 {"role": "user", "content": [{"type": "tool_result", "tool_use_id": "toolu_mock_1", "content": "{\"item\": \"付箋\", \"stock\": 8}"}]}]

ポイントは3つです。 ①assistant の応答（resp.content）をそのまま履歴に入れる、②tool_result の tool_use_id を block.id と一致させる、③1回の応答に tool_use が複数入ることがあるので、すべて実行して結果をまとめて返す。ツールを外部のサーバーとして切り出す方法（MCP）は別記事「MCPサーバーの作り方」で扱っています。

レシピ5：画像を入力する

画像は content を「ブロックのリスト」にして、image ブロックと text ブロックを並べます。

import base64
from pathlib import Path

data = base64.standard_b64encode(Path("shelf.png").read_bytes()).decode()

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": [
            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": data}},
            {"type": "text", "text": "この画像に写っている備品を列挙してください。"},
        ],
    }],
)

モックに届いたリクエスト（data は先頭のみ表示）：

{"max_tokens": 1024, "messages": [{"role": "user", "content": [{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo=..."}}, {"type": "text", "text": "この画像に写っている備品を列挙してください。"}]}], "model": "claude-sonnet-5-5"}

画像を先、質問を後に置くと指示がわかりやすくなります。media_type はファイルの形式（image/jpeg・image/png・image/gif・image/webp）に合わせます。

レシピ6：構造化出力（Pydanticで受け取る）

client.messages.parse() に Pydantic のクラスを渡すと、スキーマに沿ったJSONで回答させ、そのクラスのインスタンスとして受け取れます。

from pydantic import BaseModel

class OrderRequest(BaseModel):
    item: str
    qty: int
    urgent: bool

r = client.messages.parse(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "付箋を3つ注文したい。急ぎではない。"}],
    output_format=OrderRequest,
)
print(type(r.parsed_output).__name__, r.parsed_output)

モックで確認した、SDKが実際に送ったリクエストと戻り値です。SDKが Pydantic のクラスを JSON Schema に変換し、output_config.format に入れて送っていることがわかります。

{"max_tokens": 1024, "messages": [{"role": "user", "content": "付箋を3つ注文したい。急ぎではない。"}], "model": "claude-sonnet-5-5", "output_config": {"format": {"schema": {"type": "object", "title": "OrderRequest", "properties": {"item": {"type": "string", "title": "Item"}, "qty": {"type": "integer", "title": "Qty"}, "urgent": {"type": "boolean", "title": "Urgent"}}, "additionalProperties": false, "required": ["item", "qty", "urgent"]}, "type": "json_schema"}}}

OrderRequest item='付箋' qty=3 urgent=False

Pydantic を使わない場合は client.messages.create(..., output_config={"format": {"type": "json_schema", "schema": {...}}}) と書き、テキストを json.loads() します。tool の入力をスキーマどおりにしたいときは、ツール定義に "strict": True を付けます。構造化出力の方式比較や検証の詳細は別記事「LLMの構造化出力とJSON」にまとめています。

レシピ7：プロンプトキャッシュ

同じ長い前置き（マニュアル、ツール定義、長い会話履歴）を何度も送るときは、キャッシュで2回目以降の入力料金と待ち時間を減らせます。 一番簡単なのは、リクエストの最上位に cache_control を付ける自動キャッシュです。

msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},          # 自動で最後のブロックまでをキャッシュ
    system=long_manual_text,
    messages=[{"role": "user", "content": "返却期限を過ぎた備品の扱いは？"}],
)
u = msg.usage
print(u.cache_creation_input_tokens, u.cache_read_input_tokens, u.input_tokens)

部分ごとに区切りたいときは、ブロックに付けます（1リクエストで最大4か所）。

system=[
    {"type": "text", "text": "あなたは備品管理の担当者です。"},
    {"type": "text", "text": long_manual_text,
     "cache_control": {"type": "ephemeral", "ttl": "1h"}},   # 1時間保持
]

レシピ8：Message Batches（大量処理を半額で）

急がない大量のリクエストは、Batches API にまとめて送ると入力・出力とも50%引きになります。 結果は後から取りに行きます。

batch = client.messages.batches.create(requests=[
    {"custom_id": f"task-{i}",
     "params": {"model": "claude-haiku-4-5", "max_tokens": 256,
                "messages": [{"role": "user", "content": f"次の文を20字で要約: {text}"}]}}
    for i, text in enumerate(texts)
])
print(batch.id, batch.processing_status, batch.request_counts)

モックで確認した戻り値の形：

msgbatch_mock_001 in_progress MessageBatchRequestCounts(canceled=0, errored=0, expired=0, processing=1, succeeded=0)

処理が終わったら（processing_status == "ended"）、結果を取り出します。結果の順番は送った順とは限らないため、custom_id で対応づけます。

import time
while client.messages.batches.retrieve(batch.id).processing_status != "ended":
    time.sleep(60)

for entry in client.messages.batches.results(batch.id):
    if entry.result.type == "succeeded":
        print(entry.custom_id, entry.result.message.content[0].text)
    else:
        print(entry.custom_id, entry.result.type)   # errored / canceled / expired

この結果取得部分は、モックで終了状態まで再現していないため未実行です（公式のSDKの使い方に沿って記載）。

レシピ9：送る前にトークン数を数える

count_tokens() は、送信前に入力トークン数を調べるためのメソッドです。 長い資料を渡す前に、コンテキストや予算に収まるかを確認できます。引数は create() とほぼ同じ（max_tokens は不要）です。

c = client.messages.count_tokens(
    model="claude-sonnet-5-5",
    system="あなたは備品管理の担当者です。",
    messages=[{"role": "user", "content": "こんにちは"}],
)
print(c.input_tokens)

戻り値の型はモックで MessageTokensCount(input_tokens=42) となることを確認しました（42 はモックが返した値です）。トークン数はモデルによって変わるので、実際に使うモデル名で数えます。

レシピ10：リトライ・タイムアウト・エラー処理

SDKは既定で「2回まで自動リトライ」「タイムアウト600秒（接続5秒）」です（1.11.0 のソースの DEFAULT_MAX_RETRIES = 2、DEFAULT_TIMEOUT で確認）。クライアント全体、または1回の呼び出しごとに変えられます。

client = anthropic.Anthropic(max_retries=4, timeout=60.0)          # 全体
client.with_options(max_retries=0, timeout=10.0).messages.create(...)  # この呼び出しだけ

自動リトライの確認

2回続けて 429 を返し、3回目で成功するモックで試しました。呼び出し側は1回 create() を呼んだだけで、SDKが自動で再送しています。 サーバー側のログに、SDKが付けるリトライ回数のヘッダー（x-stainless-retry-count）が 0→1→2 と記録されました。

429→成功: （モックサーバーの固定応答です） 2.0s

/v1/messages mock-429 retry= 0 2023-06-01
/v1/messages mock-429 retry= 1 2023-06-01
/v1/messages mock-429 retry= 2 2023-06-01

（2023-06-01 はSDKが自動で付ける anthropic-version ヘッダーの値です。）SDKのソースでは、408・409・429・500以上のステータスと接続エラーが自動リトライの対象になっています。

エラー型の一覧

各ステータスコードを返すモックで、SDKが投げる例外の型を確認しました（max_retries=0）。

try:
    client.with_options(max_retries=0).messages.create(...)
except anthropic.APIStatusError as e:
    print(type(e).__name__, e.status_code, e.request_id)
    print(e.body)

mock-401: AuthenticationError status=401 request_id=req_mock_401
   body: {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'mock: invalid x-api-key'}}
mock-400: BadRequestError status=400 request_id=req_mock_400
   body: {'type': 'error', 'error': {'type': 'invalid_request_error', 'message': 'mock: max_tokens: Field required'}}
mock-529: OverloadedError status=529 request_id=req_mock_529
   body: {'type': 'error', 'error': {'type': 'overloaded_error', 'message': 'mock: overloaded'}}
APITimeoutError: Request timed out or interrupted. This could be due to a network timeout, dropped connection, or request cancellation. See https://docs.anthropic.com/en/api/errors#long-requests for more details. | isinstance APIConnectionError: True
APIConnectionError: Connection error.

例外は AnthropicError → APIError → APIStatusError → 各エラー、という親子関係です（RateLimitError.__mro__ で確認）。まとめて受けるなら anthropic.APIStatusError と anthropic.APIConnectionError の2つで足ります。問い合わせのときは e.request_id を記録しておくと調査がスムーズです。

import logging
log = logging.getLogger(__name__)

def ask(prompt: str) -> str | None:
    try:
        msg = client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
                                     messages=[{"role": "user", "content": prompt}])
    except anthropic.RateLimitError as e:
        log.warning("レート制限（自動リトライ後）: %s", e.request_id)
        return None
    except anthropic.APIStatusError as e:
        log.error("APIエラー %s %s: %s", e.status_code, e.request_id, e.message)
        return None
    except anthropic.APIConnectionError as e:
        log.error("接続できません: %s", e)
        return None
    return "".join(b.text for b in msg.content if b.type == "text")

レシピ11：非同期（AsyncAnthropic）と考える量の調整

複数のリクエストを同時に送るときは AsyncAnthropic を使います。 メソッド名は同じで、await を付けるだけです。

import asyncio
import anthropic

async def main():
    client = anthropic.AsyncAnthropic()
    questions = ["棚卸しの手順は？", "発注の締め日は？", "返却の流れは？"]
    results = await asyncio.gather(*[
        client.messages.create(model="claude-haiku-4-5", max_tokens=300,
                               messages=[{"role": "user", "content": q}])
        for q in questions
    ])
    for q, r in zip(questions, results):
        print(q, "→", r.content[0].text)

asyncio.run(main())

モックで3件が並行して返ることを確認しました。同時に送る数が多いとレート制限にかかりやすいので、asyncio.Semaphore で同時実行数を絞ると安定します。

output_config={"effort": ...} で、モデルが考える量を調整できます。 SDK 1.11.0 の型定義で指定できる値は low・medium・high・xhigh・max です。公式のモデル一覧では、Opus 5.5 の既定は medium、Fable 5.1 の既定は high と記載されています。簡単な処理では低く、難しい処理では高くすると、速度・料金と品質のバランスを取れます。

client.messages.create(model="claude-opus-5-5", max_tokens=1024,
                       output_config={"effort": "low"},
                       messages=[{"role": "user", "content": "この文の誤字を直して: ..."}])

よくある質問

Q. Claude API は無料で使えますか？ A. 使った入力・出力のトークン数に応じた従量課金です。Claude Console でクレジットを購入して使います。料金はモデルごとに異なり、プロンプトキャッシュや Batches を使うと下げられます。最新の料金は公式の Pricing ページで確認してください。

Q. Claude.ai（チャット）の有料プランで API も使えますか？ A. Claude.ai のプランと API の利用料金は別です。API は Claude Console でAPIキーを発行し、API用の支払い設定をして使います。

Q. requests で直接 HTTP を呼ぶのと SDK はどちらがよいですか？ A. SDKがおすすめです。認証ヘッダー・anthropic-version・自動リトライ・タイムアウト・ストリーミングの解析・型つきの戻り値をまとめて扱ってくれます。この記事でも、429 の自動リトライやエラーの型分けをSDKが行うことを確認しました。

Q. 社内の資料をもとに答えさせたいときはどうしますか？ A. 資料が短ければ system や messages に入れ、プロンプトキャッシュで料金を抑えます。資料が多い場合は、検索して関係する部分だけを渡す RAG という方法があります（別記事「RAGの作り方」で扱っています）。

まとめ

• pip install anthropic（最新 1.11.0）→ client.messages.create(model, max_tokens, messages) が基本の形
• APIキーは環境変数 ANTHROPIC_API_KEY に置き、コードに書かない
• モデルは Sonnet 5.5 から試し、単価重視なら Haiku 4.5、難しい処理は Opus 5.5 / Fable 5.1（料金は公式で確認）
• 長い出力はストリーミング、関数呼び出しは tool use の往復、JSONは messages.parse() で受け取る
• 同じ前置きはプロンプトキャッシュ、急がない大量処理は Batches（50%引き） でコストを下げる
• SDKは既定で2回自動リトライ（408・409・429・5xx）。例外は APIStatusError と APIConnectionError で受け、request_id を記録する
• この記事の実行結果はローカルのモックサーバーでSDKの動作を確認したもので、モデルの回答は含まない

株式会社RJCでは、生成AIのAPIを使った開発の知識を仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。