PART 7 · MODULE 2Messages, streaming & caching
Claude API & SDKs
Messages API, extended thinking, prompt caching, structured outputs, batch processing, and SDKs
Loading module...
Messages API, extended thinking, prompt caching, structured outputs, batch processing, and SDKs
The Anthropic API is the programmatic interface to every Claude model. Whether you are building a chatbot, a document-processing pipeline, or an autonomous agent, understanding the Messages API, streaming, extended thinking, and caching primitives is non-negotiable for the Claude Certified Architect (CCA) exam.
All inference goes through a single endpoint: POST /v1/messages. You send a model identifier, a system prompt, a messages array with alternating user / assistant roles, and a max_tokens cap.
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": "You are a concise technical assistant.",
"messages": [
{
"role": "user",
"content": "Explain the CAP theorem in three sentences."
}
]
}{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{
"type": "text",
"text": "The CAP theorem states that a distributed system ..."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 28,
"output_tokens": 92
}
}For multi-turn, append the assistant reply to your messages array and add the next user turn. Roles must alternate — two consecutive user messages will be rejected. The API is stateless; you re-send the full history each call.
Flagship model. Best reasoning, coding, and analysis. Supports a 14.5-hour autonomous task horizon — the longest of any model.
claude-opus-4-6
Balanced speed and intelligence. Same price as Sonnet 4.5 with meaningfully better performance across benchmarks.
claude-sonnet-4-6
Fast and efficient. Roughly 1/3 the cost of Sonnet and 2x the speed. Ideal for classification, extraction, and routing.
claude-haiku-4-5-20251001
All models support text + image input, 200K context window, and are multilingual.
Set "stream": true to receive Server-Sent Events (SSE) as the response is generated. This lets you render tokens in real time instead of waiting for the full completion.
{
"model": "claude-sonnet-4-6",
"max_tokens": 512,
"stream": true,
"messages": [
{ "role": "user", "content": "Write a haiku about APIs." }
]
}Extended thinking gives Claude a private scratch-pad to reason step-by-step before producing a visible answer. Two modes are available:
Claude decides when and how much to think based on task complexity. Controlled by the effort parameter (low, medium, high).
Claude always thinks. You set a budget_tokens cap for the thinking block. More predictable but less token-efficient for simple tasks.
{
"model": "claude-opus-4-6",
"max_tokens": 16000,
"thinking": {
"type": "adaptive",
"effort": "high"
},
"messages": [
{
"role": "user",
"content": "Design a distributed rate-limiter that handles 1M RPM across 50 regions."
}
]
}Prompt caching lets you mark content blocks as cacheable so repeated prefixes (system prompts, few-shot examples, large documents) are stored and reused across requests. This cuts latency and cost dramatically.
1.25x base input price
0.1x base input price (90% savings)
5 min default, 1-hour option available
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are a legal analyst. Here is the full contract text: ...(50,000 tokens)...",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [
{ "role": "user", "content": "Summarize the indemnification clauses." }
]
}The Message Batches API lets you submit up to thousands of requests in a single call for asynchronous processing at 50% cost savings vs. individual requests. Most batches complete in under one hour.
POST /v1/messages/batches
{
"requests": [
{
"custom_id": "doc-001",
"params": {
"model": "claude-haiku-4-5-20251001",
"max_tokens": 256,
"messages": [
{ "role": "user", "content": "Extract the invoice total from: ..." }
]
}
},
{
"custom_id": "doc-002",
"params": {
"model": "claude-haiku-4-5-20251001",
"max_tokens": 256,
"messages": [
{ "role": "user", "content": "Extract the invoice total from: ..." }
]
}
}
]
}A token is roughly 4 characters or 0.75 words. Anthropic provides a free POST /v1/messages/count_tokens endpoint to measure exact token counts before sending a request.
Two complementary mechanisms guarantee valid JSON from Claude:
Set output_config.format to constrain the response to valid JSON matching a provided schema.
Add "strict": true on a tool definition. The schema is compiled to a constrained grammar and cached for 24 hours.
{
"model": "claude-sonnet-4-6",
"max_tokens": 512,
"output_config": {
"format": {
"type": "json_schema",
"json_schema": {
"name": "sentiment",
"schema": {
"type": "object",
"properties": {
"label": { "type": "string", "enum": ["positive", "negative", "neutral"] },
"confidence": { "type": "number" }
},
"required": ["label", "confidence"]
}
}
}
},
"messages": [
{ "role": "user", "content": "Classify: 'This product is amazing!'" }
]
}{
"model": "claude-sonnet-4-6",
"max_tokens": 512,
"tools": [
{
"name": "extract_entities",
"description": "Extract named entities from text.",
"strict": true,
"input_schema": {
"type": "object",
"properties": {
"people": { "type": "array", "items": { "type": "string" } },
"locations": { "type": "array", "items": { "type": "string" } }
},
"required": ["people", "locations"]
}
}
],
"tool_choice": { "type": "tool", "name": "extract_entities" },
"messages": [
{ "role": "user", "content": "Alice met Bob in Paris last Tuesday." }
]
}Supported types: object, array, string, number, boolean, null, enum, const, $ref.
Upload files once and reference them across multiple requests without re-uploading. Supports PDF, DOCX, TXT, CSV, Excel, and images up to 500 MB per file.
import anthropic
client = anthropic.Anthropic()
# Upload once
uploaded = client.files.create(
file=open("contract.pdf", "rb"),
purpose="messages",
)
# Reference in any request
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
messages=[{
"role": "user",
"content": [
{
"type": "document",
"source": {
"type": "file",
"file_id": uploaded.id,
},
},
{
"type": "text",
"text": "Summarize the key obligations in this contract.",
},
],
}],
)Document content blocks support citations — Claude can reference exact page numbers and passages from uploaded PDFs.
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"stop_sequences": ["</answer>", "---END---"],
"messages": [
{
"role": "user",
"content": "Give your answer inside <answer> tags."
}
]
}Custom stop sequences let you terminate generation at a precise boundary, saving tokens and cost.
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY env var
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "What is the capital of France?"}
],
)
print(message.content[0].text)import anthropic
import asyncio
async def main():
client = anthropic.AsyncAnthropic()
async with client.messages.stream(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "Explain monads simply."}],
) as stream:
async for text in stream.text_stream:
print(text, end="", flush=True)
asyncio.run(main())import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic(); // reads ANTHROPIC_API_KEY env var
const message = await client.messages.create({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [
{ role: "user", content: "Explain the actor model." },
],
});
console.log(message.content[0].text);import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
try {
const stream = client.messages.stream({
model: "claude-sonnet-4-6",
max_tokens: 1024,
messages: [{ role: "user", content: "Write a limerick." }],
});
for await (const event of stream) {
if (event.type === "content_block_delta" &&
event.delta.type === "text_delta") {
process.stdout.write(event.delta.text);
}
}
} catch (err) {
if (err instanceof Anthropic.APIError) {
console.error(`API error ${err.status}: ${err.message}`);
}
}Both SDKs include automatic retries with exponential backoff, type-safe request/response objects, and first-class streaming support. The Python SDK also exposes AsyncAnthropic for async/await.
All Claude models accept images inline via base64 or URL. Supported formats: JPEG, PNG, GIF, WebP.
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": "<base64-encoded-image>"
}
},
{
"type": "text",
"text": "Describe what you see in this diagram."
}
]
}]
}PDFs are sent as document content blocks. Claude performs both text extraction and visual understanding of each page. With the Files API, you can upload a PDF once and reference it across requests. Citations from specific pages and passages are supported.
Claude is trained with CAI — a framework where the model critiques and revises its own outputs against a set of principles. This produces helpfulness with built-in safety alignment.
Separate classifiers screen both prompts and responses. Anthropic reports a 95% attack blocking rate across standard jailbreak benchmarks.
Anthropic follows a tiered AI Safety Level (ASL) framework. Each ASL defines capability thresholds and required safety measures before a model can be deployed. Usage policy categories govern prohibited content types.
Computer use lets Claude interact with desktop environments — clicking, typing, scrolling, and reading screenshots in an agentic loop.
{
"model": "claude-sonnet-4-6",
"max_tokens": 4096,
"tools": [
{
"type": "computer_20250124",
"name": "computer",
"display_width_px": 1920,
"display_height_px": 1080,
"display_number": 1
}
],
"messages": [
{
"role": "user",
"content": "Open Firefox and navigate to anthropic.com"
}
]
}