Claude Messages API mechanics: requests, state, tools, streaming and vision

1.How a Messages request and response are shaped

The Messages API gives you direct access to the model, and it is the surface you use when you want to write your own agent loop. Each call is one request with three required parts: a model, a max_tokens ceiling on the reply, and a messages list in which every entry has a role (user or assistant) and some content. Instructions that should hold from the first turn go in the top-level system field, outside the list.

The reply is one assistant message. Its content is an array of typed blocks, not a string. A plain answer is a single text block. The same array can also hold tool_use blocks and thinking blocks, so code that reads content[0].text will break once you turn those features on. Two other fields carry the facts your code branches on. stop_reason says why generation stopped: end_turn, max_tokens, stop_sequence, tool_use or refusal. usage reports input_tokens and output_tokens, which is where your billing and context-size numbers come from.

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-opus-5-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

A stop_reason of max_tokens means the reply was cut off at your ceiling. It is not a finished answer. With refusal, the response also includes a stop_details object that names the policy category behind the refusal, so you can log it or tell the user why.

Sources12

2.Conversation state lives in your code

The API has no session, so your application is the conversation store. After each reply, append the assistant message to your list, append the next user turn, and send the whole list. Data access works the same way: anything Claude should be able to see in turn 7 (a document, a screenshot, a tool result from turn 2) has to be in the turn 7 request.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"},
    ],
)

Since you write the history yourself, you can put things in it. Assistant turns don't have to come from Claude: a synthetic few-shot exchange is valid input. On older models such as Claude Sonnet 4.5, an assistant message in the last position works as a prefill, and Claude continues from where it ends. Pair a prefill of The answer is ( with max_tokens: 1 and you get back a single multiple-choice letter. Don't build new code on that pattern: Claude Opus 4.6 already rejects prefilled assistant turns, and the Opus 5.5 migration checklist says to remove them. On recent models such as Claude Opus 5.5 and Sonnet 5.5, you can instead add a role: "system" message after a user turn to bring in an instruction partway through. It cannot be the first entry in messages.

Prompt caching reuses work across those resent histories. A cache_control marker on a content block sets a cache breakpoint: everything up to and including that block is the reusable prefix. In the response's usage, cache_read_input_tokens counts tokens served from that cached prefix, and cache_creation_input_tokens counts tokens newly written to it. A read count stuck at zero means the prefix never repeats.

Resending the full history on every call is what makes [prompt caching](lesson:5.4) worth using, and it puts one requirement on how you build requests: the prefix has to stay byte-identical. The cache key is a hash of the prompt up to the breakpoint, so anything that changes early in the request, like a timestamp in the system prompt, a reordered tool list or an edited earlier turn, produces a new key and a cache miss. Put changing content at the end. A mid-conversation system message is appended to the end of the history, so it leaves the cached prefix before it intact.

How long an entry survives is set on the marker. The default lifetime is 5 minutes, refreshed at no extra cost each time the entry is used, and it is measured from the start of the request, so a slow streamed response eats into it. Adding "ttl": "1h" to cache_control requests a one-hour entry instead. Writes cost more than ordinary input: 25% extra for the 5-minute entry and 2x the base input price for the 1-hour one. The longer entry pays for itself when requests arrive more than five minutes apart or responses run long enough to outlast the window.

Sources134

3.Tool calls and thinking blocks in the request loop

Tool use runs on the same stateless request cycle. Claude never runs anything itself. When it wants a tool, the response has stop_reason: "tool_use" and one or more tool_use blocks, each with a tool name and a JSON object of arguments. Your code runs the operation and sends the output back as tool_result blocks in a new user message. That message goes at the end of the full history, after the assistant turn that asked for the tool. Keep looping while stop_reason is tool_use. Any other stop reason ends the loop. Writing the tool schemas themselves is covered in [Tool implementation](lesson:8.1).

Server tools are different. For web_search, web_fetch, code_execution and tool_search, Anthropic runs the code, and you never build a tool_result. The response shows server_tool_use blocks for what ran. That server-side loop has an iteration cap. When it hits the cap, the response comes back with stop_reason: "pause_turn", and you continue by sending the conversation again with the paused response included.

[Extended and adaptive thinking](lesson:5.3) adds thinking blocks to the assistant's content, and each one carries a signature. In a tool loop, send those blocks back exactly as you received them, including blocks whose thinking text is empty. The safe way is to append the assistant message as you received it. Don't filter its blocks by type and don't rebuild it from parts. The API rejects thinking blocks that have been edited, reordered or partly dropped with a 400 error.

On Claude Opus 5.5, thinking is not optional: every request runs with adaptive thinking, so any response can open with thinking blocks. Thinking tokens are billed as output tokens even when the thinking text is not returned, and they count against max_tokens, which stays a hard limit on thinking plus reply text. A ceiling tuned for a model that ran without thinking can now cut the answer short, and at xhigh or max effort the migration guide suggests starting at 64k.

Depth is controlled by the effort parameter rather than by a thinking budget. Set output_config={"effort": "medium"} (the Opus 5.5 default) and lower it to spend fewer tokens on thinking. The old thinking: {"type": "enabled", "budget_tokens": N} form is replaced by thinking: {"type": "adaptive"} plus effort, or by no thinking field at all. On models that still use manual extended thinking, the budget counts toward max_tokens too. What you see is also a setting: thinking.display defaults to "omitted", so thinking blocks arrive with an empty thinking field and a signature. Set "summarized" to receive readable summaries, and treat the field as display text only.

Sources235

4.Streaming responses as server-sent events

Set "stream": true and the response arrives as server-sent events, so a UI can show text as it is generated. Streaming also helps when nobody is watching. With a large max_tokens, the SDK requires streaming to avoid HTTP timeouts. Its accumulation helper streams under the hood and hands you the same complete Message object that messages.create() would.

Each kind of block streams a different delta. A text_delta carries a piece of text. A tool_use block streams input_json_delta events made of partial JSON strings, so collect them and parse once content_block_stop arrives, or use the SDK helpers that parse as the input streams. Thinking streams as thinking_delta, followed by one signature_delta just before the block closes. That signature is what the tool loop above must send back. Errors can also arrive mid-stream: overloaded_error is the streaming version of an HTTP 529. And because new event types may be added, a parser should skip unknown events rather than crash on them.

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-opus-5-5",
) as stream:
    message = stream. ? ()

Sources6

5.Sending images and files: inline, by URL, or by file ID

An image is just another content block in a user turn. Its source takes one of three types. base64 embeds the bytes and needs a media_type. url points at a hosted image. file refers to something already uploaded to the Files API. The supported formats are image/jpeg, image/png, image/gif and image/webp. Put the image block before the text that asks about it, as in this example.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": image_media_type,
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)

Statelessness is what makes inline images expensive. Suppose a support tool sends two screenshots in turn 1 and asks about "the first image" in turn 3. Those screenshots have to be in the turn 3 request, so a base64 image is re-encoded and re-sent every turn. The Files API avoids that: upload once, get back a file_id, and from then on each request refers to the file by ID. The history still has to include the image, but now as a short reference. The same upload works for documents such as PDFs, and files can be listed, retrieved and deleted.

uploaded = client.files.upload(
    file=("document.pdf", open("/path/to/document.pdf", "rb"), "application/pdf"),
)
file_id = uploaded.id
print(file_id)

Sources17

6.What changes when you call Claude through a cloud vendor

Which platform you buy Claude through is a decision about [data residency and platform choice](lesson:2.1). Once that is decided, your request code changes in specific ways. On Google Cloud's Agent Platform the body looks almost the same as a Messages API request, with two changes. The model moves out of the body and into the endpoint URL. The API version moves into the body as anthropic_version.

Model IDs also differ by platform. On Amazon Bedrock, for the models covered by its Opus 4.6-and-earlier guide, you pass an inference profile instead of the base model ID: a regional prefix plus the Bedrock ID, such as us.anthropic.claude-sonnet-4-5-20250929-v1:0, or the full inference-profile ARN. Model availability varies by region, and lifecycle dates on partner platforms are set by the partner, so the retirement date on Bedrock or Google Cloud can differ from the Claude API's. Some feature behaviour changes too. Prompt caches are isolated per workspace on the Claude API but per organization on Bedrock and Google Cloud.

The SDK client and the authentication change with the platform as well. For Bedrock models in the Opus 4.6-and-earlier guide, install anthropic[bedrock] and use AnthropicBedrock: it takes AWS keys or the default AWS credential providers, or a bearer token through the AWS_BEARER_TOKEN_BEDROCK environment variable. Opus 4.7 and later models run on Claude in Amazon Bedrock instead, through AnthropicBedrockMantle, which resolves credentials by the standard AWS precedence and uses IDs with an anthropic. prefix, such as anthropic.claude-opus-5-5. On Google Cloud, AnthropicVertex takes a project_id and a region, where global gives dynamic routing for maximum availability. Authenticate first, usually with gcloud auth application-default login.

Sources89104

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Once Claude has seen an image or document in an earlier turn, a later turn can refer to it without including it again.Why is that wrong?

   The API keeps nothing between calls. The image, or a file_id reference to it, has to be in the history of every request that relies on it.

   Covered in Conversation state lives in your code

2. 2.Thinking blocks are just display text, so a tool loop can drop them or keep only the tool_use blocks when it sends the assistant turn back.Why is that wrong?

   The thinking blocks have to go back complete, signatures included. Edited, reordered or partly dropped thinking blocks are rejected with a 400.

   Covered in Tool calls and thinking blocks in the request loop

3. 3.Each input_json_delta in a streamed tool_use block is a complete JSON object you can parse right away.Why is that wrong?

   The deltas are fragments of a JSON string. Collect them and parse at content_block_stop, or use the SDK's streaming helpers.

   Covered in Streaming responses as server-sent events