Chapter 2 · Part 1

The Messages API

Almost everything you'll ever do with Claude goes through one endpoint: the Messages API, which you call with client.messages.create(...). Learn its four moving parts and the rest of this course is variations on a theme.

The request

anatomy.py
message = client.messages.create(
  model="claude-opus-4-8",     # which model answers
  max_tokens=1024,             # cap on how long the reply can be
  system="You are a helpful assistant who explains things simply.",
  messages=[
      {"role": "user", "content": "What is an API, in one sentence?"}
  ],
)
  • model — which Claude to use. claude-opus-4-8 is the most capable; we'll meet cheaper, faster options in Chapter 6.
  • max_tokens — the maximum length of the reply, measured in tokens (~¾ of a word each, as the ChatGPT course explains). It's a hard ceiling: set it too low and the answer gets cut off mid-sentence.
  • system — the system prompt: standing instructions that set the model's role and rules. It's separate from the conversation and steers how Claude responds.
  • messages — the conversation itself: a list of turns, each with a role and content. Right now there's a single user turn.

Roles

Every message has a role. There are two you'll use:

  • user — what the human says.
  • assistant — what Claude said (you'll add these yourself next chapter, to give the model memory of its own replies).

The list must start with a user message. That's the whole grammar of a conversation.

The response

create() returns a Message object. The reply isn't a plain string — it's a list of content blocks, because a response can contain several kinds of content (text, tool calls, and more). For a plain text answer there's one text block:

response.py
print(message.content)          # [TextBlock(type='text', text='An API is ...')]
print(message.content[0].text)  # the actual answer string
print(message.stop_reason)      # 'end_turn' — Claude finished on its own
print(message.usage)            # token counts (we'll use these for cost in Ch 6)

message.content[0].text is the move you'll make constantly — reach into the first block and pull out its text. stop_reason tells you why it stopped: end_turn means it finished naturally; max_tokens means it hit your length cap and got cut off; tool_use (Chapter 5) means it wants to call a tool.

You now know the shape of every request and response. Time to string them together into an actual conversation.