The Anatomy of a Messages Request

Five required and one structural decision

Every Messages API request carries five fields the API actually needs and one structural decision you make on top. Required: model, max_tokens, and messages. Optional but constantly used: system and temperature. The structural decision: do you want a single response (non-streaming) or a stream of events.

Why max_tokens is yours, not the model's

Unlike some APIs, Anthropic requires you to declare an output budget per call. This is a billing safeguard and a latency knob. Set it generously enough that legitimate completions are not truncated, but tight enough that a runaway model cannot cost you more than you budgeted. The output token budget is a real billing line, not a recommendation.

Messages, not chat

The messages array is a list of {role, content} objects with role in ['user', 'assistant']. There is no system role inside the array — the system prompt is its own top-level field. Roles must alternate (no two user messages back-to-back); if you need to inject extra context, put it inside the user turn or in the system prompt.

Principle: Treat the request body as the API contract. Helper SDK methods are convenience; the body is the truth.

Code

Minimal Messages request (Python)·python

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    system="You answer in exactly one sentence, no more.",
    messages=[
        {"role": "user", "content": "Why is max_tokens required by Anthropic but optional by some other providers?"},
    ],
    temperature=0.2,
)
print(response.content[0].text)
print("in:", response.usage.input_tokens, "out:", response.usage.output_tokens)

Same call as raw HTTP (the wire format)·bash

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "system": "You answer in exactly one sentence, no more.",
    "messages": [
      {"role": "user", "content": "Why is max_tokens required?"}
    ],
    "temperature": 0.2
  }'

Exercise

Pick a feature in your project that calls Claude. Write the smallest valid request body (model, max_tokens, messages) plus the one optional field (system or temperature) you actually need. Justify each choice in one phrase.

Hint

If you cannot justify a temperature value, drop it — the default is fine for most production calls.

The Anatomy of a Messages Request

Five required and one structural decision

Why max_tokens is yours, not the model's

Messages, not chat

Code

External links

Exercise

Progress

Comments 0