Claude Platform Docs
メッセージClaudeで構築

Messages APIの使用

Messages APIを効果的に使用するための実践的なパターンと例

Anthropicは、Claudeを使って構築するための2つの方法を提供しており、それぞれ異なるユースケースに適しています。

Messages APIClaude Managed Agents
概要モデルへの直接的なプロンプトアクセスマネージドインフラストラクチャ上で動作する、事前構築済みで設定可能なエージェントハーネス
最適な用途カスタムエージェントループときめ細かな制御長時間実行されるタスクと非同期作業

このガイドでは、基本的なリクエスト、マルチターン会話、プリフィル手法、ビジョン機能など、Messages APIを扱う際の一般的なパターンを説明します。完全なAPI仕様については、Messages APIリファレンスAPI リファレンスへのリンクを含むプレビューを表示できます — カードにフォーカスが移るまで Tab キーを押します。戻るには Escape キーを押します。を参照してください。代わりにマネージドエージェントハーネスについては、Claude Managed Agentsの概要を参照してください。

基本的なリクエストとレスポンス

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message)
Output
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

拒否レスポンス（stop_reason: "refusal"）には、すべてのモデルにおいて、拒否のきっかけとなったポリシーカテゴリを識別するstop_detailsオブジェクトも含まれます。フィールドリファレンスと処理コードの例については、停止理由の処理を参照してください。

複数の会話ターン

Messages APIはステートレスです。つまり、常に完全な会話履歴をAPIに送信します。このパターンを使用して、時間をかけて会話を構築できます。以前の会話ターンは、必ずしも実際にClaudeから生成されたものである必要はありません。合成されたassistantメッセージを使用できます。

ベータ版のメッセージスレッドを使用すると、APIが会話を保持できるため、以降の各リクエストでは新しいメッセージのみを送信すれば済みます。スレッドの有効期限は最後のリクエストから5分後に切れ、スレッドは最後の使用から1時間以内に削除されます。

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)
print(message)
Output
{
  "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Sure, I'd be happy to provide..."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

メッセージ内のシステムロール

ユーザーターンの後に"role": "system"を持つメッセージを含めることで、会話の途中で新しいシステム指示を追加できます（配置ルールに従います）。これはClaude Fable 5.2、Claude Mythos 5.2、Claude Fable 5.1、Claude Mythos 5.1、Claude Fable 5、Claude Mythos 5、Claude Opus 5.5、Claude Opus 4.8、Claude Opus 5、Claude Sonnet 5.5、Claude Haiku 5.5で機能します。コンテンツを含むsystemメッセージをmessagesの最初のエントリにすることはできません。最初から適用される指示には、トップレベルのsystemフィールドを使用してください。

会話途中のシステムメッセージはトップレベルのsystemフィールドと同じ権限を持ちますが、メッセージ履歴の末尾に追加されるため、それより前にあるキャッシュ済みのプレフィックスを無効にしません。最初のターンから適用すべき指示にはトップレベルのsystemフィールドを使用し、後になって初めて関連する指示には会話途中のシステムメッセージを使用してください。

プロンプトキャッシングとの組み合わせ方を含む完全なガイドについては、会話途中のシステムメッセージを参照してください。

Claudeのレスポンスのプリフィル

入力メッセージリストの最後の位置で、Claudeのレスポンスの一部をプリフィル（事前入力）できます。この手法を使用して、Claudeのレスポンスを形作ります。次の例では、"max_tokens": 1を使用してClaudeから単一の多肢選択式の回答を取得します。

message = anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1,
    messages=[
        {
            "role": "user",
            "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
        },
        {"role": "assistant", "content": "The answer is ("},
    ],
)
print(message)
Output
{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

ビジョン

Claudeはリクエスト内のテキストと画像の両方を読み取ることができます。画像はbase64、url、またはfileのソースタイプを使用して提供できます。fileソースタイプは、Files APIを通じてアップロードされた画像を参照します。サポートされているメディアタイプはimage/jpeg、image/png、image/gif、image/webpです。詳細については、ビジョンガイドを参照してください。

import base64
import httpx2

# オプション 1: base64 エンコードされた画像
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message)

# オプション 2: URL で参照する画像
message_from_url = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://platform.claude.com/docs/images/vision-example.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)
Output
{
  "id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

次のステップ

停止理由とフォールバック

各stop_reasonの値を処理し、レスポンスが終了したときの対応を決定します。

Claudeでのツール使用

Messages API内から外部サービスやAPIを呼び出すためのツールをClaudeに提供します。

コンピューター使用ツール

Messages APIでデスクトップコンピューター環境を制御します。

ブラウザ使用ツール

お使いのブラウザ上で、Claudeにウェブページのナビゲーション、読み取り、操作を行わせます。

構造化出力

Claudeから、スキーマ検証済みであることが保証されたJSON出力を取得します。

タスク予算

output_config.task_budgetを使用して、エージェントループ全体にわたる参考用のトークン予算を設定します。

利用可能状況

Messages API
Availability requirements for Messages API are the same across all supported platforms.
モデル
  • すべてのモデル

データの取り扱い

データの取り扱いの概要

対象エンドポイント

  • /v1/messages
ゼロデータ保持対象

対象モデルを除く

Claudeの応答を生成するための標準API呼び出しです。

HIPAA対象

このページは役に立ちましたか？