Request parameters, in full

1 · One endpoint, many knobs essential

Almost everything you do with Claude goes through a single call: client.messages.create(...). Tools, vision, streaming, thinking, structured output — none of them are separate APIs. They are all parameters on this one call. Learn the parameters once and the whole surface opens up.

This lesson is a reference. Earlier lessons showed you the parameters you needed in the moment (a model here, a max_tokens there); this one lays every parameter out in a single place, with its default, what it actually changes, and when — if ever — you should touch it. Read it once end to end, then come back to the big table whenever you're unsure.

There are only three required parameters — model, max_tokens, and messages. Everything else has a sensible default, and the single most common mistake is over-configuring: setting knobs you don't understand and making the model worse. The mental model to carry through this lesson: the defaults are good — change them deliberately, one at a time, with a reason.

2 · The parameter groups essential

The parameters fall into five natural groups. Hold this shape in your head and every specific parameter has a home:

Required is the minimum any call needs. Prompt shaping is where your actual instructions and conversation live. Sampling tunes how the model picks the next token. Tools let the model call functions. Operational knobs govern delivery, reasoning, and billing rather than the content of the answer. The reference table in §3 uses these same groups.

3 · The full reference table essential

Every parameter of messages.create, its default, what it does, and when you'd actually reach for it. Bookmark this section.

4 · Required + prompt shaping — model, max_tokens, messages, system essential

These are the parameters you set on essentially every call. model and max_tokens are scalars; the interesting shape is in messages and system.

messages is a list of turns. Each turn has a role ("user" or "assistant") and content. Content can be a plain string, or — when you need images, documents, or tool results — a list of content blocks ({"type": "text", ...}, {"type": "image", ...}, and so on). system is separate from messages: it's top-level instructions, given as a string, or as a list of text blocks when you want to attach cache_control to cache a large stable prompt.

required.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes a real API call
import anthropic

client = anthropic.Anthropic()          # reads ANTHROPIC_API_KEY from the environment

resp = client.messages.create(
    model="claude-opus-4-8",            # REQUIRED: which model answers
    max_tokens=1024,                    # REQUIRED: hard cap on output tokens
    system=[                            # top-level instructions (list form → cacheable)
        {
            "type": "text",
            "text": "You are a terse DevOps assistant. Answer in one sentence.",
            "cache_control": {"type": "ephemeral"},   # cache this stable prefix
        }
    ],
    messages=[                          # REQUIRED: the conversation
        {"role": "user", "content": "What does 'kubectl get pods' show?"},
        # content can also be a LIST of blocks, e.g. text + an image:
        # {"role": "user", "content": [
        #     {"type": "text", "text": "What's in this screenshot?"},
        #     {"type": "image", "source": {"type": "url", "url": "https://.../shot.png"}},
        # ]},
    ],
)

# content is a LIST of blocks — read only the text ones
print(next((b.text for b in resp.content if b.type == "text"), ""))

5 · Recipe — temperature vs top_p (and stop_sequences) intermediate

Sampling parameters change how the model chooses each next token. The two you'll meet most are temperature and top_p, and the golden rule is: set at most one of them. They're two different ways to control the same thing (randomness), and steering with both at once is confusing and unnecessary — Anthropic recommends adjusting temperature and leaving top_p alone.

temperature ranges 0 to 1. Near 0 the model almost always picks the most likely token — good for extraction, classification, and anything you want reproducible-ish. At 1 (the default) it samples across the full distribution — good for brainstorming and prose. stop_sequences is unrelated to randomness: it's a list of strings that, when the model generates one, cut the response off immediately (the stop string itself is not returned). When that happens, stop_reason is "stop_sequence" and stop_sequence tells you which one fired.

sampling.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes a real API call
import anthropic

client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=256,
    temperature=0,                      # near-deterministic: extraction / classification
    # top_p=0.9,                        # DON'T also set this — pick ONE knob, not both
    stop_sequences=["\n\nEND"],       # stop the moment the model writes this marker
    system="Extract the error code. Output only the code, then write \n\nEND.",
    messages=[{"role": "user",
               "content": "Log: FATAL 2026-09-06 db timeout code=E5521 retry=3"}],
)

text = next((b.text for b in resp.content if b.type == "text"), "")
print("text:", repr(text))
print("stop_reason:", resp.stop_reason)      # "stop_sequence" if the marker fired
print("stop_sequence:", resp.stop_sequence)  # which sequence caused the stop

6 · Recipe — tools & tool_choice (force / allow / forbid) intermediate

tools is a list of tool definitions (each a name, a description, and a JSON-schema for its input). tool_choice controls whether and which tool the model uses. It has four modes:

Any of these can also carry "disable_parallel_tool_use": true to force at most one tool call per turn (by default the model may request several at once). Here is a forced tool call — useful when you want structured extraction and you know the model should always fill in this one tool:

tool_choice.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes a real API call
import anthropic

client = anthropic.Anthropic()

record_incident = {
    "name": "record_incident",
    "description": "Record a parsed incident from an alert line.",
    "input_schema": {
        "type": "object",
        "properties": {
            "service": {"type": "string"},
            "severity": {"type": "string", "enum": ["low", "high", "critical"]},
        },
        "required": ["service", "severity"],
    },
}

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=512,
    tools=[record_incident],
    # FORCE this exact tool + at most one call this turn:
    tool_choice={"type": "tool", "name": "record_incident",
                 "disable_parallel_tool_use": True},
    messages=[{"role": "user",
               "content": "CRITICAL checkout-api is down, 500s everywhere"}],
)

# a forced tool means stop_reason == "tool_use" and a tool_use block with the args
tool_use = next((b for b in resp.content if b.type == "tool_use"), None)
print(resp.stop_reason)          # "tool_use"
print(tool_use.name, tool_use.input)   # record_incident {'service': 'checkout-api', ...}

7 · Recipe — extended thinking advanced

Extended thinking lets the model reason privately before it answers — a real lever on hard, multi-step problems (planning, tricky debugging, math). On current models you turn it on with adaptive thinking, where the model itself decides how much to think, and you tune the overall depth with output_config.effort.

Two accuracy points that trip people up. First, on Opus 4.8 / 4.7 the old {"type": "enabled", "budget_tokens": N} form is gone — it returns a 400. Use {"type": "adaptive"}. Second, thinking runs at temperature=1 — you cannot combine extended thinking with a lowered temperature (or with top_p/top_k); those sampling params are incompatible with thinking. So the recipe is: turn thinking on, leave sampling alone.

thinking.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes a real API call
import anthropic

client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=8000,
    thinking={"type": "adaptive", "display": "summarized"},  # model decides how much
    output_config={"effort": "high"},   # low | medium | high | max  — the depth dial
    # NOTE: do NOT also set temperature / top_p / top_k here — thinking runs at
    # temperature=1 and rejects those sampling params.
    messages=[{"role": "user",
               "content": "Plan a zero-downtime Postgres major-version upgrade."}],
)

for block in resp.content:
    if block.type == "thinking":
        print("[thinking]", block.thinking[:80], "...")
    elif block.type == "text":
        print("[answer]", block.text)

8 · Validate before you send (this one runs offline) professional

Most parameter mistakes are catchable before you spend a request: both temperature and top_p set, a max_tokens that exceeds the model's output cap, or extended thinking combined with a non-default temperature. The helper below is pure stdlib — no API key, no network — and runs with a plain python file.py. It inspects a params dict and returns a list of warnings, so you can lint your call sites in a test.

validate_params.py# Catch the common messages.create mistakes locally, before spending a request.
# Model output caps as of this writing (verify current values in the docs):
MODEL_MAX_OUTPUT = {
    "claude-opus-4-8": 128_000,
    "claude-sonnet-4-6": 64_000,
    "claude-haiku-4-5": 64_000,
}


def validate_params(params):
    """Return a list of human-readable warnings for a messages.create params dict.
    Pure stdlib; does not call the API."""
    warnings = []
    model = params.get("model")
    if not model:
        warnings.append("model is REQUIRED and missing")
    if "max_tokens" not in params:
        warnings.append("max_tokens is REQUIRED and missing")
    if not params.get("messages"):
        warnings.append("messages is REQUIRED and empty/missing")

    # don't set both temperature and top_p
    if "temperature" in params and "top_p" in params:
        warnings.append("both temperature and top_p set — pick ONE, not both")

    # max_tokens must fit the model's output cap
    cap = MODEL_MAX_OUTPUT.get(model)
    mt = params.get("max_tokens")
    if cap is not None and isinstance(mt, int) and mt > cap:
        warnings.append(f"max_tokens={mt} exceeds {model} output cap of {cap}")

    # extended thinking requires temperature == 1 (i.e. leave it unset)
    thinking = params.get("thinking")
    thinking_on = isinstance(thinking, dict) and thinking.get("type") in ("adaptive", "enabled")
    if thinking_on and params.get("temperature", 1) != 1:
        warnings.append("thinking is on but temperature != 1 — thinking runs at temperature=1")
    if thinking_on and ("top_p" in params or "top_k" in params):
        warnings.append("thinking is on but top_p/top_k set — incompatible with thinking")

    return warnings


bad = {
    "model": "claude-opus-4-8",
    "max_tokens": 200_000,          # over the 128K cap
    "messages": [{"role": "user", "content": "hi"}],
    "temperature": 0.2,             # both temperature ...
    "top_p": 0.9,                   # ... and top_p
    "thinking": {"type": "adaptive"},  # thinking on, but temperature != 1
}
for w in validate_params(bad):
    print("WARN:", w)
print("ok:", validate_params({
    "model": "claude-opus-4-8", "max_tokens": 1024,
    "messages": [{"role": "user", "content": "hi"}],
}))

WARN: both temperature and top_p set — pick ONE, not both
WARN: max_tokens=200000 exceeds claude-opus-4-8 output cap of 128000
WARN: thinking is on but temperature != 1 — thinking runs at temperature=1
WARN: thinking is on but top_p/top_k set — incompatible with thinking
ok: []

9 · Tech-lead — operational knobs & a house policy tech-lead

The last group of parameters doesn't change what the model says — it changes how the request is delivered, tracked, and billed. A lead sets a house policy for these so every call site is consistent:

Operational parameter policy

1. stream for anything interactive or large. Streaming isn't just UX — it's how you avoid HTTP timeouts on big max_tokens calls. Policy: stream any user-facing response and any call with max_tokens above ~16K; use .get_final_message() to still get the assembled reply and usage.
2. metadata.user_id on every production call. Attach a stable, hashed per-end-user identifier (never raw PII) so abuse and rate-limit issues can be traced to a tenant. It costs nothing and it's the field support will ask you for.
3. thinking + effort by route, not globally. Turn thinking on for the hard routes (planning, debugging) and leave it off for lookups and classification. Standardise the effort level per route so cost is predictable.
4. service_tier only if you have an arrangement. It requests a priority / standard / batch service level; the exact accepted values and behaviour evolve, so treat it as opt-in and verify the current options in the docs before wiring it in.
5. betas deliberately, never by default. Beta features live on client.beta.messages with an explicit flag string. Pin the flag, document why you need it, and plan to remove it when the feature goes GA — don't leave stale beta headers scattered across the codebase.
6. Centralise the defaults. Wrap messages.create in one thin house function that fills model, sane max_tokens, metadata, and the streaming decision. Then validate_params from §8 runs in that one place.

The through-line: the content parameters (messages, system, tools) are per-request and belong to the feature; the operational parameters (stream, metadata, service_tier, betas) are cross-cutting and belong to the platform. Put the second set behind one wrapper and every engineer inherits the house policy for free.

import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-sonnet-4-6",   # required
    max_tokens=256,               # required: hard cap on output
    messages=[{"role": "user", "content": "Define idempotency."}],  # required
)
# system is optional: with no role/rules given, the model uses its defaults.
print(resp.content[0].text)

import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=64,
    temperature=0,           # focused, repeatable; do NOT also set top_p
    stop_sequences=["\n\n"],  # stop at first blank line
    messages=[{"role": "user", "content": "Extract the year: Founded in 1994."}],
)
print(resp.content[0].text, resp.stop_reason)

import anthropic
client = anthropic.Anthropic()

tools = [{
    "name": "record_temp",
    "description": "Record a temperature reading.",
    "input_schema": {"type": "object",
        "properties": {"celsius": {"type": "number"}},
        "required": ["celsius"]},
}]
resp = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=256, tools=tools,
    tool_choice={"type": "tool", "name": "record_temp"},
    messages=[{"role": "user", "content": "It is 21 degrees C."}],
)
# stop_reason == 'tool_use' -> the args are in a tool_use block:
for block in resp.content:
    if block.type == "tool_use":
        print(block.input)   # {'celsius': 21}

import anthropic
client = anthropic.Anthropic()

resp = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=2048,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "high"},   # low | medium | high | max
    # NOTE: with thinking on, do NOT pass temperature/top_p/top_k -> 400.
    messages=[{"role": "user", "content": "Prove sqrt(2) is irrational."}],
)
for b in resp.content:
    if b.type == "text":
        print(b.text)

def validate_params(p, model_cap):
    warns = []
    if "temperature" in p and "top_p" in p:
        warns.append("set temperature OR top_p, not both")
    if p.get("max_tokens", 0) > model_cap:
        warns.append(f"max_tokens {p['max_tokens']} > cap {model_cap}")
    if p.get("thinking") and p.get("temperature", 1) != 1:
        warns.append("thinking requires temperature=1 (drop it)")
    for k in ("model", "max_tokens", "messages"):
        if k not in p:
            warns.append(f"missing required param: {k}")
    return warns

bad = {"model": "claude-opus-4-8", "max_tokens": 200000,
       "messages": [], "temperature": 0.3, "top_p": 0.9}
print(validate_params(bad, model_cap=128000))

CAPS = {"claude-opus-4-8": 128000, "claude-sonnet-4-6": 64000,
        "claude-haiku-4-5": 64000}

def house_policy(p):
    p = dict(p)
    cap = CAPS.get(p["model"], 4096)
    p.setdefault("max_tokens", 1024)
    p["max_tokens"] = min(p["max_tokens"], cap)      # never exceed the cap
    if "temperature" in p:
        p.pop("top_p", None)                          # one sampling knob
    md = p.setdefault("metadata", {})
    if "user_id" not in md:
        raise ValueError("metadata.user_id required for abuse tracking")
    return p

out = house_policy({"model": "claude-sonnet-4-6", "max_tokens": 999999,
                    "temperature": 0.2, "top_p": 0.8,
                    "metadata": {"user_id": "u-42"}})
print(out["max_tokens"], "top_p" in out)   # 64000 False

Knowledge check check yourself