Messages API の基本（学習ガイド）

Claude をアプリケーションから使うときの基本が、Messages API（POST /v1/messages）です。会話を messages の配列で渡し、Claude の応答をコンテンツブロックの配列として受け取ります。

公式の SDK を使えば、認証のヘッダーなどは自動で付きます。それでも、リクエストの構造を理解しておくと、エラーの原因を見つけやすくなります。

一、必須のパラメータは model・max_tokens・messages
リクエストでは、使うモデル（model）、生成する最大トークン数（max_tokens）、会話（messages）が必須です。HTTP で直接呼ぶ場合は、認証の x-api-key と、API のバージョンを指定する anthropic-version のヘッダーを付けます。
二、システムプロンプトはトップレベルの system に書く
Messages API には、"system" ロールのメッセージはありません。役割や前提の指示は、トップレベルの system パラメータで渡します。messages のロールは user と assistant です。
三、停止理由（stop_reason）を確かめる
自然に回答を終えると "end_turn"、max_tokens に達して打ち切られると "max_tokens"、指定した停止文字列で止まると "stop_sequence"、ツールを使おうとしていると "tool_use" になります。
四、ストリーミングと画像の入力
stream: true を指定すると、応答が Server-Sent Events（SSE）で少しずつ届きます。画像は、user メッセージの content に image ブロックとして入れ、base64 のデータや URL を指定します。
五、エラーは状態コードに応じて対処する
429 はレート制限なので、待ち時間を伸ばしながら再試行します。400 はリクエストの形式の誤り、401 は認証の問題です。

用語	意味
Messages API	Claude と対話するための API（POST /v1/messages）。
max_tokens	生成するトークン数の上限。必須のパラメータ。
system パラメータ	システムプロンプトを渡す、リクエストのトップレベルの項目。
コンテンツブロック	テキスト・画像・ツール呼び出しなど、メッセージを構成する単位。
stop_reason	応答の生成が止まった理由。