NeosantaraAI models are capable of interacting with tools (also known as functions), allowing you to extend the AI’s capabilities to perform a wider variety of tasks, such as fetching real-time data, performing calculations, or interacting with external systems. Here’s an example of how to provide tools to NeosantaraAI using the chat completions API: 
curl https://api.neosantara.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEOSANTARA_API_KEY" \
  -d '{
    "model": "nusantara-base",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. Jakarta, ID"
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What is the weather like in Jakarta?"
      }
    ]
  }'

​
How Tool Use Works

NeosantaraAI’s tool use functionality follows a common pattern, similar to OpenAI’s function calling, where you provide the model with descriptions of available tools, and the model decides if and how to use them. Integrate client-side tools with NeosantaraAI in these steps:
1

Provide NeosantaraAI with tools and a user prompt

  • Define tools with names, descriptions, and input schemas (parameters) in your API request within the tools parameter.
  • Include a user prompt that might require these tools, e.g., “What’s the weather in Jakarta?”
2

NeosantaraAI decides to use a tool

  • The model assesses if any tools can help with the user’s query.
  • If yes, the model constructs a tool_calls object within its response, containing the name of the tool to be called and the arguments (input) for that tool.
  • The API response will have a finish_reason of tool_calls.
3

Execute the tool and return results

  • Your application extracts the tool name and input from NeosantaraAI’s tool_calls response.
  • Your application then executes the actual tool code on your system.
  • Return the results to the model in a new user message with a tool role, containing the tool_call_id and the content of the tool’s output.
4

NeosantaraAI uses tool result to formulate a response

  • NeosantaraAI analyzes the tool results you provide to craft its final, natural language response to the original user prompt.
Note: Steps 3 and 4 are optional. For some workflows, NeosantaraAI’s tool use request (step 2) might be all you need, without sending results back to the model.

​
Tool Use Examples

Here are a few code examples demonstrating various tool use patterns and techniques. The examples use simple tools for clarity.

​
Pricing

Tool use requests are priced based on:
  1. The total number of input tokens sent to the model (including the tokens from tool definitions in the tools parameter and tool call/result messages).
  2. The number of output tokens generated (including tool calls generated by the model).
  3. Additional charges may apply for specific capabilities (e.g., vision processing for image inputs).
The additional tokens from tool use come from:
  • The tools array in API requests (tool names, descriptions, and parameter schemas).
  • tool_calls generated by the model in assistant messages.
  • tool messages (containing tool_call_id and content) sent by your application.
These token counts are added to your normal input and output tokens to calculate the total cost of a request. Refer to our pricing documentation for current per-model prices and usage tiers. When you send a tool use prompt, just like any other API request, the response will output both input and output token counts as part of the reported usage metrics.

​
Next Steps

Explore our other capabilities and API references:

Image Generation

Generate high-quality images from text prompts.

Embeddings

Convert text into numerical vectors for semantic search.