Claude API の接続で難しいのは「HTTP リクエストを送れるかどうか」ではなく、いくつか見落としやすい細部です。キーをどのリクエストヘッダーに置くのか、anthropic-version が必須なのか、max_tokens をなぜ省略できないのか、content が文字列ではなく配列なのはなぜか。ここを押さえれば、最小の呼び出しは 10 分ほどで動きます。
本記事は「アカウントとキー、リクエストヘッダー、curl、Python、ストリーミングとパラメータ、エラー切り分け、キーの安全管理」の順に説明し、最後に互換ゲートウェイを代替入口として使う方法を紹介します。モデル ID、コンテキスト、課金は Anthropic の公式ドキュメントとモデル価格を基準にしてください。
注記：Anthropic と Claude は各権利者の商標です。OpenAI は OpenAI の商標です。本記事は技術的な接続方法の説明のみを目的としています。モデル、価格、割当は変更されるため、接続前に公式ドキュメントをご確認ください。
一、接続前の準備：アカウント、ワークスペース、キー
Claude API は Anthropic Console でアカウント、ワークスペース、API キー、請求を管理します。開始前に次の 3 点を確認してください。
| 準備項目 | 確認すること | 説明 |
|---|---|---|
| アカウント | メール認証ができ、Console にログインできる | チーム利用では会社のメールアドレスを推奨 |
| ワークスペース | キーがどのワークスペースに属するか | ワークスペースはメンバー、キー、使用量の帰属に影響する |
| 課金 | 支払い方法、請求情報、利用可能な残高 | Console に実際に表示される内容を基準にする |
チームで請求の管理者が決まっていない場合は、本番用のキーを急いで作らないでください。一度キーを配布すると、使用量と権限はそのワークスペースに紐づき、後から分離するほどコストが増えます。
二、API キーの作成：6 ステップ
- Anthropic Console（console.anthropic.com）を開き、アカウントを登録またはログインしてメール認証を完了します。
- ワークスペースを作成または選択します。本番、テスト、個人の実験は分けておくと、1 本のキーをあちこちで使い回さずに済みます。
- API Keys ページで新しいキーを作成し、用途が分かる名前を付けます。たとえば
prod-backend-2026-10です。 - キーをコピーし、すぐにシークレット管理サービスまたは環境変数へ保存します。多くのコンソールは作成時に一度しか完全な値を表示しません。
- Console の課金ページで支払い方法、請求情報、上限設定を確認します。前払い、請求書、利用上限に対応するかは、コンソールに実際に表示される選択肢を基準にしてください。
- ローカルで環境変数を設定し、最小のリクエストを送ってキーが使えることを確認します。
export ANTHROPIC_API_KEY="sk-ant-あなたのキー"
キーをコード、Git リポジトリ、フロントエンドのページ、チャットの履歴に書かないでください。テスト段階でも専用のキーを作ると、いつでも無効化できて安全です。
三、リクエストヘッダーと最小の curl 呼び出し
Messages API のエンドポイントは POST https://api.anthropic.com/v1/messages で、特に重要なヘッダーは 3 つです。
| リクエストヘッダー | 値 | 役割 |
|---|---|---|
x-api-key |
あなたの API キー | Anthropic API キーの認証 |
anthropic-version |
2023-06-01 |
API バージョンの指定。欠けるとエラーになる場合がある |
content-type |
application/json |
JSON のリクエストボディを宣言 |
注意点として、API キーは x-api-key で送り、Authorization: Bearer ではありません。この 2 つの認証方式を混在させることが、401 のよくある原因です。
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-5",
"max_tokens": 1024,
"system": "あなたは日本語の技術アシスタントです。簡潔に回答してください。",
"messages": [
{"role": "user", "content": "API ゲートウェイとは何かを 3 文で説明してください。"}
]
}'
例のモデル ID は、現時点で利用できるモデルの 1 つにすぎません。実際に使えるモデル、コンテキスト、価格は公式の Models API とモデル価格を基準にしてください。レスポンスの content はコンテンツブロックの配列で、テキストは通常 content[0].text にありますが、より安全なのは配列を走査して type == "text" を判定する方法です。
四、Python で Messages API を呼び出す
公式 SDK をインストールします。
pip install anthropic
最小の呼び出しは次のとおりです。
import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="あなたは日本語の技術アシスタントです。簡潔に回答してください。",
messages=[
{"role": "user", "content": "API ゲートウェイとは何かを 3 文で説明してください。"}
],
)
for block in resp.content:
if block.type == "text":
print(block.text)
print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)
いくつか要点があります。
systemはトップレベルのパラメータです。{"role": "system"}のメッセージとして書かないでください。Messages API のメッセージロールはuserとassistantが中心です。max_tokensは必須で、今回の返答における最大出力長を表します。小さすぎると途中で切れ、stop_reasonがmax_tokensになります。大きすぎる場合はコストとタイムアウトを合わせて考えてください。resp.contentはブロックの配列で、テキストブロック、思考ブロック、ツール呼び出しブロックを含むことがあります。業務コードではテキストだけが返ると決めつけないでください。usageとstop_reasonは記録してください。請求の照合と障害調査の両方で役立ちます。
五、system、max_tokens、ストリーミング出力
system には役割設定、出力形式、境界条件を書きます。変わらない内容を前に置き、変化するユーザー入力は messages に入れると、キャッシュに当たりやすくなります。
max_tokens は「多ければよい」ものではありません。1 回の出力上限を制約するもので、入力コストは変えません。長いレポートや長いコードには十分な余裕を与え、分類や抽出では小さめに設定します。本番環境ではインターフェースの種類ごとに設定し、全体で 1 つの値を使い回さないことをおすすめします。
ストリーミング出力は、長い回答や対話型の画面に向いています。Python SDK では次のように書きます。
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=4096,
system="あなたは日本語の技術アシスタントです。",
messages=[{"role": "user", "content": "200 文字程度の製品説明を書いてください。"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
ストリーミングのリクエストでも usage と stop_reason が返るため、保存時に漏らさないでください。生の HTTP を使う場合は、リクエストボディに "stream": true を加えます。レスポンスは SSE のイベントストリームになるので、content_block_delta などのイベントを順に解析します。
六、モデル名とバージョンの選び方
Claude のモデルは Opus、Sonnet、Haiku などの系列に分かれ、系列ごとに位置づけ、コンテキスト、価格が異なります。モデル ID には安定した別名と日付付きスナップショットの 2 種類がよくあります。本番環境ではどちらを使うかを明確にし、コンソールの表示名をそのままコードに書かないでください。
選定の順序は次のとおりです。
- まず業務の評価セットで、品質要件を満たす系列を絞り込みます。
- 次に遅延、コンテキスト、コストを比較します。
- 最後に、そのモデルが対象地域と接続方式で利用できることを確認します。
モデルは追加・提供終了があり、古い ID が legacy 状態になることもあります。モデル名は設定ファイルやマッピング表にまとめ、移行時は 1 か所だけ変更するようにしてください。利用できるモデルの詳細は、公式の Models API、コンソール、モデル価格を基準にしてください。
七、401、429、400 の切り分け
| ステータスコード | よくある原因 | 確認の順序 |
|---|---|---|
| 401 | キーがない、ヘッダーの誤り、キーの無効化、ワークスペースの不一致 | x-api-key、空白や改行、キーの状態、Base URL を確認 |
| 429 | リクエスト頻度や Token レートの超過、同時実行の急増、残高の問題 | retry-after を読み、指数バックオフとジッター、キーの分割、同時実行の削減 |
| 400 | JSON が不正、max_tokens の欠落、モデル ID の誤り、パラメータの超過 |
エラーボディと request id を保存し、リクエストボディを項目ごとに確認 |
| 404 | パスまたはモデル名が存在しない | /v1/messages とモデル ID を確認 |
| 5xx | 上流の一時的な障害 | 回数を限って再試行し、直らなければ代替入口へ切り替え |
調査の際は、まず request-id レスポンスヘッダーを保存してください。401 では残高を疑う前に、認証ヘッダーとキー自体を確認します。429 は「残高切れ」とは限らず、レート制限の可能性もあります。400 は多くがリクエストボディの問題で、エラーメッセージが該当フィールドを示してくれます。
八、キーの安全管理と互換ゲートウェイという代替入口
キーの安全管理では、少なくとも次の 4 点を徹底します。環境変数またはシークレット管理サービスにだけ保存する。プロジェクトごとにキーを分ける。使用量のアラートを設定する。定期的にローテーションし、退職したメンバーのキーを無効化する。フロントエンド、モバイルアプリ、公開リポジトリに長期利用のキーを置いてはいけません。
中国国内のチームでネットワーク、支払い、請求書に問題がある場合は、Anthropic 互換エンドポイントを提供するゲートウェイで公式アドレスを置き換えられます。公式 SDK は通常、base_url とキーを変えるだけで済みます。
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
resp = client.messages.create(
model="サイト内のモデル一覧を参照",
max_tokens=256,
messages=[{"role": "user", "content": "OK とだけ返してください"}],
)
print(resp.content)
ゲートウェイが OpenAI 互換インターフェースしか提供しない場合は、Base URL を変えるだけでなく、リクエスト構造の変更やアダプター層の追加が必要です。ゲートウェイを選ぶときは、Anthropic のネイティブプロトコルに対応しているか、モデル名がどうマッピングされるか、レート制限とログのポリシーが透明かを確認してください。
九、よくある質問
Claude API と Claude の Web 版サブスクリプションは同じものですか？
いいえ。Web 版は利用者向けの製品サブスクリプションで、API は使用量に応じた課金です。アカウント体系、割当、管理画面も別です。API のキー、請求、使用量は Anthropic Console で管理します。
API キーを作成した後、完全な値を確認できますか？
多くの場合、表示されるのは作成時の一度だけです。その後は先頭の数文字か名前しか見えないため、作成後すぐにシークレット管理サービスへ保存してください。紛失した場合は古いキーを無効化し、新しいキーを作成します。
なぜ max_tokens が必須なのですか？
Messages API は 1 回の出力上限を明示する必要があり、生成長とリソースを制御するために使われます。省略すると 400 が返ります。タスクに応じて妥当な値を設定し、むやみに最大値にしないでください。
429 は残高切れですか、それとも同時実行が多すぎますか？
どちらの可能性もあります。まずレスポンスボディと retry-after を確認してください。短時間に集中して出る場合はレートや同時実行の問題が多く、継続して出て請求額も異常ならプランと使用量を確認します。対処はバックオフ再試行、同時実行の削減、キーの分割です。
中国国内のチームは必ずゲートウェイを使う必要がありますか？
いいえ。安定して直結でき、支払いとコンプライアンスの評価も完了しているチームは、公式への直結のほうが簡単です。人民元での決済、請求書、複数モデルの統一入口、ネットワーク最適化が必要な場合にゲートウェイを検討し、データと障害対応のポリシーを確認してください。
次のステップ
まず ZSQH AI Gateway への登録を行い、テスト用のキーで /v1/messages の最小リクエストを通してから業務に接続してください。モデル、コンテキスト、課金はモデル価格を基準にしてください。
関連記事：
