Create a message

curl -X POST https://api-llm.sunra.ai/v1/messages \
  -H "Authorization: Bearer <SUNRA_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api-llm.sunra.ai/v1/messages",
    headers={
        "Authorization": "Bearer <SUNRA_KEY>",
        "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())

const response = await fetch("https://api-llm.sunra.ai/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <SUNRA_KEY>",
    "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);

{
  "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"
  }
}

POST

messages

curl -X POST https://api-llm.sunra.ai/v1/messages \
  -H "Authorization: Bearer <SUNRA_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api-llm.sunra.ai/v1/messages",
    headers={
        "Authorization": "Bearer <SUNRA_KEY>",
        "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())

const response = await fetch("https://api-llm.sunra.ai/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <SUNRA_KEY>",
    "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);

{
  "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"
  }
}

Creates a message using the Anthropic Messages API format. Supports text, images, PDFs, tools, and extended thinking.

Authentication

string

required

Bearer token. Use your API key as the bearer token in the Authorization header.Format: Bearer <SUNRA_KEY>

Request

This endpoint expects an object.

string

required

The model that will complete your prompt. Browse available models at sunra.ai/models.

object

Optional provider routing preferences. Omit for automatic routing. See Provider routing for supported fields and provider discovery.

object[] | null

required

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.

Show properties

string

required

The role of the message author. Supported values: user, assistant.

string | object[]

required

The content of the message. Can be a single string or an array of content blocks.

Show content block types

string

required

Value: text.

string

required

The text content.

object[] | null

Citations for the text block.

object

Cache control breakpoint at this content block.

Show properties

string

required

Value: ephemeral.

string

Time-to-live. Values: 5m (default), 1h.

string

required

Value: image.

object

required

Image source.

Show source variants

base64
url

string

required

Value: base64.

string

required

Media type: image/jpeg, image/png, image/gif, or image/webp.

string

required

Base64-encoded image data.

string

required

Value: url.

string

required

Image URL.

object

Cache control breakpoint at this content block.

string

required

Value: document.

object

required

Document source.

Show source variants

base64
text
content
url

string

required

Value: base64.

string

required

Value: application/pdf.

string

required

Base64-encoded PDF data.

string

required

Value: text.

string

required

Value: text/plain.

string

required

Plain text data.

string

required

Value: content.

string | object[]

required

Content blocks.

string

required

Value: url.

string

required

PDF URL.

object

Citations configuration.

Show properties

boolean

Whether citations are enabled for this document.

string

Additional context for the document.

string

Title of the document.

object

Cache control breakpoint at this content block.

string

required

Value: tool_use.

string

required

The ID of the tool use.

string

required

The name of the tool.

object

required

The input to the tool.

object

Cache control breakpoint at this content block.

string

required

Value: tool_result.

string

required

The ID of the tool use this result corresponds to.

string | object[]

The result content. Can be a string or an array of content blocks.

boolean

Whether this is an error result.

object

Cache control breakpoint at this content block.

string

required

Value: thinking.

string

required

The thinking content.

string

required

The signature of the thinking block.

string

required

Value: redacted_thinking.

string

required

The redacted thinking data.

number

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.

string | object[]

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.

boolean

default:false

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.

number

default:1

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.

number

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.

number

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.

string[]

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.

object[]

Definitions of tools that the model may use. Supports custom tools, Anthropic built-in tools, and server tools.

Show tool types

Custom Tool
Bash Tool
Text Editor Tool
Web Search Tool

string

required

Name of the tool. This is how the tool will be called by the model.

object

required

JSON schema for the tool’s input. This defines the shape of the input that your tool accepts and that the model will produce.

string

Description of what this tool does. Tool descriptions should be as detailed as possible.

string

Value: custom.

object

Cache control breakpoint.

Show properties

string

required

Value: ephemeral.

string

Time-to-live. Values: 5m (default), 1h.

string

required

Value: bash_20250124.

string

required

Value: bash.

object

Cache control breakpoint.

string

required

Value: text_editor_20250124.

string

required

Value: str_replace_editor.

object

Cache control breakpoint.

string

required

Value: web_search_20250305.

string

required

Value: web_search.

string[] | null

If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

string[] | null

If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

number | null

Maximum number of times the tool can be used in the API request.

object | null

Parameters for the user’s location. Used to provide more relevant search results.

Show properties

string

required

Value: approximate.

string | null

The city of the user.

string | null

The two letter ISO country code.

string | null

The region of the user.

string | null

The IANA timezone of the user.

object

Cache control breakpoint.

object

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.

Show variants

auto
any
none
tool

string

required

Value: auto.

boolean

Whether to disable parallel tool use. Defaults to false. If true, the model will output at most one tool use.

string

required

Value: any.

boolean

Whether to disable parallel tool use. Defaults to false. If true, the model will output exactly one tool use.

string

required

Value: none.

string

required

Value: tool.

string

required

The name of the tool to use.

boolean

Whether to disable parallel tool use. Defaults to false. If true, the model will output exactly one tool use.

object

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.

Show variants

enabled
disabled
adaptive

string

required

Value: enabled.

integer

required

Determines how many tokens Claude can use for its internal reasoning process. Must be ≥1024 and less than max_tokens.

string

required

Value: disabled.

string

required

Value: adaptive.

object

Configuration for controlling output behavior. Supports the effort parameter and structured output format.

Show properties

string | null

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.

object | null

A schema to specify Claude’s output format in responses (structured outputs).

Show properties

string

required

Value: json_schema.

object

required

The JSON schema of the format.

object

Top-level cache control. Automatically applies a cache_control marker to the last cacheable block in the request.

Show properties

string

required

Value: ephemeral.

string

Time-to-live for the cache control breakpoint. Values: 5m (5 minutes, default), 1h (1 hour).

string

Determines whether to use priority capacity or standard capacity for this request. Supported values: auto, standard_only.

object

An object describing metadata about the request.

Show properties

string

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.

string

Unique message identifier, e.g. msg_01XFDUDYJgAACzvnptvVoYEL.

string

Object type. Always message.

string

Conversational role of the generated message. Always assistant.

object | null

Information about the container used in the request (for the code execution tool).

Show properties

string

Identifier for the container used in this request.

string

The time at which the container will expire.

object[]

Content generated by the model. This is an array of content blocks, each of which has a type that determines its shape.

Show content block types

string

Value: text.

string

The generated text.

object[] | null

Citations supporting the text block. Can be char_location, page_location, content_block_location, web_search_result_location, or search_result_location.

string

Value: tool_use.

string

The ID of the tool use block.

string

The name of the tool.

object

The input to the tool as generated by the model.

string

Value: thinking.

string

The thinking content.

string

The signature of the thinking block.

string

Value: redacted_thinking.

string

The redacted data.

string

Value: server_tool_use.

string

The ID of the tool use block.

string

The server tool name. e.g., web_search, web_fetch, code_execution.

object

The input to the server tool.

string

Value: web_search_tool_result.

string

The ID of the tool use this result corresponds to.

object | object[]

Search results or error object.

string

Value: web_fetch_tool_result.

string

The ID of the tool use this result corresponds to.

object

Fetched content or error object.

string

Value: code_execution_tool_result.

string

The ID of the tool use this result corresponds to.

object

Execution result or error object.

string

The model that handled the request.

string | null

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

string | null

Which custom stop sequence was generated, if any.

object

Billing and rate-limit usage. The three input buckets are mutually exclusive — see Token usage.

Show properties

integer

The number of fresh input tokens which were used. Excludes both cache buckets.

integer

The number of output tokens which were used.

integer

All input buckets plus output_tokens. Omitted on streamed responses.

integer | null

The number of input tokens used to create the cache entry.

integer | null

The number of input tokens read from the cache.

string | null

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.

object | null

Breakdown of cached tokens by TTL.

Show properties

integer

The number of input tokens used to create the 5 minute cache entry.

integer

The number of input tokens used to create the 1 hour cache entry.

string | null

The geographic region where inference was performed for this request.

object | null

The number of server tool requests.

Show properties

integer

The number of web search tool requests.

integer

The number of web fetch tool requests.

string | null

If the request used the priority, standard, or batch tier. Values: standard, priority, batch.

curl -X POST https://api-llm.sunra.ai/v1/messages \
  -H "Authorization: Bearer <SUNRA_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api-llm.sunra.ai/v1/messages",
    headers={
        "Authorization": "Bearer <SUNRA_KEY>",
        "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())

const response = await fetch("https://api-llm.sunra.ai/v1/messages", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <SUNRA_KEY>",
    "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);

{
  "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"
  }
}

Overview

Platform

Multimodal

LLM

Client Libraries

Authentication

Request

Response

​Authentication

​Request

​Response

Authentication

Request

Response