Messages schemas

You're Claude Code, working in my repository.

Task
Type my app's Messages calls with the definitions on this page: AnthropicMessageRequest (messages, system blocks, tools, tool_choice, thinking, output_config), the content block params I send, AnthropicMessage with its content blocks and AnthropicUsage, and the count_tokens request and response. Then parse one real reply with them.

Read this first
Meta's docs page "Messages schemas" as Markdown: https://dev.meta.ai/docs/api-reference/messages/schemas.md
It's the source of truth for request and response shapes. The same page for people: https://dev.meta.ai/docs/api-reference/messages/schemas

Setup
- Base URL: https://api.meta.ai/v1 for HTTP calls (POST https://api.meta.ai/v1/messages); the Anthropic SDK takes https://api.meta.ai
- Auth: send Authorization: Bearer $MODEL_API_KEY, reading MODEL_API_KEY from the environment. Never hard-code, print or commit the key.
- Model: muse-spark-1.3-contributor (Contributor mode: Meta may use what you send to train future models; drop -contributor for Standard mode)
- Python: the Anthropic SDK (pip install anthropic) with base_url="https://api.meta.ai" (no /v1) and auth_token=os.environ["MODEL_API_KEY"], or plain requests to https://api.meta.ai/v1/messages.

Facts to get right
- Input content blocks are a union told apart by type: text, image, video, document, search_result, tool_use, tool_result, server_tool_use, thinking, redacted_thinking. A block a role doesn't support is an invalid_request_error.
- Reply content blocks include text, thinking (the summary the page describes), redacted_thinking (field data; the only reasoning block Meta sent when this was built), tool_use and server_tool_use. Replay reasoning blocks as is.
- AnthropicThinkingConfigParam is enabled (budget_tokens at least 1024 and below max_tokens), adaptive or disabled; display is summarized or omitted.
- AnthropicUsage: input_tokens and output_tokens, plus cache_read_input_tokens, cache_creation_input_tokens and output_tokens_details.thinking_tokens.
- AnthropicToolChoice type is auto, any or none; cache_control takes only {"type": "ephemeral", "ttl": "5m"}.

Starter code (Python)
from typing import Literal, NotRequired, TypedDict

class AnthropicUsage(TypedDict):
    input_tokens: int
    output_tokens: int
    cache_creation_input_tokens: NotRequired[int]
    cache_read_input_tokens: NotRequired[int]
    output_tokens_details: NotRequired[dict]

class AnthropicMessage(TypedDict):
    id: str
    type: Literal["message"]
    role: Literal["assistant"]
    model: str
    content: list[dict]  # switch on block["type"]: text, thinking, redacted_thinking, tool_use, server_tool_use
    stop_reason: Literal["end_turn", "max_tokens", "stop_sequence", "tool_use", "pause_turn", "refusal"]
    stop_sequence: str | None
    usage: AnthropicUsage

Done when
- A real reply parses with the types, thinking, redacted_thinking and tool_use blocks included.
- The key comes from MODEL_API_KEY and never appears in code, logs or commits.
- API errors (4xx, 429) surface their message instead of failing silently.

The full schema and model definitions referenced by the Messages endpoints. Each endpoint page links here for the detailed shape of its request and response objects.

Schemas#

Anthropic Base64 Source Param#

Inline base64-encoded media.

Anthropic Cache Control Ephemeral Param#

Prompt-cache breakpoint. Accepted to improve cache hit rates. Only the 5m TTL is supported.

Anthropic Citations Config Param#

Document citation settings. Enabling citations is not supported.

Anthropic Content Block#

Anthropic Messages content block. Supported block types are text, image, video (Meta extension), document, tool_use, tool_result, server_tool_use, thinking, and redacted_thinking. cache_control prompt-cache controls are accepted to improve cache hit rates. Unsupported block types return an invalid_request_error.

Anthropic Content Block Param#

Input content block. A block type that a role does not support returns an invalid_request_error.

Type: AnthropicTextBlockParam | AnthropicImageBlockParam | AnthropicVideoBlockParam | AnthropicDocumentBlockParam | AnthropicSearchResultBlockParam | AnthropicToolUseBlockParam | AnthropicToolResultBlockParam | AnthropicServerToolUseBlockParam | AnthropicThinkingBlockParam | AnthropicRedactedThinkingBlockParam

Anthropic Content Source Block Param#

A block of an inline-content document.

Type: AnthropicContentSourceTextBlockParam | AnthropicContentSourceOtherBlockParam

Anthropic Content Source Other Block Param#

Any other block of an inline-content document, passed as its JSON text.

Anthropic Content Source Param#

Document built from inline content blocks.

Anthropic Content Source Text Block Param#

A text block of an inline-content document.

Anthropic Count Tokens Request#

Anthropic Count Tokens Response#

Anthropic Custom Tool Param#

A developer tool. type is omitted or custom.

Anthropic Direct Caller Param#

The model invoked the tool directly.

Anthropic Document Block Param#

Document input.

Anthropic Document Source Param#

Document source.

Type: AnthropicBase64SourceParam | AnthropicPlainTextSourceParam | AnthropicContentSourceParam | AnthropicUrlSourceParam | AnthropicFileSourceParam

Anthropic File Source Param#

Media referenced by an uploaded file ID.

Anthropic Image Block Param#

Image input.

Anthropic Input Message#

Anthropic Messages input message.

Anthropic Json Output Format#

Anthropic JSON structured-output format.

Anthropic Media Source Param#

Image or video source.

Type: AnthropicBase64SourceParam | AnthropicUrlSourceParam | AnthropicFileSourceParam

Anthropic Message#

Anthropic-compatible assistant message response.

Anthropic Message Request#

Anthropic Message Request Base#

Anthropic Messages request accepted at /v1/messages. top_k, stop_sequences and inference_geo are not supported, so a request that sets them is rejected.

Anthropic Metadata Param#

Request metadata. user_id identifies the end user; other string values are passed through.

Anthropic Output Config#

Anthropic output controls. effort sets the reasoning effort; max selects the strongest available effort.

Anthropic Plain Text Source Param#

Plain-text document.

Anthropic Redacted Thinking Block Param#

Encrypted reasoning returned by an earlier response, replayed as is.

Anthropic Search Result Block Param#

Search result passed to the model as its JSON text.

Anthropic Server Tool Caller Param#

What invoked the tool. Accepted and ignored.

Type: AnthropicDirectCallerParam

Anthropic Server Tool Use Block Param#

Earlier server tool call, replayed. Supported names are web_search and tool_search.

Anthropic Server Tool Use Input Param#

The call input, as returned.

Anthropic Stream Event#

Anthropic Messages server-sent event. Stream event names include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, message_stop, and error.

Type: object

Anthropic System Text Block Param#

A system prompt text block.

Anthropic Text Block Param#

Text content.

Anthropic Thinking Block Param#

Earlier reasoning summary, replayed.

Anthropic Thinking Config Adaptive Param#

The model decides how much to reason.

Anthropic Thinking Config Disabled Param#

Reasoning off, where the model supports it.

Anthropic Thinking Config Enabled Param#

Reasoning with a token budget.

Anthropic Thinking Config Param#

Extended reasoning settings.

Type: AnthropicThinkingConfigEnabledParam | AnthropicThinkingConfigAdaptiveParam | AnthropicThinkingConfigDisabledParam

Anthropic Tool#

Anthropic tool definition. Custom (developer) tools are supported; supported hosted tools are accepted, and unsupported hosted tools return an invalid_request_error.

Type: AnthropicWebSearchToolParam | AnthropicToolSearchToolParam | AnthropicCustomToolParam

Anthropic Tool Choice#

Anthropic Tool Result Block Param#

Result of an earlier tool call.

Anthropic Tool Result Content Block Param#

A block of a tool result. Blocks other than text, image and document are passed as their JSON text.

Type: AnthropicContentSourceTextBlockParam | AnthropicToolResultImageBlockParam | AnthropicToolResultDocumentBlockParam | AnthropicToolResultOtherBlockParam

Anthropic Tool Result Document Block Param#

A document in a tool result.

Anthropic Tool Result Image Block Param#

An image in a tool result.

Anthropic Tool Result Other Block Param#

Any other block of a tool result, passed as its JSON text.

Anthropic Tool Search Tool Param#

The hosted tool search tool.

Anthropic Tool Use Block Param#

Earlier tool call, replayed.

Anthropic Url Source Param#

Media fetched from a URL.

Anthropic Usage#

Anthropic User Location Param#

Approximate user location for web search.

Anthropic Video Block Param#

Video input (Meta extension).

Anthropic Web Search Tool Param#

The hosted web search tool.

Mirrored from dev.meta.ai/docs/api-reference/messages/schemas (synced Oct 30, 2026). Text and examples © Meta. Live demos run on Muse Muse's key.