Create a message

Body

modelstringYes

Model ID

messagesarrayYes

role is user / assistant. content is a string or an array of blocks (text, image, tool_use, tool_result, thinking, document)

systemstring | arrayNo

A string or an array of text blocks

temperaturenumberNo

0–1

top_pnumberNo

0–1

top_kintegerNo

Positive integer

stop_sequencesstring[]No

Up to 8

streambooleanNo

Defaults to false

toolsarrayNo

{name, description, input_schema}

tool_choiceobjectNo

{"type":"auto"|"any"|"none"} or {"type":"tool","name":"..."}

metadataobjectNo

{"user_id": "..."}

thinkingobjectNo

{"type":"enabled","budget_tokens":N} (N ≥ 1024) · {"type":"adaptive"} · {"type":"disabled"}

output_configobjectNo

effort (low–max, with adaptive or omitted thinking) · format ({"type":"json_schema","schema":{...}}, structured-output models only)

everyaisobjectNo

Gateway caching options

If you attach cache_control directly to a block, it is passed through as-is (see prompt caching). document and image tool_result blocks return 400. metadata.user_id is forwarded as Anthropic metadata. Send image blocks with source.type: "base64" (a url source has the same limits as https URLs in Chat). Models that reject forced tool use (any, tool) are the same as in Chat.

To continue a tool conversation, send the response content blocks back unchanged, including thinking blocks — Gemini's tool signature travels in the thinking block signature. stop_reason: "stop_sequence" and stop_sequence are set only on routes where the provider reports the matched string (Claude, vLLM-based); Gemini and GPT return end_turn even when a stop_sequences entry stopped the output.

Model options

Check the table above for the values the selected model supports (in the API: capabilities, limits, and parameter_constraints in GET /v1/models). Whether an unsupported value is adjusted or rejected with 400 is described under parameter policy in model selection and access.

For models supporting manual thinking, use budget_tokens ≥ 1024. Web search is available through Chat only.

POST /v1/messages/count_tokens

Estimates the input token count before you send a request. Claude Code calls this endpoint automatically.

• Free — no credit is deducted.
• Returns a token estimate that may differ from actual usage.
• The request body takes the same shape as /v1/messages.

{
  "input_tokens": 1234
}