claude-sonnet-4-5-20250929-thinking
Text To Text
Create an chat message
POST
/
v1
/
messages
Authorization
- Auth Type:
Bearer Auth(In:header) - Format:
Authorization: Bearer <YOUR_API_KEY> - Description: Use
Bearer <YOUR_API_KEY>. Format:Authorization: Bearer sk-xxxxxx. - API Key: where API Key is your AGCloud API KEY
Response Examples
Show Sync Responses
Show Sync Responses
Show Async Responses
Show Async Responses
Show Streaming Responses
Show Streaming Responses
Async Chat Response Field Description
| Field | Type | Range | Description |
|---|---|---|---|
id | string | - | The current chat task id. |
object | string | - | The type of object returned by the API. In this case it is always task. |
status | string | pending processing success failed | Current status of the task. |
created_at | number | - | Unix timestamp (in seconds) indicating when the task was created. |
Streaming Events
| Event | Description |
|---|---|
message_start | Indicates the start of a new message |
content_block_start | Indicates the start of a content block |
content_block_delta | Contains incremental text content |
content_block_stop | Indicates the end of a content block |
message_delta | Contains final message metadata (stop_reason, usage) |
message_stop | Indicates the end of the message |
Parameters
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | ✅ | - | The model ID to use for this request. |
messages | array<object> | ✅ | - | An array of message objects representing the conversation history. See Messages |
max_tokens | integer | ✅ | 4096 | The maximum number of tokens the model can generate in the response. Range 1-32000 |
async | boolean | - | false | Whether to return an asynchronous response. Only supported for non-streaming requests. |
stream | boolean | - | false | If true, returns a stream of server-sent events (SSE) as the response is generated. |
system | string | array<object> | - | - | System prompt that sets the behavior and context for the assistant. See System |
temperature | number | - | 1.0 | Controls the randomness of the output. Lower values produce more focused responses, higher values produce more creative outputs. Range 0.0-1.0 |
top_p | number | - | 1.0 | Nucleus sampling parameter. The model considers tokens with top_p cumulative probability mass. Range 0.0-1.0 |
top_k | integer | - | - | Limits token selection to the K most probable tokens at each step. |
stop_sequences | array<string> | - | - | An array of strings that will stop generation when encountered. |
tools | array<object> | - | - | A list of tools the model may call to generate the response. See Tools |
tool_choice | object | - | auto | Controls how the model selects which tool(s) to use. Can be auto any tool. See Tool Choices |
thinking | object | - | - | Configuration for extended thinking (chain-of-thought) mode. See Thinking |
metadata | object | - | - | Optional metadata to associate with the request. See Metadata |
If both
stream and async are true, stream takes precedence.Messages Array Structure
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
role | string | ✅ | - | The role of the message. Can be: user or assistant |
content | string | array | ✅ | - | The content of the message. Can be a simple string for text-only messages, or an array of content blocks for multimodal content |
>content.type | string | ✅ if content is array | - | Must be text |
>content.text | string | ✅ if content is array | - | The text content |
System Array Structure
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | string | ✅ | - | The system tips, default text |
text | string | ✅ | - | Describe the role the model plays. |
Tools Array Structure
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
type | string | ✅ | - | The type of tool. Must be web_search_20250305 for web search |
name | string | ✅ | - | The name of the tool. Use web_search |
max_uses | integer | - | - | Maximum number of times the web search tool can be used in a single request, range in 1-10 |
allowed_domains | array | - | - | Only include search results from these domains. Cannot be used with blocked_domains |
blocked_domains | array | - | - | Never include search results from these domains. Cannot be used with allowed_domains |
user_location | object | - | - | Localize search results based on user’s location. See User Location |
max_uses parameter limits the number of searches performed. If Claude attempts more searches than allowed, the web_search_tool_result will be an error with the max_uses_exceeded error code.
Domain Filtering
When using domain filters:
- Domains should not include the HTTP/HTTPS scheme (use example.com instead of https://example.com)
- Subdomains are automatically included (example.com covers docs.example.com)
- Specific subdomains restrict results to only that subdomain (docs.example.com returns only results from that subdomain, not from example.com or api.example.com)
- Subpaths are supported (example.com/blog)
- You can use either allowed_domains or blocked_domains, but not both in the same request
- Request-level domain restrictions must be compatible with organization-level domain restrictions configured in the Console
User Location Structure
Theuser_location object allows you to localize search results based on user’s location:
| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✅ | The type of location. Must be approximate |
city | string | - | The city name (e.g., San Francisco) |
region | string | - | The region or state (e.g., California) |
country | string | - | The country code in ISO 3166-1 alpha-2 format (e.g., US) |
timezone | string | - | The IANA timezone ID (e.g., America/Los_Angeles) |
Tool Choices Structure
| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✅ | Tool selection mode. auto: model decides whether to use a tool, any: model must use one of the available tools, tool: model must use the specific tool specified by name. |
name | string | - | The name of the specific tool to use. Required only when type is tool. |
Thinking Structure
| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✅ | Thinking mode. enabled: model uses extended thinking for internal reasoning before generating the response, disabled: standard response mode. |
budget_tokens | integer | - | Maximum tokens allocated for thinking. Required when type is enabled. The model uses these tokens for internal reasoning before producing the final output. |
Metadata Structure
| Field | Type | Required | Description |
|---|---|---|---|
user_id | string | - | An external identifier for the user making the request. Useful for analytics, abuse detection, and logging. |