> ## 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.

# Create Chat Completion

<Card icon="key" href="https://app.neosantara.xyz/api-keys" title="Get your free API key" horizontal>
  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.
</Card>

<ParamField path="model" type="string" required>
  ID of the model to use (e.g., `garda-beta-mini`, `nusantara-base`). See [`/v1/models`](/api-reference/models/list-available-models).
</ParamField>

<ParamField path="messages" type="array" required>
  A list of messages comprising the conversation so far.

  <Expandable title="message properties">
    <ParamField path="role" type="string" required>
      The role of the messages author. One of `system`, `user`, `assistant`, or `tool`.
    </ParamField>

    <ParamField path="content" type="string or array" required>
      The contents of the message.
    </ParamField>

    <ParamField path="name" type="string">
      An optional name for the participant. Provides the model information to differentiate between participants of the same role.
    </ParamField>

    <ParamField path="tool_call_id" type="string">
      Tool call that this message is responding to (required for `tool` role).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="max_tokens" type="integer">
  The maximum number of tokens to generate in the chat completion.
</ParamField>

<ParamField path="temperature" type="number" default="1">
  What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
</ParamField>

<ParamField path="top_p" type="number" default="1">
  An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top\_p probability mass.
</ParamField>

<ParamField path="stream" type="boolean" default="false">
  If set, partial message deltas will be sent. Tokens will be sent as data-only server-sent events as they become available.
</ParamField>

<ParamField path="stop" type="string or array">
  Up to 4 sequences where the API will stop generating further tokens.
</ParamField>

<ParamField path="tools" type="array">
  A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for.
</ParamField>

<ParamField path="tool_choice" type="string or object">
  Controls which (if any) tool is called by the model. Can be `none`, `auto`, `required`, or a specific tool object.
</ParamField>

<ParamField path="reasoning" type="object">
  Enable reasoning capabilities for supported models (e.g., `nusantara-base`, `garda-beta-mini`).

  <Expandable title="properties">
    <ParamField path="effort" type="string">
      Controls the reasoning effort. Can be `low`, `medium`, or `high`. (Cannot be used with `max_tokens`)
    </ParamField>

    <ParamField path="max_tokens" type="integer">
      The maximum number of tokens to reserve for reasoning. (Cannot be used with `effort`)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="web_search_options" type="object">
  Configuration for web search capabilities on supported models.

  <Expandable title="properties">
    <ParamField path="search_depth" type="string">
      The depth of the search. Can be `basic` or `advanced`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="response_format" type="object">
  An object specifying the format that the model must output.

  <Expandable title="properties">
    <ParamField path="type" type="string">
      Must be one of `text`, `json_object`, or `json_schema`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="user" type="string">
  A unique identifier representing your end-user, which can help Neosantara AI to monitor and detect abuse.
</ParamField>

## Returns

<ResponseField name="id" type="string">
  A unique identifier for the chat completion.
</ResponseField>

<ResponseField name="object" type="string">
  The object type, which is always `chat.completion`.
</ResponseField>

<ResponseField name="created" type="integer">
  The Unix timestamp (in seconds) of when the chat completion was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model used for the chat completion.
</ResponseField>

<ResponseField name="choices" type="array">
  A list of chat completion choices.

  <Expandable title="choices properties">
    <ResponseField name="index" type="integer">
      The index of the choice in the list of choices.
    </ResponseField>

    <ResponseField name="message" type="object">
      A chat completion message generated by the model.

      <Expandable title="properties">
        <ResponseField name="role" type="string">
          The role of the author of this message.
        </ResponseField>

        <ResponseField name="content" type="string">
          The contents of the message.
        </ResponseField>

        <ResponseField name="tool_calls" type="array">
          The tool calls generated by the model, such as function calls.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finish_reason" type="string">
      The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence, `length` if the maximum number of tokens specified in the request was reached, `tool_calls` if the model called a tool, or `content_filter` if content was omitted due to a flag from our content filters.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Usage statistics for the completion request.

  <Expandable title="usage properties">
    <ResponseField name="prompt_tokens" type="integer">
      Number of tokens in the prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Number of tokens in the generated completion.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total number of tokens used in the request (prompt + completion).
    </ResponseField>
  </Expandable>
</ResponseField>

## Return Examples

```json Response 200 theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "nusantara-base",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello there, how may I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}
```