При миграции с 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?"},
]

Каждое входное сообщение имеет role и content.

Названия ролей

API Text Completions ожидает чередующиеся обороты \n\nHuman: и \n\nAssistant:, но API Messages ожидает роли user и assistant. Вы можете увидеть документацию, ссылающуюся на обороты “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"}
    ]
)

​
Названия моделей

API Messages требует, чтобы вы указали полную версию модели (например, claude-sonnet-4-20250514).

Ранее мы поддерживали указание только номера основной версии (например, claude-2), что приводило к автоматическим обновлениям до младших версий. Однако мы больше не рекомендуем этот шаблон интеграции, и Messages его не поддерживают.

​
Причина остановки

Text Completions всегда имеют stop_reason одного из следующих типов:

  • "stop_sequence": Модель либо естественно завершила свой ход, либо была сгенерирована одна из ваших пользовательских последовательностей остановки.
  • "max_tokens": Либо модель сгенерировала указанное вами количество max_tokens контента, либо достигла своего абсолютного максимума.

Messages имеют stop_reason одного из следующих значений:

  • "end_turn": Разговорный ход завершился естественно.
  • "stop_sequence": Была сгенерирована одна из ваших указанных пользовательских последовательностей остановки.
  • "max_tokens": (без изменений)

​
Указание максимального количества токенов

  • Text Completions: параметр max_tokens_to_sample. Без валидации, но с ограниченными значениями для каждой модели.
  • Messages: параметр max_tokens. При передаче значения выше, чем поддерживает модель, возвращает ошибку валидации.

​
Формат потоковой передачи

При использовании "stream": true с Text Completions ответ включал любые из server-sent-events completion, ping и error. См. потоковую передачу Text Completions для подробностей.

Messages могут содержать несколько блоков контента различных типов, поэтому их формат потоковой передачи несколько более сложен. См. потоковую передачу Messages для подробностей.