Anthropic

Haiku, Sonnet and Opus are Anthropic's three Claude size tiers, ordered smallest to largest. Haiku is the fastest and cheapest, Opus is the most capable and most expensive, and Sonnet sits between them. All three are called through the same Messages API.

Send a top-level tools array on the Messages request. Each entry needs a name, a description that tells Claude when to call it, and an input_schema: a JSON Schema object describing the parameters.

Set the user message content to an array of blocks and add an image block next to your text block. The image block carries a source object that is either base64 (with media_type and data) or a url. Image blocks belong in user turns.

max_tokens is a hard ceiling on the tokens Claude generates in that one response, including any thinking tokens. It is required on every Messages API request, and hitting it truncates the output mid-stream with stop_reason "max_tokens".

messages is a non-empty array of turns, each with a role of user or assistant, starting with user and alternating. Each turn's content is either a plain string or an array of typed content blocks. The endpoint is stateless, so you resend the full history every call.

Anthropic prices each Claude model per million tokens, with input and output billed at separate rates and output costing several times more than input. Rates climb from Haiku to Sonnet to Opus, so per-request cost depends on both the tier and the token mix.

Anthropic's prompt cache is prefix-based: a cache_control marker ends a cacheable prefix rather than caching one block. Put it after everything stable — tools first, then system, then early messages — and keep anything that varies per request after it.

Key a buffer by the event's index field and append each delta to that block. text_delta contributes its text; input_json_delta contributes a partial_json string fragment that you concatenate and parse as JSON only once the block's content_block_stop arrives.

An Anthropic stream opens with message_start, then for each content block a content_block_start, a run of content_block_delta chunks, and a content_block_stop. It closes with message_delta carrying the final stop_reason and output usage, then message_stop.

Four values: auto lets Claude decide (the default when tools are present), any forces at least one tool call, tool with a name forces that specific tool, and none forbids calling any tool. Each can also carry disable_parallel_tool_use.

Append the assistant's entire content array to messages, then add a new user message whose content holds a tool_result block. That block carries tool_use_id matching the call's id, plus the result content. Then call the API again.

Image cost scales with pixel area, not file size: Anthropic documents roughly width times height divided by 750 tokens. Oversized images are downscaled server-side first, so you pay for the resized version, capped by the model's resolution limit.

Treat it as a failed request even though bytes already reached the user. The HTTP 200 and headers are long gone, so surface the failure in your own stream protocol, keep or discard the partial text deliberately, and retry the whole call — there is no resume point.

The usage object reports cache_creation_input_tokens for tokens written to the cache on this call and cache_read_input_tokens for tokens served from it. A non-zero read count means a hit; input_tokens counts only the uncached remainder.

create(stream=True) returns a raw iterator of stream events that you assemble yourself. messages.stream() is a context manager returning a helper that accumulates the events for you, exposes a text-only iterator, hands back the finished message, and closes the HTTP response on exit.

Context window is not a tier ladder: the current Claude tiers share the same standard window, so moving from Haiku to Opus buys capability and not extra room. Extended long-context has been offered as a per-model opt-in with its own pricing, not as an Opus perk.

Anthropic cache entries live five minutes by default, and every hit refreshes that window. An optional one-hour TTL is requested with ttl inside cache_control. Writes cost a premium over base input price, reads a small fraction of it.

message_delta. It arrives after the last content block and carries delta.stop_reason, delta.stop_sequence, and a usage object with the message's output token count — none of which exist yet at message_start.

Four media types are accepted: image/jpeg, image/png, image/gif and image/webp. Each image may be up to 5 MB through the API, and a single request may carry up to 100 images. Base64 encoding inflates the payload by about a third.

Common values are end_turn, max_tokens, stop_sequence and tool_use, plus pause_turn, refusal and model_context_window_exceeded. Read stop_reason before touching the content array, because some outcomes return HTTP 200 with little or no content.

input_tokens counts everything the server read for that one request — system prompt, tool definitions and the entire resent message history — not just the newest user turn. output_tokens counts what the model generated in that response.

Split the pipeline into steps and assign a tier per step: small models for classification, extraction and routing, the large model for the one genuinely hard step. Prove each assignment with a held-out eval set, and cascade with escalation only when escalation stays rare.

Check the usage counters first: persistent cache_creation with zero cache_read means the prefix is either below the minimum cacheable size, changing between calls, expiring between calls, or routed to a different model. None of these raises an error.

Time the gap between events, not the whole request. Reset a watchdog on every frame including ping keepalives, and fail the stream when the idle gap exceeds your budget. A total wall-clock timeout kills legitimate long generations instead.

Because tool_choice applies to every request you send, and any forbids a plain-text answer. Each turn is therefore obliged to return a tool_use block, so a loop that exits on stop_reason leaving tool_use never exits. Force only the first turn.

Execute them all, then send every tool_result back in a single user message. Splitting them across separate user turns is invalid and teaches Claude to stop batching. A failed call still needs its block, marked is_error.

Put every image as its own block in the same user message content array, place them before the text that asks about them, and label them in the text so answers can refer to them unambiguously. Each image is tokenised and billed separately.

Choose a URL source when the image is already hosted somewhere Anthropic can reach and you want to keep bytes out of the request body. Choose base64 for private or locally generated images, and the Files API when the same image is reused across many calls.

Pin dated Claude snapshot identifiers in one config layer keyed by role, never as literals at call sites. Aliases float to newer snapshots and can change behaviour silently. Gate every migration on a held-out eval set, shadow real traffic, and keep the old identifier available for rollback.