Claude Messages API: Request Shape, Conversation State, Vision and Streaming

1.One request in, one Message out

A basic Messages API call has three parts: a model, a max_tokens cap, and a messages list of turns, each with a role and some content. The reply is a Message object. It has an id, role: "assistant", a content array of typed blocks, the model that served the request, a stop_reason, and a usage object that counts input and output tokens.

{
  "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
  }
}

content is an array, not a string, because one reply can hold several blocks: text here, and elsewhere tool_use or thinking blocks, which the streaming section covers. stop_reason tells you why generation ended. "end_turn" means Claude finished naturally. "max_tokens" means the cap cut the reply off, which is sometimes intended. A refusal comes back as stop_reason: "refusal" with a stop_details object that names the policy category behind it.

Sources1

2.Conversation state is yours to carry

Since the API is stateless, a multi-turn conversation is a list your application keeps and resends in full each time. This is the main data access pattern of the Messages API. Nothing on the server lets a follow-up request refer back to an earlier one, so persisting, trimming and replaying the transcript are all up to you. Earlier assistant turns also don't have to come from Claude. You can write synthetic assistant messages to set up a conversation.

Instructions that apply from the first turn go in the top-level system field. On Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 4.8 and Claude Opus 5, you can also add a "role": "system" message after a user turn to bring in a new instruction partway through. It has the same authority as the top-level field. It cannot be the first entry in messages. Because it is appended at the end, it does not invalidate the cached prefix before it.

Sources1

3.Sending images: three source types

Images go into a user turn as image content blocks, next to text blocks. Supported media types are image/jpeg, image/png, image/gif and image/webp. Vision also works in claude.ai and in the Claude Console Playground, but on the API the choice that matters is where the image bytes come from:

One request can hold several images, and Claude analyses them together, which suits comparisons or a series of document pages. The docs recommend putting a short text label before each image (Image 1:, Image 2:) so you and later turns can refer to them by name. Combine this with statelessness: a follow-up that mentions "Image 1" only works if the earlier turn containing that image is still in the history you resend. The Files API makes resending cheap, because the history holds a file_id reference instead of the base64 data again.

Sources12

4.Streaming: events, tool input and thinking

Set "stream": true and the reply arrives as server-sent events (SSE). The Python and TypeScript SDKs wrap this for you:

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-opus-5-5",
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Streaming also matters when you don't show partial output. With large max_tokens values the SDKs require streaming to avoid HTTP timeouts. .get_final_message() (Python) or .finalMessage() (TypeScript) streams internally and returns the same complete Message that .create() would. The raw event order is: message_start (a Message with empty content), then for each content block a content_block_start, one or more content_block_delta events and a content_block_stop, then one or more message_delta events and a final message_stop. Each block's index matches its position in the final content array. There can be ping events at any point. Errors can also arrive inside the stream, for example an overloaded_error that would be an HTTP 529 in a non-streaming call. New event types may be added, so your parser should ignore types it doesn't recognise.

Tool calls need care when streamed. The deltas for a tool_use block are partial JSON strings, while the final tool_use.input is always an object. Collect the fragments and parse them when content_block_stop arrives, or use the SDK helpers that give you parsed values as they build up. Current models emit one complete key and value at a time, so there can be pauses between events while a tool call is being written. Thinking blocks stream as thinking_delta events and close with a signature_delta, which verifies the block's integrity. With display: "omitted", no thinking text is streamed: the block receives one empty thinking_delta and a signature, then closes.

Sources3

Exam traps

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

1. 1.After the first request, the API remembers the conversation, so a follow-up only needs to send the new user message.Why is that wrong?

   The API is stateless. Each request must contain the full history you want Claude to consider, and your application stores it.

   Covered in Conversation state is yours to carry

2. 2.Once Claude has seen an image in an earlier turn, a later request can refer to 'the first image' without including it again.Why is that wrong?

   The earlier turn, with its image, has to be in the resent history. To avoid re-encoding it, upload it to the Files API and reference the file_id in each turn.

   Covered in Sending images: three source types

3. 3.Each input_json_delta for a tool call is a JSON object you can parse on its own.Why is that wrong?

   The deltas are fragments of a JSON string. Only the collected result, the final tool_use.input, is an object, so parse after content_block_stop or use the SDK helpers.

   Covered in Streaming: events, tool input and thinking