Making a call
By the end: You can call a model, read the reply, and know what every part of the response means.
- The shape of a request
- Roles, and what each is for
- Reading the response properly
- Checking why generation stopped
New to the messages api? Using a language model means sending it a request over the internet and getting a reply back. The request is a list of messages, each labelled with who said it — standing instructions, the person, or the model's own earlier replies. The response is one more message. That exchange is the entire interface, and the model keeps nothing afterwards: it has no memory of the request you sent a second ago. Why it matters
Talking to a model means sending some text over the internet and reading what comes back, and this is where that exchange gets pinned down: how the thing you send is put together, why each piece of it is labelled with a speaker, and how to read the reply properly rather than just printing it. What comes back carries more than the answer, including a field saying whether the model finished or simply ran out of room, and ignoring that field is how truncated text reaches users. Everything else you build sits on top of this one exchange.
A request is a list of messages#
You send a list. Each item has a role saying who is speaking, and some content. The model replies with one message.
# pip install anthropic
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "What is a stateless API?"}],
)
print(response.content[0].text)Later examples shorten this
Once past this section, examples write client.chat(messages) or client.generate(prompt) as shorthand for the call above, so that the code stays about the thing being taught rather than repeating six lines of setup. Those are not real methods on any SDK. Wherever you see one, the real call is client.messages.create as written here.
The three roles#
- system: your instructions. Who the model is, what it should do, what format to use. Not shown to the user.
- user: what the person said.
- assistant: what the model said previously. Providers differ here; some call this role model rather than assistant.
messages = [
{"role": "system", "content": "You answer in one sentence."},
{"role": "user", "content": "What is Python?"},
{"role": "assistant", "content": "A high-level programming language."},
{"role": "user", "content": "Who created it?"},
]Role names differ between providers
Anthropic and OpenAI use assistant. Google uses model. The concept is identical, only the spelling changes. This is the kind of detail to check in the documentation rather than remember.
Reading the response#
Beyond the text, two fields matter on every response and most people ignore both.
response.text # the answer
response.usage.input_tokens # what you were charged for sending
response.usage.output_tokens # what you were charged for receiving
response.stop_reason # why it stoppedstop_reason tells you whether you got the whole answer. The common values are a natural finish, hitting the maximum token limit, or the model asking to call a tool.
if response.stop_reason == "max_tokens":
# The answer is cut off mid-sentence. No exception was raised.
raise ValueError("truncated: raise max_tokens or shorten the task")Truncation is silent
When output hits the limit, you get a partial string back and nothing raises. Your JSON parse then fails somewhere unrelated, or a summary is quietly half written. Checking stop_reason is a one-line habit that saves hours.
Where people go wrong
Reading response.text without checking stop_reason. A truncated answer looks like a complete one until something downstream fails on it.
If this comes up in an interview
What are the roles in a chat request and what is each for?
system carries your instructions and is not shown to the user. user is what the person said. assistant, called model by some providers, is what the model said on previous turns. The list is the whole conversation.
What is stop_reason and why check it?
It says why generation ended: finished naturally, hit the token limit, or requested a tool. Hitting the limit truncates the output without raising an exception, so without checking it you get silently incomplete data.
Does max_tokens make the model give shorter answers?
No. It is a hard cut-off, not an instruction. The model writes as though unconstrained and gets chopped mid-word. To get a shorter answer, ask for one in the prompt.
Build this: Call a model with max_tokens set to 20 and ask for a long story. Print the text and the stop reason, and confirm it stops mid-sentence with no error raised.
Watch it explained
This is one section of The Messages API, 6 hours across 3 sections. Read it in full to get the whole topic in order.
Stop 4 of 50 on the AI Engineer route
0 of 50 topics done · 0h behind you, 603h to go
What you have marked done is stored in this browser only. It does not reach a server, and clearing site data will clear it.