Messages API
Relevant source files
The following files were used as context for generating this wiki page:
The Messages API is the primary interface for interacting with Claude models within the Anthropic Go SDK. It enables developers to send structured prompts—comprising user and assistant turns—to generate text, process multimodal inputs (like images and documents), and utilize tools. The API supports both synchronous request-response patterns and real-time streaming of model outputs.
This module also includes Beta features for advanced capabilities, such as Message Batches for high-throughput asynchronous processing and "Structured Outputs" for enforcing specific JSON schemas on model responses.
Sources: README.md:28-44, examples/message/main.go:13-25, betamessagebatch.go:42-47
Core Message Generation
The standard workflow involves creating a Client and calling Messages.New. This function accepts a set of parameters including the target model, a list of messages (the conversation history), and the maximum number of tokens to generate.
Message Structure and Roles
The API operates on alternating turns between user and assistant roles. Content within these turns can be simple text or complex arrays of content blocks, such as text blocks, image blocks, or tool use blocks.
The diagram above illustrates the structure of a Messages API request, highlighting the alternating roles and block types.
Sources: examples/message/main.go:13-25, betamessagebatch.go:278-310, message_test.go:41-52
Key Request Parameters
| Parameter | Type | Description |
|---|---|---|
Model | Model | The specific Claude model to use (e.g., ClaudeSonnet4_5). |
Messages | []MessageParam | Array of prior conversational turns. |
MaxTokens | int64 | Maximum tokens to generate before stopping. |
System | []TextBlockParam | Context/instructions provided to the model. |
Temperature | float64 | Randomness in response (0.0 to 1.0). |
StopSequences | []string | Custom sequences that trigger generation halt. |
Sources: message_test.go:41-88, betamessagebatch.go:264-390
Streaming and Accumulation
For real-time applications, the SDK provides a streaming interface through Messages.NewStreaming. This returns a stream that emits events as the model generates content.
Event Processing Flow
Streaming involves handling different event types such as MessageStartEvent, ContentBlockDeltaEvent (containing text or JSON fragments), and MessageStopEvent. The SDK provides an Accumulate method to rebuild a complete Message object from these fragmented events.
The sequence diagram shows the interaction between the application and the API during a streaming session.
Sources: examples/message-streaming/main.go:17-43, message_test.go:150-200
Beta Message Batches
The Beta.Messages.Batches service allows for processing large volumes of requests asynchronously. These batches can take up to 24 hours to complete and are designed for non-latency-sensitive workloads.
Batch Lifecycle
- Creation: Submit multiple
Messages.Newrequests in a single call. - Polling: Use the Batch ID to check the
processing_status(in_progress,canceling, orended). - Retrieval: Once finished, the results are available via a
.jsonlfile specified in theresults_url.
| Status | Description |
|---|---|
in_progress | The batch is currently being processed by the system. |
canceling | Cancellation has been initiated but not finalized. |
ended | All requests have succeeded, errored, canceled, or expired. |
Sources: betamessagebatch.go:42-120, betamessagebatch.go:189-204
Multimodal and Document Inputs
The Messages API supports more than just text. It can ingest images (base64 encoded) and documents (via file IDs).
- Images: Included in a
MessageParamusingNewImageBlockBase64, specifying media type and data. - Documents: Leverages the Beta Files API. Files are first uploaded to obtain a
FileID, which is then referenced in aBetaDocumentBlock.
This diagram outlines the process of including a file in a Messages API request.
Sources: examples/multimodal/main.go:28-44, examples/file-upload/main.go:23-53
Advanced Configuration and Tool Use
The API supports complex features like "Tool Use" and "Thinking" (extended chain-of-thought).
Tools and Structured Output
Developers define tools with JSON schemas. Claude can then output tool_use blocks, which the application executes before returning results. Alternatively, the OutputFormat parameter (Beta) can force the model to respond entirely in a valid JSON format matching a provided schema.
Thinking Mode
The Thinking configuration enables Claude's extended thinking capabilities. It requires a minimum budget of tokens and produces special content blocks showing the model's internal reasoning process before providing the final answer.
Sources: message_test.go:102-125, betamessage_test.go:61-95, betamessagebatch.go:425-435
The Messages API serves as the backbone of the Anthropic SDK for Go, providing a unified interface for simple chats, complex tool-integrated workflows, and high-volume batch processing across various input modalities.