Text Completionsからの移行
Text CompletionsからMessagesへの移行
Text CompletionsからMessagesに移行する際は、以下の変更点を考慮してください。
入力と出力
Text CompletionsとMessagesの間で最も大きな変更は、モデルの入力を指定し、モデルから出力を受け取る方法です。
Text Completionsでは、入力は生の文字列です:
Messagesでは、生のプロンプトの代わりに入力メッセージのリストを指定します:
各入力メッセージにはrole
とcontent
があります。
ロール名
Text Completions APIは交互の\n\nHuman:
と\n\nAssistant:
のターンを期待しますが、Messages APIはuser
とassistant
のロールを期待します。「human」または「user」のターンを参照するドキュメントを見ることがあるかもしれません。これらは同じロールを指し、今後は「user」になります。
Text Completionsでは、モデルが生成したテキストはレスポンスのcompletion
値で返されます:
Messagesでは、レスポンスはcontent
値で、これはコンテンツブロックのリストです:
Claudeの口に言葉を入れる
Text Completionsでは、Claudeのレスポンスの一部を事前に埋めることができます:
Messagesでは、最後の入力メッセージをassistant
ロールにすることで同じ結果を得ることができます:
そうすると、レスポンスのcontent
は最後の入力メッセージのcontent
から続きます:
システムプロンプト
Text Completionsでは、システムプロンプトは最初の\n\nHuman:
ターンの前にテキストを追加することで指定されます:
Messagesでは、system
パラメータでシステムプロンプトを指定します:
モデル名
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
を使用する場合、レスポンスにはcompletion
、ping
、error
のサーバー送信イベントのいずれかが含まれます。詳細についてはText Completionsストリーミングを参照してください。
Messagesには様々なタイプの複数のコンテンツブロックが含まれる可能性があるため、そのストリーミング形式はやや複雑です。詳細についてはMessagesストリーミングを参照してください。