Text CompletionsからMessagesに移行する際は、以下の変更点を考慮してください。

入力と出力

Text CompletionsとMessagesの間で最も大きな変更は、モデルの入力を指定し、モデルから出力を受け取る方法です。

Text Completionsでは、入力は生の文字列です:

Python
prompt = "\n\nHuman: Hello there\n\nAssistant: Hi, I'm Claude. How can I help?\n\nHuman: Can you explain Glycolysis to me?\n\nAssistant:"

Messagesでは、生のプロンプトの代わりに入力メッセージのリストを指定します:

messages = [
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm Claude. How can I help?"},
  {"role": "user", "content": "Can you explain Glycolysis to me?"},
]

各入力メッセージにはrolecontentがあります。

ロール名

Text Completions APIは交互の\n\nHuman:\n\nAssistant:のターンを期待しますが、Messages APIはuserassistantのロールを期待します。「human」または「user」のターンを参照するドキュメントを見ることがあるかもしれません。これらは同じロールを指し、今後は「user」になります。

Text Completionsでは、モデルが生成したテキストはレスポンスのcompletion値で返されます:

Python
>>> response = anthropic.completions.create(...)
>>> response.completion
" Hi, I'm Claude"

Messagesでは、レスポンスはcontent値で、これはコンテンツブロックのリストです:

Python
>>> response = anthropic.messages.create(...)
>>> response.content
[{"type": "text", "text": "Hi, I'm Claude"}]

Claudeの口に言葉を入れる

Text Completionsでは、Claudeのレスポンスの一部を事前に埋めることができます:

Python
prompt = "\n\nHuman: Hello\n\nAssistant: Hello, my name is"

Messagesでは、最後の入力メッセージをassistantロールにすることで同じ結果を得ることができます:

Python
messages = [
  {"role": "human", "content": "Hello"},
  {"role": "assistant", "content": "Hello, my name is"},
]

そうすると、レスポンスのcontentは最後の入力メッセージのcontentから続きます:

JSON
{
  "role": "assistant",
  "content": [{"type": "text", "text": " Claude. How can I assist you today?" }],
  ...
}

システムプロンプト

Text Completionsでは、システムプロンプトは最初の\n\nHuman:ターンの前にテキストを追加することで指定されます:

Python
prompt = "Today is January 1, 2024.\n\nHuman: Hello, Claude\n\nAssistant:"

Messagesでは、systemパラメータでシステムプロンプトを指定します:

Python
anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="Today is January 1, 2024.", # <-- システムプロンプト
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)

モデル名

Messages APIでは、完全なモデルバージョン(例:claude-sonnet-4-20250514)を指定する必要があります。

以前は、メジャーバージョン番号のみの指定(例:claude-2)をサポートしており、これによりマイナーバージョンへの自動アップグレードが行われていました。しかし、この統合パターンはもはや推奨されておらず、Messagesではサポートされていません。

停止理由

Text Completionsは常に以下のいずれかのstop_reasonを持ちます:

  • "stop_sequence":モデルが自然にターンを終了したか、カスタム停止シーケンスの1つが生成されました。
  • "max_tokens":モデルが指定されたmax_tokensのコンテンツを生成したか、絶対最大値に達しました。

Messagesは以下の値のいずれかのstop_reasonを持ちます:

  • "end_turn":会話のターンが自然に終了しました。
  • "stop_sequence":指定されたカスタム停止シーケンスの1つが生成されました。
  • "max_tokens":(変更なし)

最大トークンの指定

  • Text Completions:max_tokens_to_sampleパラメータ。検証なしですが、モデルごとに上限値があります。
  • Messages:max_tokensパラメータ。モデルがサポートする値より高い値を渡すと、検証エラーが返されます。

ストリーミング形式

Text Completionsで"stream": trueを使用する場合、レスポンスにはcompletionpingerrorのサーバー送信イベントのいずれかが含まれます。詳細についてはText Completionsストリーミングを参照してください。

Messagesには様々なタイプの複数のコンテンツブロックが含まれる可能性があるため、そのストリーミング形式はやや複雑です。詳細についてはMessagesストリーミングを参照してください。