Messages API Basics

Messages API の基本

約 14 分 · クイズ 4 問 · 演習 1 問

重要キーワード (4 語)

Messages API (メッセージAPI) — Claude API の中心エンドポイント

Stateless (ステートレス) — サーバーが会話状態を保持しない設計

Content Block (コンテンツブロック) — 応答の構成要素 (text/image/tool_use 等)

stop_reason (停止理由) — 応答が終了した理由 (end_turn / max_tokens / tool_use ...)

Messages API

Claude API の中心は Messages API です。 messages.create() を呼ぶことで応答を得ます。

リクエストの構造

client.messages.create(
    model="claude-sonnet-4-6",          # モデル ID
    max_tokens=1024,                    # 出力上限
    system="あなたは丁寧な日本語アシスタントです。",
    messages=[
        {"role": "user", "content": "Pythonとは?"},
        {"role": "assistant", "content": "Python は..."},
        {"role": "user", "content": "では JavaScript は?"},
    ],
    temperature=0.7,                    # 0.0 〜 1.0 の創造性
    stop_sequences=["END"],             # 出てきたら停止
)

レスポンスの構造

{
  "id": "msg_01...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {"type": "text", "text": "JavaScript は..."}
  ],
  "stop_reason": "end_turn",   # end_turn / max_tokens / stop_sequence / tool_use
  "usage": {"input_tokens": 42, "output_tokens": 128}
}

マルチターン会話

会話履歴は すべてのターンを送り直す のが基本ルールです。モデル側に状態は保持されません (stateless)。

history = []
def chat(user_msg):
    history.append({"role": "user", "content": user_msg})
    res = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=history,
    )
    text = res.content[0].text
    history.append({"role": "assistant", "content": text})
    return text

content の中身

content は テキスト・画像・ツール呼び出し などの「ブロック」の配列です。複雑な応答ではブロックが複数返ることがあります。

for block in msg.content:
    if block.type == "text":
        print(block.text)
    elif block.type == "tool_use":
        print("Tool call:", block.name, block.input)
    elif block.type == "thinking":
        print("Internal thought:", block.thinking)

user メッセージも構造化できる

content は文字列だけでなく配列で渡せます。画像や複数テキストブロックが混在可能。

messages=[{
    "role": "user",
    "content": [
        {"type": "text", "text": "この画像を説明して"},
        {"type": "image", "source": {"type": "url", "url": "https://example.com/cat.jpg"}},
    ],
}]

stop_reason の意味

値	意味
`end_turn`	自然終了 (ふつうの完了)
`max_tokens`	max_tokens に到達した (途中切断)
`stop_sequence`	stop_sequences のいずれかが出現
`tool_use`	ツール呼び出しを要求 (Tool Use 中)
`pause_turn`	長時間処理 (Claude Code on the web 等) で一時停止

試してみる: マルチターン

簡単な対話を Playground で再現してみましょう。

▶ ターンの感覚を掴む

私は今 Python の入門書を選んでいます。3 冊おすすめしてください。

(↑ の応答を見たら、続けて「2 冊目について、対象読者をもっと詳しく」と聞いてみましょう)