最初の5分でClaude APIを動かす
Claudeを試す前に、様々なAI APIのドキュメントを調べるのに半日近くかかりました。結論：Claude APIが一番始めやすい——SDKが明確で、レスポンスが一貫していて、予期しない挙動が少ない。OpenAI SDKを使ったことがあれば、すぐに慣れるはずです。
まずライブラリをインストール：
pip install anthropic完了。さっそくAPIを呼び出してみましょう：
import anthropic
client = anthropic.Anthropic(api_key="sk-ant-api03-...")
message = client.messages.create(
model="claude-opus-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "Dockerとは何か3文で簡単に説明してください"}
]
)
print(message.content[0].text)実行してみると——数秒で回答が表示されます。これがAIアプリケーションを動かすために必要なすべてです。残りはそれを良くすること。
APIキーはconsole.anthropic.com → API Keys → Create Keyから取得できます。コードにキーをハードコードしないでください——環境変数を使いましょう：
# ~/.bashrc または ~/.zshrc に追加
export ANTHROPIC_API_KEY="sk-ant-api03-..."
# api_keyを渡さなければSDKが自動的にこの変数を読み取る
client = anthropic.Anthropic() # api_keyは不要！API構造を理解してよくあるエラーを防ぐ
Messages API — 正しい使い方
ClaudeはMessages APIを使います。旧モデルのようなCompletion APIではありません。会話の構造は、userとassistantのメッセージが交互に並ぶリストです：
messages = [
{"role": "user", "content": "Pythonを勉強しています"},
{"role": "assistant", "content": "Pythonは良い選択です！どこから始めたいですか？"},
{"role": "user", "content": "リスト内包表記から始めてもいいですか？"}
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
messages=messages
)ルール：最初のメッセージはuserでなければならず、user/assistantが交互に並ぶ必要があります。このルールに違反するとすぐにエラーが発生します——チャットボット構築時にヒストリーを正しくトリムするのを忘れてこのエラーにはまったことがあります。
システムプロンプト——出力をコントロールする主要なツール
システムプロンプトはmessagesの中ではなく、独立したパラメータとして渡します：
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
system="あなたはシニアDevOpsエンジニアです。簡潔に答え、箇条書きを使ってください。常にセキュリティへの影響について言及してください。",
messages=[
{"role": "user", "content": "nginxのリバースプロキシはどう設定しますか？"}
]
)他のAPIでは、システムメッセージをリストの先頭に通常のメッセージとして追加しますが、Claudeでは独立したパラメータとして分離されています——モデルがこのインストラクションをより高い優先度で処理するため、会話が長くなっても要件が「忘れられる」ことが少なくなります。
ストリーミング——優れたUXには必須
10秒間白い画面を見てからテキストが表示されるのを誰も望みません。ストリーミングがこの問題を解決します：
import anthropic
client = anthropic.Anthropic()
with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "PostgreSQLデータベースのバックアップスクリプトを書いてください"}]
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
print() # 完了後に改行FlaskまたはFastAPIを使えば、Server-Sent Eventsを使ってブラウザに直接ストリームできます：
from flask import Flask, Response, stream_with_context
import anthropic
import json
app = Flask(__name__)
client = anthropic.Anthropic()
@app.route("/chat")
def chat():
def generate():
with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello!"}]
) as stream:
for text in stream.text_stream:
yield f"data: {json.dumps({'text': text})}\n\n"
yield "data: [DONE]\n\n"
return Response(
stream_with_context(generate()),
mimetype="text/event-stream"
)本番アプリケーションのための高度なテクニック
プロンプトキャッシング——コストを90%削減
数千トークンの長いシステムプロンプトを毎日何百回も呼び出していますか？それはお金を無駄にしています。システムプロンプトが約3000トークン、1日約120リクエストのプロジェクトでキャッシングを有効にしたところ、コストが1日$2.1から$0.4に下がりました：
# 長いシステムプロンプトにプロンプトキャッシングを有効化
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": """あなたはeコマースシステムの技術アシスタントです。
[... システムドキュメント5000語 ...]""",
"cache_control": {"type": "ephemeral"} # キャッシュする！
}
],
messages=[{"role": "user", "content": query}]
)最初のリクエストはキャッシュ構築のためにフルコストがかかります。2回目以降のリクエストでは、キャッシュされた部分は通常価格の10%のみです。3000トークンのシステムプロンプトと1日100リクエストの場合、月約$50の節約になります。
指数バックオフによる自動リトライ
レート制限とネットワークエラーは日常的なことです。一時的なエラーでアプリケーションがクラッシュしないようにしましょう：
import anthropic
import time
def call_claude_with_retry(messages, max_retries=3, **kwargs):
client = anthropic.Anthropic()
for attempt in range(max_retries):
try:
return client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=messages,
**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.APIConnectionError as e:
if attempt == max_retries - 1:
raise
time.sleep(1)
return NoneJSONモードによる構造化出力
レスポンスを構造化データにパースする必要がある場合、正規表現は使わず——プロンプトでJSONを使いましょう：
import json
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system="常に有効なJSONのみで回答し、JSON以外のテキストは含めないでください。",
messages=[{
"role": "user",
"content": """次の文を分析してJSONを返してください：
'PostgreSQL version 14.5のサーバーが2月15日午前3時にOOMエラーが発生した'
形式: {\"component\": str, \"version\": str, \"error_type\": str, \"time\": str}"""
}]
)
data = json.loads(response.content[0].text)
print(data["error_type"]) # "OOM"実プロジェクト経験からの実践的なヒント
APIを呼び出せれば最初のステップは完了です。もっと頭を使う部分——そして請求書が届くまで無視されがちな部分——はコスト管理と出力品質の維持です。以下のことは実際に失敗してから学んだことがほとんどです：
- タスクに合ったモデルを選ぶ：シンプルなタスク（分類、抽出）にはHaiku、中程度のタスク（要約、翻訳、コードレビュー）にはSonnet、複雑なタスク（分析、推論）にはOpusを使いましょう。すべてにOpusを使うとHaikuの15倍のコストがかかります。
max_tokensを実際のニーズに合わせて設定する：回答に200トークンしか必要ないなら4096に設定しないでください。実際の出力に対してのみ課金されますが——max_tokensを高く設定すると、モデルが必要以上に冗長な出力を生成する傾向があり、レイテンシが上がりコストも増加します。- 使用トークン数をログに記録する：レスポンスオブジェクトは
input_tokensとoutput_tokensを含むmessage.usageを返します。コストを追跡し、異常にトークンを消費しているプロンプトを検出するためにログを取りましょう。 - まず
claude-haiku-4-5-20251001でテストする：開発中は、Haikuを使って素早く安価にイテレーションしましょう。実際の品質テストが必要なときだけSonnet/Opusに切り替えてください。 - 会話ヒストリーを制限する：全てのヒストリーではなく、直近の10〜20メッセージのみを保持しましょう。コンテキストウィンドウは大きいですが、コストはすぐに積み上がります。
# 会話ヒストリーを効率的に管理するパターン
def trim_history(messages, max_pairs=10):
"""直近のmax_pairs組のuser/assistantを保持する"""
if len(messages) > max_pairs * 2:
return messages[-(max_pairs * 2):]
return messages
# コストを追跡するために使用量をログに記録
response = client.messages.create(...)
print(f"Input: {response.usage.input_tokens} tokens | Output: {response.usage.output_tokens} tokens")初心者がよくやらかすこと：GitHubにコミットするソースコードにAPIキーを含めないでください。Anthropicには自動スキャンシステムがあり、検出されると即座にキーが無効化されます。python-dotenvと.envファイルを使い、.gitignoreに追加しましょう。
# .env
ANTHROPIC_API_KEY=sk-ant-api03-...
# .gitignore
.env
*.env# main.py
from dotenv import load_dotenv
load_dotenv()
client = anthropic.Anthropic() # .envから自動読み取り上のクイックスタートだけで、数時間でプロトタイプを動かせます。そこから優先順位に従って拡張しましょう：まずストリーミング（即座にUXが改善）、次にコストが増え始めたらキャッシング、最後に本番デプロイ時にリトライとエラーハンドリング。Claude APIはかなり安定しています——8ヶ月前に書いたコードベースが今でも正常に動いており、大規模なマイグレーションが必要なbreaking changeには遭遇していません。
