> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a message
Creates a message using the Anthropic Messages API format. Supports text, images, PDFs, tools, and extended thinking.
## Authentication
Bearer token. Use your API key as the bearer token in the Authorization header.
Format: `Bearer `
## Request
This endpoint expects an object.
The model that will complete your prompt. Browse available models at [sunra.ai/models](https://sunra.ai/models).
Optional provider routing preferences. Omit for automatic routing. See [Provider routing](/llm/provider-routing) for supported fields and provider discovery.
Input messages. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or include multiple `user` and `assistant` messages for multi-turn conversations.
The role of the message author. Supported values: `user`, `assistant`.
The content of the message. Can be a single string or an array of content blocks.
Value: `text`.
The text content.
Citations for the text block.
Cache control breakpoint at this content block.
Value: `ephemeral`.
Time-to-live. Values: `5m` (default), `1h`.
Value: `image`.
Image source.
Value: `base64`.
Media type: `image/jpeg`, `image/png`, `image/gif`, or `image/webp`.
Base64-encoded image data.
Value: `url`.
Image URL.
Cache control breakpoint at this content block.
Value: `document`.
Document source.
Value: `base64`.
Value: `application/pdf`.
Base64-encoded PDF data.
Value: `text`.
Value: `text/plain`.
Plain text data.
Value: `content`.
Content blocks.
Value: `url`.
PDF URL.
Citations configuration.
Whether citations are enabled for this document.
Additional context for the document.
Title of the document.
Cache control breakpoint at this content block.
Value: `tool_use`.
The ID of the tool use.
The name of the tool.
The input to the tool.
Cache control breakpoint at this content block.
Value: `tool_result`.
The ID of the tool use this result corresponds to.
The result content. Can be a string or an array of content blocks.
Whether this is an error result.
Cache control breakpoint at this content block.
Value: `thinking`.
The thinking content.
The signature of the thinking block.
Value: `redacted_thinking`.
The redacted thinking data.
The maximum number of tokens to generate before stopping. Note that the model may stop before reaching this maximum. Different models have different maximum values for this parameter; a value above a model's own ceiling is rejected with `400` rather than reduced. See [Output limits](/llm/limits).
System prompt. A system prompt is a way of providing context and instructions to the model.
Can be a string or an array of `TextBlockParam` objects, each containing `text`, `type` (`"text"`), optional `cache_control`, and optional `citations`.
Whether to incrementally stream the response using server-sent events (SSE). Streams are subject to an idle timeout and a lifetime ceiling — see [Output limits and stream lifetime](/llm/limits#stream-lifetime).
Amount of randomness injected into the response. Ranges from 0.0 to 1.0. Use `temperature` closer to 0.0 for analytical/multiple choice tasks, and closer to 1.0 for creative and generative tasks. Note that even with `temperature` of 0.0, the results will not be fully deterministic.
Use nucleus sampling. Computes the cumulative distribution over all options for each subsequent token in decreasing probability order and cuts it off once it reaches the probability specified by `top_p`. Recommended for advanced use cases only. You usually only need to use `temperature`.
Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. Recommended for advanced use cases only.
Custom text sequences that will cause the model to stop generating. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence.
Definitions of tools that the model may use. Supports custom tools, Anthropic built-in tools, and server tools.
Name of the tool. This is how the tool will be called by the model.
[JSON schema](https://json-schema.org/draft/2020-12) for the tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce.
Description of what this tool does. Tool descriptions should be as detailed as possible.
Value: `custom`.
Cache control breakpoint.
Value: `ephemeral`.
Time-to-live. Values: `5m` (default), `1h`.
Value: `bash_20250124`.
Value: `bash`.
Cache control breakpoint.
Value: `text_editor_20250124`.
Value: `str_replace_editor`.
Cache control breakpoint.
Value: `web_search_20250305`.
Value: `web_search`.
If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`.
If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`.
Maximum number of times the tool can be used in the API request.
Parameters for the user's location. Used to provide more relevant search results.
Value: `approximate`.
The city of the user.
The two letter ISO country code.
The region of the user.
The IANA timezone of the user.
Cache control breakpoint.
How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
Value: `auto`.
Whether to disable parallel tool use. Defaults to `false`. If `true`, the model will output at most one tool use.
Value: `any`.
Whether to disable parallel tool use. Defaults to `false`. If `true`, the model will output exactly one tool use.
Value: `none`.
Value: `tool`.
The name of the tool to use.
Whether to disable parallel tool use. Defaults to `false`. If `true`, the model will output exactly one tool use.
Configuration for enabling Claude's extended thinking. When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens.
Value: `enabled`.
Determines how many tokens Claude can use for its internal reasoning process. Must be ≥1024 and less than `max_tokens`.
Value: `disabled`.
Value: `adaptive`.
Configuration for controlling output behavior. Supports the effort parameter and structured output format.
How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer. Valid values: `low`, `medium`, `high`, `max`.
A schema to specify Claude's output format in responses (structured outputs).
Value: `json_schema`.
The JSON schema of the format.
Top-level cache control. Automatically applies a cache\_control marker to the last cacheable block in the request.
Value: `ephemeral`.
Time-to-live for the cache control breakpoint. Values: `5m` (5 minutes, default), `1h` (1 hour).
Determines whether to use priority capacity or standard capacity for this request. Supported values: `auto`, `standard_only`.
An object describing metadata about the request.
An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier.
## Response
Successful message response.
Unique message identifier, e.g. `msg_01XFDUDYJgAACzvnptvVoYEL`.
Object type. Always `message`.
Conversational role of the generated message. Always `assistant`.
Information about the container used in the request (for the code execution tool).
Identifier for the container used in this request.
The time at which the container will expire.
Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape.
Value: `text`.
The generated text.
Citations supporting the text block. Can be `char_location`, `page_location`, `content_block_location`, `web_search_result_location`, or `search_result_location`.
Value: `tool_use`.
The ID of the tool use block.
The name of the tool.
The input to the tool as generated by the model.
Value: `thinking`.
The thinking content.
The signature of the thinking block.
Value: `redacted_thinking`.
The redacted data.
Value: `server_tool_use`.
The ID of the tool use block.
The server tool name. e.g., `web_search`, `web_fetch`, `code_execution`.
The input to the server tool.
Value: `web_search_tool_result`.
The ID of the tool use this result corresponds to.
Search results or error object.
Value: `web_fetch_tool_result`.
The ID of the tool use this result corresponds to.
Fetched content or error object.
Value: `code_execution_tool_result`.
The ID of the tool use this result corresponds to.
Execution result or error object.
The model that handled the request.
The reason that the model stopped generating. Possible values:
* `end_turn` — the model reached a natural stopping point
* `max_tokens` — exceeded `max_tokens` or the model's maximum
* `stop_sequence` — one of your custom stop sequences was generated
* `tool_use` — the model invoked one or more tools
* `pause_turn` — a long-running turn was paused
* `refusal` — streaming classifiers intervened for potential policy violations
Which custom stop sequence was generated, if any.
Billing and rate-limit usage. The three input buckets are mutually exclusive — see [Token usage](/llm/token-usage).
The number of fresh input tokens which were used. Excludes both cache buckets.
The number of output tokens which were used.
All input buckets plus `output_tokens`. Omitted on streamed responses.
The number of input tokens used to create the cache entry.
The number of input tokens read from the cache.
Present as `anthropic.exclusive.v1` when Sunra normalized this response. Assert on this value rather than inferring the convention from the numbers. See [Token usage](/llm/token-usage).
Breakdown of cached tokens by TTL.
The number of input tokens used to create the 5 minute cache entry.
The number of input tokens used to create the 1 hour cache entry.
The geographic region where inference was performed for this request.
The number of server tool requests.
The number of web search tool requests.
The number of web fetch tool requests.
If the request used the priority, standard, or batch tier. Values: `standard`, `priority`, `batch`.
```bash cURL theme={null}
curl -X POST https://api-llm.sunra.ai/v1/messages \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Hello, how are you?"
}
]
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api-llm.sunra.ai/v1/messages",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json"
},
json={
"model": "anthropic/claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, how are you?"}
]
}
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api-llm.sunra.ai/v1/messages", {
method: "POST",
headers: {
"Authorization": "Bearer ",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "anthropic/claude-sonnet-4-6",
max_tokens: 1024,
messages: [
{ role: "user", content: "Hello, how are you?" }
]
})
});
const data = await response.json();
console.log(data);
```
```json 200 theme={null}
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"container": null,
"content": [
{
"type": "text",
"text": "Hello! I'm doing well, thank you for asking. How can I help you today?",
"citations": null
}
],
"model": "anthropic/claude-sonnet-4-6",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 19,
"total_tokens": 31,
"cache_creation_input_tokens": null,
"cache_read_input_tokens": null,
"cache_creation": null,
"inference_geo": null,
"server_tool_use": null,
"service_tier": null,
"sunra_usage_semantics": "anthropic.exclusive.v1"
}
}
```