> ## Documentation Index
> Fetch the complete documentation index at: https://nusaai-edit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Compatibility

> > Use the official OpenAI SDK to interact with the Neosantara AI API.

Neosantara AI provides a robust compatibility layer that enables you to use the official OpenAI SDKs to interact with our API. With only a few minor code changes, you can quickly evaluate Neosantara AI model capabilities or even migrate existing applications.

<Note>
  While this compatibility layer is fully supported, our priority remains the reliability and performance of the native **[Neosantara AI API](/api-reference/introduction)**. For the best experience and access to our complete feature set, we recommend using our modern `/v1/responses` endpoint.
</Note>

## Getting Started

To use the OpenAI SDK, you only need to change three things in your existing code:

1. **Update the `base_url`** to point to Neosantara AI's API endpoint.
2. **Replace your API key** with a [Neosantara AI API key](https://app.neosantara.xyz/dashboard).
3. **Update the model name** to a [Neosantara AI model](/en/models-overview).

<View title="Responses" icon="chat">
  ### Quick Start: [`responses`](/api-reference/responses/create) API

  The `/v1/responses` endpoint is our most powerful and modern API. Use `client.responses.create()` to access it.

  <CodeGroup>
    ```python icon="python" py theme={null}
    from openai import OpenAI

    client = OpenAI(
        api_key="<NAI_API_KEY>",
        base_url="https://api.neosantara.xyz/v1"
    )

    response = client.responses.create(
        model="nusantara-base",
        input="Who are you?"
    )

    # Access the response text
    print(response.output_text)
    ```

    ```javascript icon="square-js" js theme={null}
    import OpenAI from 'openai';

    const openai = new OpenAI({
        apiKey: "<NAI_API_KEY>",
        baseURL: "https://api.neosantara.xyz/v1",
    });

    const response = await openai.responses.create({
        input: "Who are you?",
        model: "nusantara-base",
    });

    console.log(response.output_text);
    ```
  </CodeGroup>

  ### Example with Tools

  <CodeGroup>
    ```python icon="py" theme={null}
    from openai import OpenAI
    import json

    client = OpenAI(
        api_key="<NAI_API_KEY>",
        base_url="https://api.neosantara.xyz/v1"
    )

    # 1. Define a list of callable tools for the model
    tools = [
        {
            "type": "function",
            "name": "get_horoscope",
            "description": "Get today's horoscope for an astrological sign.",
            "parameters": {
                "type": "object",
                "properties": {
                    "sign": {
                        "type": "string",
                        "description": "An astrological sign like Taurus or Aquarius",
                    },
                },
                "required": ["sign"],
            },
        },
    ]

    def get_horoscope(sign):
        return f"{sign}: Next Tuesday you will befriend a baby otter."

    # Create a running input list we will add to over time
    input_list = [
        {"role": "user", "content": "What is my horoscope? I am an Aquarius."}
    ]

    # 2. Prompt the model with tools defined
    response = client.responses.create(
        model="nusantara-base",
        tools=tools,
        input=input_list,
    )

    # Save function call outputs for subsequent requests
    input_list += response.output

    for item in response.output:
        if item.type == "function_call":
            if item.name == "get_horoscope":
                # 3. Execute the function logic for get_horoscope
                horoscope = get_horoscope(json.loads(item.arguments))

                # 4. Provide function call results to the model
                input_list.append({
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": json.dumps({
                      "horoscope": horoscope
                    })
                })

    print("Final input:")
    print(input_list)

    response = client.responses.create(
        model="nusantara-base",
        instructions="Respond only with a horoscope generated by a tool.",
        tools=tools,
        input=input_list,
    )

    # 5. The model should be able to give a response!
    print("Final output:")
    print(response.model_dump_json(indent=2))
    print("\n" + response.output_text)
    ```

    ```javascript icon="square-js" js theme={null}
    import OpenAI from "openai";
    const openai = new OpenAI();

    // 1. Define a list of callable tools for the model
    const tools = [
      {
        type: "function",
        name: "get_horoscope",
        description: "Get today's horoscope for an astrological sign.",
        parameters: {
          type: "object",
          properties: {
            sign: {
              type: "string",
              description: "An astrological sign like Taurus or Aquarius",
            },
          },
          required: ["sign"],
        },
      },
    ];

    function getHoroscope(sign) {
      return sign + " Next Tuesday you will befriend a baby otter.";
    }

    // Create a running input list we will add to over time
    let input = [
      { role: "user", content: "What is my horoscope? I am an Aquarius." },
    ];

    // 2. Prompt the model with tools defined
    let response = await openai.responses.create({
      model: "gpt-5",
      tools,
      input,
    });

    response.output.forEach((item) => {
      if (item.type == "function_call") {
        if (item.name == "get_horoscope"):
          // 3. Execute the function logic for get_horoscope
          const horoscope = get_horoscope(JSON.parse(item.arguments))
          
          // 4. Provide function call results to the model
          input_list.push({
              type: "function_call_output",
              call_id: item.call_id,
              output: json.dumps({
                horoscope
              })
          })
      }
    });

    console.log("Final input:");
    console.log(JSON.stringify(input, null, 2));

    response = await openai.responses.create({
      model: "gpt-5",
      instructions: "Respond only with a horoscope generated by a tool.",
      tools,
      input,
    });

    // 5. The model should be able to give a response!
    console.log("Final output:");
    console.log(JSON.stringify(response.output, null, 2));
    ```
  </CodeGroup>
</View>

<View title="Completions" icon="comment">
  ### Quick Start: [`Completions`](/api-reference/chat/completions/create) API

  The `/v1/chat/completions` endpoint is available for seamless compatibility with existing applications. Use `client.chat.completions.create()` to access it.

  <CodeGroup>
    ```python icon="python" py theme={null}
    from openai import OpenAI

    client = OpenAI(
    api_key="<NAI_API_KEY>",
    base_url="https://api.neosantara.xyz/v1"
    )

    response = client.chat.completions.create(
    model="nusantara-base",
    messages=[
    {"role": "user", "content": "Who are you?"}
    ],
    )

    print(response.choices[0].message.content)

    ```

    ```typescript icon="square-js" js theme={null}
    import OpenAI from 'openai';

    const openai = new OpenAI({
        apiKey: "<NAI_API_KEY>",
        baseURL: "https://api.neosantara.xyz/v1",
    });

    const response = await openai.chat.completions.create({
        messages: [
            { role: "user", content: "Who are you?" }
        ],
        model: "nusantara-base",
    });

    console.log(response.choices[0].message.content);
    ```
  </CodeGroup>

  ### Example with Tools

  ```bash icon="terminal" theme={null}
  curl https://api.neosantara.xyz/v1/chat/completions \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "model": "llama-3.3-70b-instruct",
      "messages": [{"role": "user", "content": "What is the weather in Jakarta?"}],
      "tools": [{
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {"type": "string", "description": "City name"}
            },
            "required": ["location"]
          }
        }
      }]
    }'
  ```
</View>

## Feature Compatibility Details

While we aim for maximum compatibility, there are some differences in how certain features are implemented.

#### System / Developer Messages

The concept of a `system` prompt is fully supported. For some underlying providers that don't have a native system role, the content of your system message will be automatically prepended to the first user message to ensure the model follows your instructions.

#### Reasoning

Neosantara AI supports advanced reasoning through a special `reasoning` parameter available in both the `/v1/responses` and `/v1/chat/completions` endpoints.

```python theme={null}
# This parameter is supported by Neosantara AI
response = client.responses.create(
    model="nusantara-base",
    input="Solve this complex logic puzzle...",
    reasoning={"effort": "high"}
)
```

#### Conversation State (`store`)

The `store: true` and `previous_response_id` parameters are **fully supported** in the `/v1/responses` endpoint. This allows you to build stateful conversations without manually resending the entire chat history. This feature is not available for `/v1/chat/completions`.

#### Tools

The endpoint supports OpenAI-compatible function calling. See [Tools Overview](/tools-overview) for details.

## Detailed Parameter Support

Most unsupported fields are silently ignored to prevent errors.

| Field                       | Support Status & Notes                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------ |
| `model`                     | **Fully supported**. Use Neosantara AI model names.                                              |
| `messages`                  | **Fully supported** in `/v1/chat/completions`.                                                   |
| `input` / `instructions`    | **Fully supported** in `/v1/responses`.                                                          |
| `max_tokens`                | **Fully supported**.                                                                             |
| `stream`                    | **Fully supported** for both endpoints.                                                          |
| `temperature`               | **Fully supported**.                                                                             |
| `top_p`                     | **Fully supported**.                                                                             |
| `stop`                      | **Fully supported**.                                                                             |
| `presence_penalty`          | **Fully supported**.                                                                             |
| `frequency_penalty`         | **Fully supported**.                                                                             |
| `response_format`           | **Fully supported**. `json_schema` is only available in `/v1/responses`.                         |
| `tools` / `functions`       | **Fully supported**. `strict` mode is handled on a best-effort basis by the underlying provider. |
| `tool_choice`               | **Fully supported**.                                                                             |
| `n`                         | Ignored. Only one choice (`n=1`) is supported.                                                   |
| `logprobs` / `top_logprobs` | Ignored.                                                                                         |
| `user` / `metadata`         | Ignored.                                                                                         |
| `seed`                      | Ignored.                                                                                         |