Request parameters for v2/messages

This table shows parameters for message request:

Table 1. Message request
Parameter Type Required Description
modelId string false Specific ID or version of the model to use; the model is required for this field.
safetyGuardrail Boolean false The base guardrails from AWS.
Messages string true The array of objects. See the table for messages configuration below.
ModelConfig false Configuration to customize model parameters.

This table shows the configuration variables:

Table 2. Configuration
Name Type Required Description
max_response integer false

Maximum number of tokens to generate a response.

The default value is 1024.
temperature float false Sampling temperature to use, value must be between 0 and 2.
top_p float false An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.
stop_sequence string false Up to 4 sequences where the API stops generating further tokens.
frequency_penalty float false Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
presence_penalty float false Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
reasoning false
  • Enabled: the flag for enabling the extensive thinking
  • Budget_tokens: the maximum of tokens used for reasoning

This table shows the messages variables:

Table 3. Messages
Name Type Required Description
Role string true The role of the factor sending the message. Specify user or assistant.
Content string true

The array of objects containing these elements:

Note: When building the message array, structure it to reflect a natural conversation. Alternate between user and assistant roles. Do not place two messages from the same role next to each other.

Prompt request example for v2/messages

{
  "modelId": "claude-sonnet-4-5-20250929-v1:0",
  "messages": [ 
    {
      "role": "user",
      "content": [
        {
          "text": "What is the weather of New York"
        }
      ]
    }
  ],
  "toolConfig": {
    "tools": [
      {
        "toolSpec": {
          "name": "get_weather",
          "description": "Get current weather information",
          "inputSchema": {
            "json": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "City and state"
                }
              },
              "required": ["location"]
            }
          }
        }
      }
    ],
    "toolChoice": {
      "any": {}
    }
  }
}