The Messages API is a conversation envelope
The Anthropic Messages API gives Claude a conversation and asks it to produce the next assistant turn. Think of each request as an envelope: it names the model, sets an output limit, includes instructions, and carries the conversation so far.
The central idea is simple: you send structured messages, not just a prompt string. Once you understand that structure, text responses, images, and tool calls become easier to follow.
Four fields to recognize before your first request
- model: The API model identifier for the Claude model you want to use. Copy the exact identifier from your provider's model list; a display name is not necessarily a valid API value.
- max_tokens: The maximum number of tokens the model may generate for this response. It is an output ceiling, not a promise that the response will use the full allowance.
- system: Optional top-level instructions that guide the assistant, such as its task, tone, or formatting requirements.
- messages: An ordered array of conversation turns. Each turn has a role and content.
A minimal request body has this shape, with the placeholder model value replaced before sending:
{"model":"YOUR_MODEL_ID","max_tokens":256,"system":"Explain concepts in plain English.","messages":[{"role":"user","content":"What is an API?"}]}
For a small learning exercise, Claude Haiku 4.5 is one option to consider. The request structure remains the same when you select another supported Claude model.
Roles identify the speaker, not the instruction priority
The usual message roles are user and assistant. A user message contains a question, task, or supplied material. An assistant message represents an earlier model reply that you include as conversation history.
Unlike some other API formats, Anthropic's native Messages API does not put system instructions in a message with a system role. Use the top-level system field instead.
A normal follow-up request includes the earlier user message, the assistant's reply, and the new user message. The API does not automatically remember earlier requests for you. Your application chooses which history to send, and that history contributes to input token usage.
Content blocks let one message carry different things
For a basic text message, content can be a string. It can also be an array of typed blocks. A text block looks like {"type":"text","text":"What is an API?"}.
The block structure matters because messages can contain more than plain text. Depending on the model and supported features, blocks can represent images, tool requests, or tool results. Check each block's type before deciding how to process it.
Do not assume every response is one text string. For a simple chat interface, collect text from text blocks. Keep other block types available for the logic that handles them.
The response tells you what happened and where it stopped
A typical response includes an id, the assistant role, the model identifier, a content array, a stop_reason, and usage information. The generated answer lives inside content, rather than in an OpenAI-style choices array.
- end_turn: The assistant finished its turn normally.
- max_tokens: Generation reached the configured output limit. The answer may be incomplete.
- tool_use: The assistant requested a tool action. Your application must handle that request rather than treating it as a finished answer.
Usage reports input and output token counts, with additional fields for supported features such as caching. Inspect these fields instead of estimating cost from character counts alone.
Check the endpoint before connecting your application
Anthropic's native endpoint is POST /v1/messages. Direct requests use authentication and an API-version header alongside a JSON content type. Follow your provider's documentation for the exact credentials and supported features.
SwiftRelay is worth considering for pay-as-you-go, per-token access to Claude and other models. Its API host is https://api.fastapirelay.com. Confirm the native Messages API route and header requirements before connecting: OpenAI-compatible SDK support does not make the two request formats interchangeable. Sign up for SwiftRelay to try the structure with the small gift credit available to new accounts.