Anthropic対話フォーマット（Messages）

Anthropic 対話フォーマット（Messages）

このページの概要

公式ドキュメント

• Anthropic Messages
• Anthropic Streaming Messages

📝 はじめに

テキストや画像を含む構造化された入力メッセージのリストを与えると、モデルは対話の次のメッセージを生成します。Messages API は、単発の問い合わせやステートレスなマルチターン対話に使用できます。

💡 リクエスト例

基本的なテキスト対話 ✅

curl https://4AllAPI地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

レスポンス例:

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2095,
    "output_tokens": 503
  }
}

画像分析対話 ✅

curl https://4AllAPI地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "/9j/4AAQSkZJRg..."
                    }
                },
                {
                    "type": "text",
                    "text": "この画像には何が写っていますか?"
                }
            ]
        }
    ]
}'

レスポンス例:

{
  "content": [
    {
      "text": "この画像には、窓辺で日向ぼっこをしているオレンジ色の猫が写っています。猫はとてもリラックスしている様子で、目を細めながら日差しを楽しんでいます。窓の外にはいくつかの緑の植物が見えます。",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-4-6-sonnet-20251022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

ツール呼び出し ✅

curl https://4AllAPI地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-4-6-sonnet-20251022",
    "messages": [
        {
            "role": "user",
            "content": "今日の北京の天気はどうですか?"
        }
    ],
    "tools": [
        {
            "name": "get_weather",
            "description": "指定した場所の現在の天気を取得する",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "都市名。例:北京"
                    }
                },
                "required": ["location"]
            }
        }
    ]
}'

レスポンス例:

{
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
      "name": "get_weather",
      "input": { "location": "北京" }
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
  "model": "claude-4-6-sonnet-20251022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

ストリーミング応答 ✅

curl https://4All API地址/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $4All API_API_KEY" \
     --data \
'{
    "model": "claude-4-6-sonnet-20251022",
    "messages": [
        {
            "role": "user",
            "content": "お話を聞かせて"
        }
    ],
    "stream": true
}'

レスポンス例:

{
  "type": "message_start",
  "message": {
    "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
    "model": "claude-4-6-sonnet-20251022",
    "role": "assistant",
    "type": "message"
  }
}
{
  "type": "content_block_start",
  "index": 0,
  "content_block": {
    "type": "text"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "昔々"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "、"
  }
}
{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "text": "小さなウサギがいました..."
  }
}
{
  "type": "content_block_stop",
  "index": 0
}
{
  "type": "message_delta",
  "delta": {
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 2045,
      "output_tokens": 628
    }
  }
}
{
  "type": "message_stop"
}

📮 リクエスト

エンドポイント

POST /v1/messages

認証方法

リクエストヘッダーに以下を含めて API キー認証を行います:

x-api-key: $4All API_API_KEY

ここで $4All API_API_KEY はあなたの API キーです。API キーはコンソールから取得でき、各キーは1つのワークスペースでのみ使用できます。

リクエストヘッダーのパラメータ

anthropic-beta

• 型: 文字列
• 必須: いいえ

使用する beta バージョンを指定します。beta1,beta2 のようにカンマ区切りのリストを指定することも、ヘッダーを複数回指定することもできます。

anthropic-version

• 型: 文字列
• 必須: はい

使用する API バージョンを指定します。

リクエストボディのパラメータ

max_tokens

• 型: 整数
• 必須: はい

生成する最大 token 数です。モデルによって上限が異なります。詳細はモデルドキュメントを参照してください。範囲 x > 1 です。

messages

• 型: オブジェクト配列
• 必須: はい

入力メッセージのリストです。モデルは user と assistant が交互にやり取りする形で学習されています。新しいメッセージを作成する際は、messages パラメータで過去の会話ターンを指定できます。モデルは対話の次のメッセージを生成します。連続する user メッセージまたは assistant メッセージは、1つのターンとしてまとめられます。

各メッセージには role と content フィールドが必要です。単一の user ロールのメッセージ、または複数の user / assistant メッセージを指定できます。最後のメッセージが assistant ロールの場合、応答内容はそのメッセージの内容の続きから直接生成されます。これにより、モデルの応答を制約できます。

単一の user メッセージの例:

[{"role": "user", "content": "Hello, Claude"}]

マルチターン対話の例:

[
  {"role": "user", "content": "こんにちは。"},
  {"role": "assistant", "content": "こんにちは！私は Claude です。何をお手伝いしましょうか？"},
  {"role": "user", "content": "LLM とは何か、簡単に説明してください。"}
]

部分的に入力済みの応答例:

[
  {"role": "user", "content": "太陽のギリシャ語名は何ですか? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "正解は ("}
]

各メッセージの content は、文字列または content block の配列にできます。文字列は “text” タイプの content block 配列の省略形です。以下の2つの書き方は同等です:

{"role": "user", "content": "Hello, Claude"}

{
  "role": "user",
  "content": [{"type": "text", "text": "Hello, Claude"}]
}

Claude 3 モデル以降では、画像 content block も送信できます:

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRg..."
      }
    },
    {
      "type": "text",
      "text": "この画像には何が写っていますか?"
    }
  ]
}

現在サポートされている画像形式には、base64、image/jpeg、image/png、image/gif、image/webp が含まれます。

messages.role

• 型: 列挙型文字列
• 必須: はい
• 使用可能な値: user, assistant

注意: Messages API には “system” ロールはありません。システムプロンプトが必要な場合は、トップレベルの system パラメータを使用してください。

messages.content [

• 型: 文字列またはオブジェクト配列
• 必須: はい

メッセージ内容は、以下のいずれかのタイプです:

テキスト内容 (Text)

{
  "type": "text",          // 必須、列挙値: "text"
  "text": "Hello, Claude", // 必須、最小長: 1
  "cache_control": {
    "type": "ephemeral"    // 任意、列挙値: "ephemeral"
  }
}

画像内容 (Image)

{
  "type": "image",         // 必須、列挙値: "image"
  "source": {             // 必須
    "type": "base64",     // 必須、列挙値: "base64"
    "media_type": "image/jpeg", // 必須、対応: image/jpeg, image/png, image/gif, image/webp
    "data": "/9j/4AAQSkZJRg..."  // 必須、base64 エンコードされた画像データ
  },
  "cache_control": {
    "type": "ephemeral"    // 任意、列挙値: "ephemeral"
  }
}

ツール使用 (Tool Use)

{
  "type": "tool_use",      // 必須、列挙値: "tool_use"、デフォルト値
  "id": "toolu_xyz...",    // 必須、ツール使用の一意な識別子
  "name": "get_weather",   // 必須、ツール名、最小長: 1
  "input": {              // 必須、ツールの入力パラメータオブジェクト
    // ツール入力パラメータ。具体的な形式はツールの input_schema によって定義されます
  },
  "cache_control": {
    "type": "ephemeral"    // 任意、列挙値: "ephemeral"
  }
}

ツール結果 (Tool Result)

{
  "type": "tool_result",   // 必須、列挙値: "tool_result"
  "tool_use_id": "toolu_xyz...",  // 必須
  "content": "結果の内容",   // 必須、文字列または content block 配列
  "is_error": false,      // 任意、ブール値
  "cache_control": {
    "type": "ephemeral"    // 任意、列挙値: "ephemeral"
  }
}

content が content block 配列の場合、各 content block はテキストまたは画像にできます:

{
  "type": "tool_result",
  "tool_use_id": "toolu_xyz...",
  "content": [
    {
      "type": "text",      // 必須、列挙値: "text"
      "text": "分析結果",   // 必須、最小長: 1
      "cache_control": {
        "type": "ephemeral" // 任意、列挙値: "ephemeral"
      }
    },
    {
      "type": "image",     // 必須、列挙値: "image"
      "source": {         // 必須
        "type": "base64", // 必須、列挙値: "base64"
        "media_type": "image/jpeg",
        "data": "..."
      },
      "cache_control": {
        "type": "ephemeral"
      }
    }
  ]
}

ドキュメント (Document)

{
  "type": "document",      // 必須、列挙値: "document"
  "source": {             // 必須
    // ドキュメントのソースデータ
  },
  "cache_control": {
    "type": "ephemeral"    // 任意、列挙値: "ephemeral"
  }
}

注意: 1. 各タイプには、content のキャッシュ動作を制御するための任意の cache_control フィールドを含めることができます 2. テキスト内容の最小長は 1 です 3. すべてのタイプの type フィールドは必須の列挙型文字列です 4. ツール結果の content フィールドは、文字列またはテキスト/画像を含む content block 配列をサポートします

model

• 型: 文字列
• 必須: はい

使用するモデル名です。詳細はモデルドキュメントを参照してください。範囲は 1 - 256 文字です。

metadata

• 型: オブジェクト
• 必須: いいえ

リクエストのメタデータを表すオブジェクトです。以下の任意フィールドを含みます:

• user_id : リクエストに関連付けられるユーザーの外部識別子。uuid、ハッシュ値、または他の不透明な識別子を指定してください。名前、メールアドレス、電話番号などの識別情報は含めないでください。最大長: 256。

stop_sequences

• 型: 文字列配列
• 必須: いいえ

生成を停止するカスタムの文字列シーケンスです。

stream

• 型: ブール値
• 必須: いいえ

サーバー送信イベント (SSE) を使って応答内容を逐次返すかどうかを指定します。

system

• 型: 文字列
• 必須: いいえ

Claude に背景情報と指示を与えるシステムプロンプトです。モデルに文脈や特定の目標・役割を与えるために使用します。これはメッセージ内の role とは異なります。Messages API には “system” ロールはありません。

temperature

• 型: 数値
• 必須: いいえ
• デフォルト値: 1.0

生成のランダム性を制御します。0.0 - 1.0 の範囲です。範囲 x < 1 です。分析的・選択問題系のタスクでは 0.0 に近い値、創造的・生成的なタスクでは 1.0 に近い値を推奨します。

注意: temperature を 0.0 にしても、結果は完全には決定的になりません。

🆕 thinking

• 型: オブジェクト
• 必須: いいえ

Claude の拡張思考機能を設定します。有効にすると、最終回答を出す前の Claude の思考過程を示す content block が応答に含まれます。少なくとも 1,024 token の予算が必要で、max_tokens の制限に含まれます。

以下の2つのモードのいずれかを設定できます:

1. 有効モード

{
  "type": "enabled",
  "budget_tokens": 2048
}

• type : 必須、列挙値: “enabled”
• budget_tokens : 必須、整数。Claude が内部推論に使用できる token 数を決定します。予算を大きくするほど、複雑な問題に対してより深く分析でき、応答品質が向上します。1024 以上かつ max_tokens 未満である必要があります。範囲 x > 1024 です。

2. 無効モード

{
  "type": "disabled"
}

• type : 必須、列挙値: “disabled”

tool_choice

• 型: オブジェクト
• 必須: いいえ

提供されたツールをモデルがどのように使うかを制御します。以下の3種類があります:

1. Auto モード（自動選択）

{
  "type": "auto",  // 必須、列挙値: "auto"
  "disable_parallel_tool_use": false  // 任意、デフォルト false。true の場合、モデルは最大1つのツールしか使用しません
}

2. Any モード（任意のツール）

{
  "type": "any",  // 必須、列挙値: "any"
  "disable_parallel_tool_use": false  // 任意、デフォルト false。true の場合、モデルは必ず1つのツールを使用します
}

3. Tool モード（指定ツール）

{
  "type": "tool",  // 必須、列挙値: "tool"
  "name": "get_weather",  // 必須、使用するツール名を指定
  "disable_parallel_tool_use": false  // 任意、デフォルト false。true の場合、モデルは必ず1つのツールを使用します
}

注意: 1. Auto モード: モデルがツールを使うかどうかを自分で判断できます 2. Any モード: モデルはツールを使う必要がありますが、利用可能な任意のツールを選べます 3. Tool モード: モデルは指定されたツールを使う必要があります

tools

• 型: オブジェクト配列
• 必須: いいえ

モデルが使用可能なツールを定義します。ツールにはカスタムツールと組み込みツールタイプがあります:

1. カスタムツール（Tool）

各カスタムツール定義には以下が含まれます:

• type : 任意、列挙値: “custom”
• name : ツール名、必須、1-64 文字
• description : ツールの説明、できるだけ詳しく記述することを推奨
• input_schema : ツール入力の JSON Schema 定義、必須
• cache_control : キャッシュ制御、任意。type は “ephemeral”

例:

[
  {
    "type": "custom",
    "name": "get_weather",
    "description": "指定した場所の現在の天気を取得する",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "都市名。例:北京"
        }
      },
      "required": ["location"]
    }
  }
]

2. コンピューターツール (ComputerUseTool)

{
  "type": "computer_20241022",  // 必須
  "name": "computer",           // 必須、列挙値: "computer"
  "display_width_px": 1024,     // 必須、表示幅（ピクセル）
  "display_height_px": 768,     // 必須、表示高さ（ピクセル）
  "display_number": 0,          // 任意、X11 のディスプレイ番号
  "cache_control": {
    "type": "ephemeral"         // 任意
  }
}

3. Bash ツール (BashTool)

{
  "type": "bash_20241022",      // 必須
  "name": "bash",               // 必須、列挙値: "bash"
  "cache_control": {
    "type": "ephemeral"         // 任意
  }
}

4. テキストエディターツール (TextEditor)

{
  "type": "text_editor_20241022", // 必須
  "name": "str_replace_editor",   // 必須、列挙値: "str_replace_editor"
  "cache_control": {
    "type": "ephemeral"           // 任意
  }
}

モデルがツールを使用すると、tool_use content block が返されます:

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_weather",
    "input": { "location": "北京" }
  }
]

ツールを実行し、tool_result content block で結果を返すことができます:

[
  {