Ao migrar de Text Completions para Messages, considere as seguintes mudanças.

​
Entradas e saídas

A maior mudança entre Text Completions e Messages é a forma como você especifica as entradas do modelo e recebe as saídas do modelo.

Com Text Completions, as entradas são strings brutas:

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:"

Com Messages, você especifica uma lista de mensagens de entrada em vez de um prompt bruto:

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?"},
]

Cada mensagem de entrada tem um role e content.

Nomes de papéis

A API Text Completions espera turnos alternados de \n\nHuman: e \n\nAssistant:, mas a API Messages espera papéis user e assistant. Você pode ver documentação referindo-se a turnos “human” ou “user”. Estes se referem ao mesmo papel, e será “user” daqui para frente.

Com Text Completions, o texto gerado pelo modelo é retornado nos valores completion da resposta:

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

Com Messages, a resposta é o valor content, que é uma lista de blocos de conteúdo:

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

​
Colocando palavras na boca do Claude

Com Text Completions, você pode pré-preencher parte da resposta do Claude:

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

Com Messages, você pode alcançar o mesmo resultado fazendo com que a última mensagem de entrada tenha o papel assistant:

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

Ao fazer isso, o content da resposta continuará a partir do content da última mensagem de entrada:

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

​
Prompt do sistema

Com Text Completions, o prompt do sistema é especificado adicionando texto antes do primeiro turno \n\nHuman::

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

Com Messages, você especifica o prompt do sistema com o parâmetro system:

Python
anthropic.Anthropic().messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    system="Today is January 1, 2024.", # <-- prompt do sistema
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)

​
Nomes dos modelos

A API Messages requer que você especifique a versão completa do modelo (por exemplo, claude-sonnet-4-20250514).

Anteriormente, suportávamos especificar apenas o número da versão principal (por exemplo, claude-2), o que resultava em atualizações automáticas para versões menores. No entanto, não recomendamos mais esse padrão de integração, e Messages não o suportam.

​
Razão de parada

Text Completions sempre têm um stop_reason de:

  • "stop_sequence": O modelo terminou seu turno naturalmente, ou uma de suas sequências de parada personalizadas foi gerada.
  • "max_tokens": O modelo gerou seus max_tokens especificados de conteúdo, ou atingiu seu máximo absoluto.

Messages têm um stop_reason de um dos seguintes valores:

  • "end_turn": O turno conversacional terminou naturalmente.
  • "stop_sequence": Uma de suas sequências de parada personalizadas especificadas foi gerada.
  • "max_tokens": (inalterado)

​
Especificando tokens máximos

  • Text Completions: parâmetro max_tokens_to_sample. Sem validação, mas valores limitados por modelo.
  • Messages: parâmetro max_tokens. Se passar um valor maior do que o modelo suporta, retorna um erro de validação.

​
Formato de streaming

Ao usar "stream": true com Text Completions, a resposta incluía qualquer um dos eventos enviados pelo servidor completion, ping e error. Veja Text Completions streaming para detalhes.

Messages podem conter múltiplos blocos de conteúdo de tipos variados, e então seu formato de streaming é um pouco mais complexo. Veja Messages streaming para detalhes.