Claude API Request Body Parameters Explained

When you send a request to Claude's Messages API, the JSON body you build controls everything about the response: which model answers, how creative it is, how long it can talk, and whether it can call tools. If you've opened the docs and felt overwhelmed by the list of fields, this article walks through every parameter you're likely to use, what it does, and when to change it from the default.

The short version: model and messages are required, everything else is optional and exists to shape behavior — length limits, randomness, system instructions, tool access, and streaming. Below is a field-by-field breakdown with practical defaults.

The required fields

model

A string identifying which Claude model handles the request, for example claude-opus-4 or claude-sonnet-4. Different models trade speed and cost for reasoning quality. Pick the smallest model that reliably solves your task — most production apps use a mid-tier model for everyday requests and reserve the largest model for complex reasoning or long-context work.

messages

An array of conversation turns, each with a role (user or assistant) and content. Content can be a plain string or an array of content blocks (text, images, tool results). The array must start with a user message, and roles typically alternate:

{
  "messages": [
    { "role": "user", "content": "Summarize this changelog in two sentences." }
  ]
}

For multi-turn conversations, you resend the full history each time — the API is stateless. Your application is responsible for storing and replaying prior turns.

Parameters that shape the response

max_tokens

Required by the raw Anthropic API, and the single most common source of truncated answers. It caps how many tokens the model can generate in its reply — not the input size. If you set it too low, Claude's response gets cut off mid-sentence. For short answers, 256–512 is usually enough; for long-form generation (articles, code files), push it to 2000–4000 depending on the model's limit.

temperature

A float between 0 and 1 controlling randomness. Lower values (0–0.3) produce consistent, deterministic output — ideal for classification, extraction, or anything with a "correct" answer. Higher values (0.7–1) produce more varied, creative output — useful for brainstorming or copywriting. If you're not sure, leave it at the default and adjust only after seeing real outputs.

top_p and top_k

Alternative sampling controls. top_p restricts the model to tokens whose cumulative probability mass is below a threshold (nucleus sampling); top_k restricts it to the k most likely next tokens. Most developers never touch these — temperature alone is enough for 95% of use cases. Combining all three sampling parameters rarely helps and can make output harder to reason about.

stop_sequences

An array of strings that, if generated, immediately halt the response. Useful when you want Claude to stop right before a delimiter you control, e.g. stopping generation at "\n\nUser:" so it doesn't hallucinate the next turn of a conversation you're simulating.

Instructions and context

system

A string (or content block array) of instructions that apply to the whole conversation but aren't part of the message history — role, tone, constraints, output format. Keep it as a separate field rather than stuffing instructions into the first user message; it's processed differently and tends to be followed more reliably:

{
  "system": "You are a strict JSON-only API. Never include explanations.",
  "messages": [{ "role": "user", "content": "List three colors." }]
}

metadata

An object for passing non-prompt data, most commonly a user_id field for abuse monitoring on Anthropic's side. It doesn't affect the model's output.

Streaming and tools

stream

A boolean. Set to true to receive the response as server-sent events instead of a single JSON blob, token by token, so you can render output as it's generated. This matters for chat UIs where perceived latency is everything — users see the first words almost immediately instead of waiting for the full generation.

tools and tool_choice

tools is an array of function definitions Claude can call — each with a name, description, and JSON Schema input_schema. tool_choice controls whether Claude must use a specific tool, any tool, or decide on its own (auto, the default). This is how you connect Claude to databases, internal APIs, or calculators: Claude returns a tool_use block instead of plain text, your code executes it, and you send the result back as a tool_result content block in the next request.

stop_reason (response field, not a request parameter)

Worth knowing even though it's on the response, not the request: it tells you why generation stopped — end_turn, max_tokens, stop_sequence, or tool_use. Checking this field is the easiest way to detect truncated responses caused by a max_tokens value set too low.

Putting it together

A realistic request combining the common parameters looks like this:

{
  "model": "claude-sonnet-4",
  "max_tokens": 1024,
  "temperature": 0.3,
  "system": "You are a concise technical writer.",
  "messages": [
    { "role": "user", "content": "Explain what idempotency means in API design." }
  ],
  "stream": false
}

If you're calling Claude through SubToAPI, the request body is identical to the raw Anthropic format — same field names, same structure — so you're not learning a second API surface. You just point your HTTPS requests at https://api.subtoapi.app/v1/messages with an Authorization: Bearer $SUBTOAPI_KEY header instead of managing Anthropic credentials directly, and you get usage metadata and team seats on top. See the quickstart and messages reference for the exact payload shape, streaming for SSE handling, and tools for function-calling schemas.

questions

What happens if I omit max_tokens? The raw Anthropic API requires it — omitting it returns an error. There's no "unlimited" option; you must pick an upper bound for the response length.

Does changing temperature affect token usage or cost? No. temperature only changes sampling randomness, not how many tokens are generated or billed. Cost depends on max_tokens, the actual length of the reply, and input size.

Can I send images in the messages array? Yes. Use a content block array with a type: "image" object (base64-encoded or referenced) alongside text blocks, instead of a plain string, in any user message.