Create a Message

POST /v1/messages

Create a Message

cURL

curl --request POST \
  --url https://api.neosantara.xyz/v1/messages \
  --header 'x-api-key: <api-key>'

200

{
  "id": "<string>",
  "type": "<string>",
  "role": "<string>",
  "model": "<string>",
  "stop_reason": "<string>",
  "stop_sequence": {},
  "content": {
    "type": "<string>",
    "text": "<string>"
  },
  "usage": {
    "input_tokens": 123,
    "output_tokens": 123,
    "cache_creation_input_tokens": 123,
    "cache_read_input_tokens": 123
  }
}

Get your free API key

Start with 10,000 Monthly Token Limit on our Free Plan. No credit card required. Your tokens automatically reset on the 1st of each month.

model · string · required

The model ID to use for the request.

Example: "garda-beta-mini", "nusantara-base"

messages · array[object] · required

Array of message objects with alternating user/assistant roles.

Show message structure

role · string · required

The role of the message sender. Must be either "user" or "assistant".

content · string | array[object] · required

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

Content Types:

• Text: {"type": "text", "text": "..."}
• Image URL: {"type": "image_url", "image_url": {"url": "https://..."}}
• Document: {"type": "document", "..."}
• String: Direct string (automatically converted to text block)

max_tokens · integer · required

Maximum tokens for the response.

Range: ≥ 1

system · string | array[object]

System prompt/instructions for the model.

Show Format

• String: Direct system message
• Array: Array of system blocks [{"type": "text", "text": "..."}]

temperature · number · default: "1.0"

Controls randomness. Higher = more random, Lower = more deterministic.

Range: 0.0 - 1.0

Show Example

• 0.0 - Completely deterministic
• 0.7 - Balanced creativity
• 1.0 - Maximum randomness

stream · boolean · default: "false"

Enable streaming responses (Server-Sent Events format).

Show streaming events

• message_start - Initial message metadata
• content_block_start - Text block starts
• content_block_delta - Text chunk delta
• content_block_stop - Text block ends
• message_delta - Message metadata update
• message_stop - Stream complete

top_p · number · default: "1.0"

Nucleus sampling - cumulative probability threshold.

Range: 0.0 - 1.0

top_k · number

Sample from top K tokens by probability.

Range: > 0

stop_sequences · array[string] · default: "[]"

Sequences where generation stops.

Max Items: Typically 5 sequences

tools · array[object] · default: "[]"

Array of tool/function definitions.

Show tool structure

name · string · required

The name of the tool/function.

description · string · required

A description of what the tool does.

input_schema · object · required

JSON Schema defining the tool’s input parameters.

Show Example

"tools": [
  {
    "name": "calculate",
    "description": "Calculate math expression",
    "input_schema": {
      "type": "object",
      "properties": {
        "expression": {"type": "string"}
      },
      "required": ["expression"]
    }
  }
]

tool_choice · string · default: "auto"

How to handle tool selection.

Show options

• "auto" - Model decides whether to use a tool
• "any" - Model must use a tool
• {"type": "tool", "name": "..."} - Use specific tool

thinking · object

Enable extended thinking mode.

Show thinking properties

type · string · required

Must be "enabled" to activate thinking mode.

budget_tokens · integer · required

Number of tokens allocated for thinking.

Constraints:

• Must be ≥ 1024
• Must be < max_tokens

metadata · object · default: "{}"

Custom metadata for tracking/logging.

service_tier · string · default: "auto"

Which service tier to use.

Show option

"auto", "standard_only"

Returns

id · string

The unique identifier for the message.

type · string

The type of the response, always "message".

role · string

The role of the responder, always "assistant".

model · string

The model used for the response.

stop_reason · string

The reason generation stopped, e.g., "end_turn".

stop_sequence · string | null

The stop sequence that triggered the end, if any.

content · array[object]

The generated content.

Show content structure

type · string

The type of content block, e.g., "text".

text · string

The text content.

usage · object

Token usage statistics.

Show usage properties

input_tokens · integer

Number of input tokens.

output_tokens · integer

Number of output tokens.

cache_creation_input_tokens · integer

Cache creation input tokens.

cache_read_input_tokens · integer

Cache read input tokens.

Return Examples

Response 200

{
  "id": "msg_01XYZ...",
  "type": "message",
  "role": "assistant",
  "model": "nusantara-base",
  "content": [
    {
      "type": "text",
      "text": "The capital of France is Paris."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8
  }
}