Claude API Mechanics

1. The Messages API

Reasoning, tool use, vision, extended thinking—everything reaches your code through a single doorway: the Messages API, POST /v1/messages. Every request carries three mandatory headers: x-api-key, anthropic-version: 2023-06-01, and content-type: application/json (a fourth, anthropic-beta, is added for beta features).

Required top-level fields

A minimal, well-formed request:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "What is the capital of France?" }
  ]
}

The response's most important field is content—an array of content blocks, not a plain string:

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "The capital of France is Paris." }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 14,
    "output_tokens": 9,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

The stop_reason tells you why Claude stopped; usage reports token accounting. Because content is always an array, robust code never assumes content[0] is text—with thinking or tool use enabled, the first block may be a thinking or tool_use block. Always iterate and branch on each block's type.

Figure 5.1: Messages API request/response round-trip

System prompts vs. user/assistant messages

Here is the mistake that catches almost every newcomer. The system prompt is a top-level system parameter, not an entry in the messages array:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "system": "You are a terse assistant. Answer in one sentence.",
  "messages": [
    { "role": "user", "content": "Explain photosynthesis." }
  ]
}

The tempting error is to write {"role": "system", "content": "..."} inside messages[]. Think of the system parameter as the job description posted on the wall; messages is the transcript of the actual conversation. The system parameter accepts a plain string or an array of text blocks (the array form is needed for cache_control). Within messages, valid roles are user and assistant. Newer models such as Claude Opus 4.8 allow a model-gated mid-conversation system message; on models that don't support it, that entry returns a 400: role 'system' is not supported on this model. The rule to memorize: the primary system prompt is always the top-level system parameter.

Statelessness and multi-turn conversations

The Messages API is stateless—the server keeps no memory of prior calls. To hold a multi-turn conversation, you resend the full history on every request:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "My name is Alice." },
    { "role": "assistant", "content": "Nice to meet you, Alice." },
    { "role": "user", "content": "What's my name?" }
  ]
}

Three rules govern the array: (1) the first message must be user; (2) roles conventionally alternate; (3) content may be a plain string or an array of blocks (text, image, document, tool_use, tool_result, thinking, redacted_thinking). Because history is resent every turn, long conversations grow in cost—which is exactly why prompt caching matters.

2. Streaming and Realtime Behavior

By default a request blocks until Claude finishes, then returns the whole response at once. Streaming (stream: true, or an SDK helper such as client.messages.stream()) pushes the response back incrementally as Server-Sent Events—the server holds one HTTP connection open and emits small event:/data: chunks. The analogy: non-streaming is a next-day newspaper (complete, but you wait); streaming is a live commentator (each play as it happens).

The canonical event sequence

Figure 5.2: SSE streaming event sequence

The heart of the stream is content_block_delta, whose delta.type tells you the increment kind:

• text_delta — a chunk of visible text (in .text)
• input_json_delta — a chunk of a tool call's JSON input, streamed piecemeal
• thinking_delta — a chunk of extended-thinking reasoning (in .thinking)
• signature_delta — the cryptographic signature that closes a thinking block

Handling partial output

Because the response arrives in pieces, streaming code must accumulate. In practice you rarely hand-assemble deltas: SDK helpers (stream.get_final_message() in Python, stream.finalMessage() in TypeScript) reconstruct the complete Message object while still letting you render text as it arrives. Two cautions: a stream can be interrupted mid-flight (design your UI to tolerate partial responses), and you must track message_delta to capture the final stop_reason.

Realtime vs. batch tradeoffs

Realtime—streamed or one-shot—gives you an answer now, ideal for anything interactive. The Message Batches API (POST /v1/messages/batches) is the async alternative: submit up to 100,000 {custom_id, params} pairs, processed in the background at 50% of the standard token price. You poll processing_status until it reads "ended". Most batches finish within an hour (max 24h; results retained 29 days). Critically, results arrive in any order—key by custom_id, never position.

The essential exam point: there is no quality difference between batch and realtime—you trade latency for cost and throughput, nothing more.

3. Multi-Format Input and Vision

The content array is not limited to text. You compose multi-format input by mixing content blocks of different type values inside a single user message.

Figure 5.3: Composing a multi-format user message

An image block carries a source of one of three kinds: base64 (raw bytes + media_type, supported everywhere), url (a link Claude fetches), or file (a file_id from the Files API). A vision request:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "<base64-encoded bytes>"
          }
        },
        { "type": "text", "text": "What's in this image?" }
      ]
    }
  ]
}

Supported image formats: JPEG, PNG, GIF, WebP. Claude works best with image-then-text ordering. Documents use a document block with the same three source types; PDF support relies on vision (each page is processed as both text and image, inheriting vision's costs). Plain-text files (.txt, .csv, .md) work, but binary .xlsx/.docx are not supported.

Vision pricing and tiers

Claude views images in patches: each 28×28-pixel block equals one visual token, so an image costs roughly ⌈width/28⌉ × ⌈height/28⌉ tokens.

A 1000×1000 image costs about 1,296 tokens; a 1920×1080 image on the high-res tier costs roughly 2,691 tokens. Other limits: max 100 images per request on 200K-context models (600 on others), max 8000×8000 px, and up to 10 MB per image on the first-party API.

Thinking blocks in responses

When extended thinking is enabled, reasoning surfaces as thinking content blocks with three fields: type: "thinking", a thinking string, and a signature (an opaque, encrypted string the API uses to verify reasoning across turns). On current models you enable it with adaptive thinking—thinking: {"type": "adaptive"}. The older {"type": "enabled", "budget_tokens": N} form is removed and returns a 400. You control depth with output_config: {"effort": ...}, and a display sub-field controls visibility ("summarized" vs "omitted")—but display affects visibility only: you are billed for thinking tokens regardless.

{
  "model": "claude-opus-4-8",
  "max_tokens": 8000,
  "thinking": { "type": "adaptive", "display": "summarized" },
  "output_config": { "effort": "high" },
  "messages": [
    { "role": "user", "content": "Solve this step by step: 27 * 453" }
  ]
}

One rule you must not violate: in a multi-turn or tool-use conversation on the same model, you must pass thinking blocks back unchanged—echo [thinking_block, tool_use_block] in the assistant turn before returning your tool_result. Modifying a thinking block returns an invalid_request_error. Think of the signature as a wax seal: read the letter, but break the seal and the API won't accept it back.

4. Tools and Third-Party Access

Tool use in the Messages API

Tool use lets Claude call functions you define. You declare a tools array; each tool has a name, a description (Claude reads this to decide when to call it), and an input_schema (a JSON Schema object).

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather for a location.",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string", "description": "City name" }
        },
        "required": ["location"]
      }
    }
  ],
  "messages": [
    { "role": "user", "content": "What's the weather in Paris?" }
  ]
}

The tool-use loop is a conversation, not a single call:

1. Claude returns a tool_use block and stop_reason becomes "tool_use".
2. Your code executes the tool.
3. You send a new user message with a tool_result block whose tool_use_id matches step 1.
4. Claude reads the result and produces its final answer.

Figure 5.4: The tool_use / tool_result loop

You control tool selection with tool_choice: auto (default), any, tool (force a specific one), or none. When Claude requests several tools at once, execute them all and return all tool_result blocks in a single user message—splitting them silently trains Claude to stop making parallel calls. Anthropic also offers server-side tools (web search, web fetch, code execution) that run on its own infrastructure.

The stop_reason field is your loop's control signal:

stop_details is populated only when stop_reason == "refusal"; otherwise it is null, so guard before reading it.

Invoking Claude via Amazon Bedrock and Google Vertex AI

Two clouds host Claude, each with a dedicated SDK client class—you do not point the first-party client at a custom URL.

• Amazon Bedrock: the Mantle client (AnthropicBedrockMantle(aws_region="...")). Region is required. Model IDs take an anthropic. prefix (anthropic.claude-opus-4-8). Auth is AWS-native (SigV4 / IAM), not an API key.
• Google Vertex AI: AnthropicVertex(project_id="...", region="..."). Two args required: project_id and region (often "global"). Model IDs take no prefix (dated snapshots use an @ separator). Auth is GCP Application Default Credentials—no API key.

Feature parity is close but not total. Core Messages, streaming, tool use, extended thinking, PDF input, and explicit prompt caching work on both. Gaps: automatic prompt caching (first-party only; explicit cache_control still works), the Message Batches API, Files API, and Models API are first-party only; web fetch and code execution are unavailable on both; web search is Vertex-only in its basic variant.

Caching within API requests

Prompt caching stores a stable prefix so repeated calls don't re-process it. The mechanism is a prefix match: Claude renders your request as tools → system → messages, and any byte change anywhere in that prefix invalidates the cache from that point forward. Mark a breakpoint by attaching cache_control to the last block of a stable prefix:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "system": [
    {
      "type": "text",
      "text": "<large shared instructions / document>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "Summarize the key points." }
  ]
}

Default lifetime is 5 minutes (pass "ttl":"1h" for one hour). Up to 4 breakpoints per request; the minimum cacheable prefix is model-dependent (e.g. 4096 tokens on Opus 4.8). Verify with usage counters: cache_creation_input_tokens (tokens written, ~1.25× cost) and cache_read_input_tokens (tokens served, ~0.1× cost). If cache_read_input_tokens stays zero across identical-prefix requests, a silent invalidator is at work—an interpolated datetime.now()/UUID, unsorted JSON, or a changing tool set. Keep the prefix byte-identical.