> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Generate the next message in a conversation. OpenAI-compatible, with or without streaming.

Early access
**Gnani Evon v3.5** is now available as an API to early access registrants.

## Overview

Send a conversation and get the model's next message. The call is **stateless**: nothing is stored between requests, so `messages` must hold the whole conversation every time.

The request and response follow [OpenAI's Chat Completions API](https://platform.openai.com/docs/api-reference/chat/create). New to the API? Start with the [Overview](https://docs.gnani.ai/api/LLM/overview.md).

***

## Endpoint

```text theme={null}
POST https://api.vachana.ai/v1/chat/completions
Content-Type: application/json
```

***

## Authentication

Send your API key in one of these headers. If you send both, `X-API-Key-ID` is used.

| Header | Required | Description |
| - | - | - |
| `X-API-Key-ID` | One of the two | Your Gnani API key. |
| `Authorization` | One of the two | `Bearer <your-api-key>`. This is what OpenAI's SDKs send. |
| `X-API-Request-ID` | No | Your own ID for the request. It is returned in the `X-API-Request-ID` response header. If you leave it out, one is generated. |

***

## Request body

```json theme={null}
{
  "model": "evon-v3.5",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
    {"role": "user", "content": "What is the capital of Karnataka?"}
  ],
  "temperature": 0.6,
  "max_tokens": 512,
  "reasoning_effort": "none"
}
```

Only `messages` is required. Every other field has a default.

**Every value is checked before the model runs.** A value of the wrong type or out of range is refused with `400 invalid_request`, and the message names the field, for example `temperature must be between 0 and 2, got -1`. Sending `null` for a field means "use the default". A field name the API does not know is refused with `400 unknown_parameter`, so a typo does not pass silently. A few OpenAI fields that Gnani does not use, such as `logprobs` and `store`, are accepted and ignored. See [Migrating from OpenAI](https://docs.gnani.ai/api/LLM/openai-compatibility.md).

### Parameters at a glance

Every request field, with its allowed values. Full descriptions and the playground are in the generated parameter list on this page. A value outside its range is refused with `400 invalid_request`.

| Parameter | Type | Range or options | Default | Purpose |
| - | - | - | - | - |
| `model` | string | `evon-v3.5` only. Any other value returns `404 model_not_found`. | `evon-v3.5` | The model to use. |
| `messages` | object\[] | At least 1 message. `role`: `system`, `developer`, `user`, `assistant` or `tool`. | required | The conversation so far, oldest first. |
| `stream` | boolean | `true`, `false` | `false` | Stream the reply as Server-Sent Events. See [Streaming](https://docs.gnani.ai/api/LLM/streaming.md). |
| `stream_options` | object | `include_usage`: `true` or `false` (default `false`). Only with `"stream": true`. | | Adds a last chunk with token `usage`. |
| `max_tokens` | integer | `1` to your plan's maximum: **1,024** on Free and Pay-as-you-go; on Enterprise, up to the context window less the input. | 1,024 on Free and Pay-as-you-go | Most tokens in the reply, thinking included. See [Limits](https://docs.gnani.ai/api/LLM/limits.md). |
| `max_completion_tokens` | integer | Same as `max_tokens` | | Another name for `max_tokens`. |
| `temperature` | number | `0` to `2` | `0.6` | How random the reply is. Lower is more focused. |
| `top_p` | number | Above `0`, up to `1` | `0.95` | Nucleus sampling. |
| `stop` | string \| string\[] | One string, or up to 4 strings. Each at least 1 character. | | Stop sequences. |
| `seed` | integer | Any integer | | Makes sampling repeatable, not guaranteed. |
| `frequency_penalty` | number | `-2` to `2` | `0` | Discourages repeating the same words. |
| `presence_penalty` | number | `-2` to `2` | `0` | Encourages new topics. |
| `reasoning_effort` | string | `none`, `minimal`, `low`, `medium`, `high` | | `none` turns thinking off. The other values leave it on. See [Thinking](https://docs.gnani.ai/api/LLM/thinking.md). |
| `enable_thinking` | boolean | `true`, `false` | `true` | Turns thinking on or off. See [Thinking](https://docs.gnani.ai/api/LLM/thinking.md). |
| `reasoning_budget` | integer | `0` to `65536`. `0` means no budget. | `32768` | Most tokens the model may spend thinking. See [Thinking](https://docs.gnani.ai/api/LLM/thinking.md). |
| `tools` | object\[] | `function` tools, and the built-in `{"type": "web_search"}` | | See [Tool calling](https://docs.gnani.ai/api/LLM/tool-calling.md) and [Web search](https://docs.gnani.ai/api/LLM/web-search.md). |
| `tool_choice` | string \| object | `none`, `auto`, `required`, or `{"type": "function", "function": {"name": "..."}}` | `auto` | Whether and which tool the model calls. See [Tool calling](https://docs.gnani.ai/api/LLM/tool-calling.md). |
| `parallel_tool_calls` | boolean | `true`, `false` | | Allow more than one function call in one reply. |
| `response_format` | object | `{"type": "text"}`, `{"type": "json_object"}` or `{"type": "json_schema", "json_schema": {...}}` | `{"type": "text"}` | Ask for JSON. See [JSON output](https://docs.gnani.ai/api/LLM/structured-outputs.md). |
| `top_k` | integer | `-1` or `0` for no limit, or a positive integer | `40` | Gnani-only. Sample from the `top_k` most likely tokens. |
| `min_p` | number | `0` to `1` | | Gnani-only. Drop tokens less likely than `min_p` times the most likely one. |
| `typical_p` | number | Above `0`, up to `1`. `1` turns it off. | | Gnani-only. Typical sampling. |
| `repetition_penalty` | number | Above `0`, up to `2`. `1.0` turns it off. | `1.0` | Gnani-only. Discourages repetition. |
| `no_repeat_ngram_size` | integer | `0` to `20`. `0` turns it off. | `0` | Gnani-only. Never repeat a run of this many tokens. |
| `user` | string | Any string | | An ID for your end user, for your own tracking. |

The Gnani-only fields are not part of OpenAI's API. With OpenAI's Python SDK, pass them in `extra_body`. The Gnani Python SDK clients work the same way; see [Python SDK: LLM](https://docs.gnani.ai/python-sdk/llm.md#gnani-only-parameters).

***

## Response

### The chat completion object

Without streaming (the default), the response is `200 OK` with `Content-Type: application/json`:

```json theme={null}
{
  "id": "chatcmpl-6b1f4f0c2a5e4d8b",
  "object": "chat.completion",
  "created": 1794390000,
  "model": "evon-v3.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of Karnataka is Bengaluru."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 41,
    "completion_tokens": 9,
    "total_tokens": 50
  }
}
```

**id** `string`

An ID for this completion.

**object** `string`

Always `chat.completion`.

**created** `integer`

When the reply was created, in Unix seconds.

**model** `string`

The model that wrote the reply.

**choices** `object[]`

Always one choice.

**choice fields**

**index** `integer`

The choice's index.

**message.role** `string`

Always `assistant`.

**message.content** `string | null`

The reply. `null` when the model only calls tools.

**message.reasoning** `string | null`

The model's thinking, when thinking is on. Show it to users only if you want to; you do not need to send it back in later requests.

**message.tool\_calls** `object[] | null`

The functions the model wants you to run. See [the tool call object](#the-tool-call-object) and [Tool calling](https://docs.gnani.ai/api/LLM/tool-calling.md).

**message.web\_search** `object`

Only with the `web_search` tool: the searches the model ran and the sources it used. See the web\_search object below, and [Web search](https://docs.gnani.ai/api/LLM/web-search.md).

**finish\_reason** `string`

Why the model stopped.

| Value | Meaning |
| - | - |
| `stop` | The reply is complete, or a `stop` sequence was reached. |
| `length` | The reply reached `max_tokens` and was cut short. |
| `tool_calls` | The model is asking you to run functions. |
| `content_filter` | The safety filters withheld the reply. See [Safety and privacy](https://docs.gnani.ai/api/LLM/safety.md). |

**usage** `object`

Tokens used by this request. See [the usage object](#the-usage-object).

> [!NOTE]
>
> **The model thinks before it answers, by default.** Its thinking is returned in `message.reasoning`, apart from the answer in `message.content`, and it counts as output tokens. For quick answers, send `"reasoning_effort": "none"` to turn thinking off. See [Thinking](https://docs.gnani.ai/api/LLM/thinking.md).

### The chat completion chunk object

With `"stream": true`, the response is `200 OK` with `Content-Type: text/event-stream`. Each event is a `chat.completion.chunk` that carries the next piece of the reply in `choices[0].delta`, and the stream ends with `data: [DONE]`:

```text wrap theme={null}
data: {"id":"chatcmpl-6b1f4f0c2a5e4d8b","object":"chat.completion.chunk","created":1794390000,"model":"evon-v3.5","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-6b1f4f0c2a5e4d8b","object":"chat.completion.chunk","created":1794390000,"model":"evon-v3.5","choices":[{"index":0,"delta":{"content":"The capital of Karnataka"},"finish_reason":null}]}

data: {"id":"chatcmpl-6b1f4f0c2a5e4d8b","object":"chat.completion.chunk","created":1794390000,"model":"evon-v3.5","choices":[{"index":0,"delta":{"content":" is Bengaluru."},"finish_reason":"stop"}]}

data: [DONE]
```

**id** `string`

An ID for this completion.

**object** `string`

Always `chat.completion.chunk`.

**created** `integer`

When the reply was created, in Unix seconds.

**model** `string`

The model that wrote the reply.

**choices** `object[]`

One choice, or an empty list on the last `usage` chunk.

**choice fields**

**index** `integer`

The choice's index.

**delta.role** `string`

`assistant`, on the first chunk.

**delta.content** `string`

The next piece of the reply. Can be empty or missing. Join every `delta.content` in order to rebuild the reply.

**delta.reasoning** `string`

The next piece of the model's thinking, when thinking is on. It arrives before the reply. See [Thinking](https://docs.gnani.ai/api/LLM/thinking.md).

**delta.tool\_calls** `object[]`

Pieces of a function call. The first piece for each call has its `index`, `id` and `function.name`; the following pieces add to `function.arguments`. Join the pieces by `index` until a chunk has a `finish_reason`, then parse the arguments. See [Tool calling](https://docs.gnani.ai/api/LLM/tool-calling.md).

**delta.web\_search** `object`

Only with the `web_search` tool: progress of a search. See the web\_search object below.

**finish\_reason** `string | null`

`null` until the last content chunk, then one of the values listed for [the chat completion object](#the-chat-completion-object).

**usage** `object`

Only on the last chunk before `[DONE]`, and only when you send `"stream_options": {"include_usage": true}`. That chunk has an empty `choices` list. See [the usage object](#the-usage-object).

How to read the stream, and what happens when it fails part-way, is on the [Streaming](https://docs.gnani.ai/api/LLM/streaming.md) page.

### The usage object

```json theme={null}
{"prompt_tokens": 41, "completion_tokens": 9, "total_tokens": 50}
```

**prompt\_tokens** `integer`

Input tokens.

**completion\_tokens** `integer`

Output tokens, thinking included.

**total\_tokens** `integer`

Total tokens.

These are the numbers counted against your [daily quota](https://docs.gnani.ai/api/LLM/limits.md). With the `web_search` tool, `usage` adds up every model call made for the request, including the search results the model read.

### The tool call object

```json wrap theme={null}
{
  "id": "call_9f2c41",
  "type": "function",
  "function": {
    "name": "get_order_status",
    "arguments": "{\"order_id\": \"ORD-48213\"}"
  }
}
```

**id** `string`

The call's ID. Send it back as `tool_call_id` on the `tool` message that holds the result.

**type** `string`

Always `function`.

**function** `object`

**function fields**

**name** `string`

The name of the function to run, from your `tools`.

**arguments** `string`

The arguments as a JSON-encoded string, not an object, written by the model. Validate it before use.

When streaming, each piece in `delta.tool_calls` also has an `index`, which you use to join the pieces of one call.

### The web\_search object

In `message.web_search`, when the model searched the web:

```json wrap theme={null}
{
  "queries": ["Mumbai weather forecast this weekend"],
  "sources": [
    {
      "id": 1,
      "title": "Mumbai weekend forecast",
      "url": "https://example.com/mumbai-forecast",
      "snippet": "Saturday: light showers in the afternoon. Sunday: partly cloudy..."
    }
  ],
  "remaining_today": 9
}
```

**queries** `string[]`

The searches the model ran, in order.

**sources** `object[]`

Every result the model was given. Numbering runs across all searches in the request.

**source fields**

**id** `integer`

The number the answer cites, as `[id]`.

**title** `string`

The page title.

**url** `string`

The page URL.

**snippet** `string`

The relevant text from the page.

**remaining\_today** `integer`

How many searches you have left today.

When streaming, `delta.web_search` reports each search as it happens:

**status** `string`

| Value | Meaning |
| - | - |
| `searching` | A search has started. `query` is what is being searched. |
| `completed` | The search finished. `sources` holds the results (empty if nothing was found), and `remaining` the searches left today. |
| `failed` | The search could not run. The model answers without it. |
| `limit_reached` | Your daily search limit was reached during this request. The model answers without searching further. |

**query** `string`

What is being searched.

**sources** `object[]`

On `completed`: the results, with the same fields as above.

**remaining** `integer`

On `completed`: the searches left today.

### Response headers

| Header | Description |
| - | - |
| `X-API-Request-ID` | The request ID: yours, or a generated one. Quote it when you contact support. |
| `Retry-After` | On some `429` responses: the number of seconds to wait before retrying. |

***

## Errors

Error codes, shapes and what to do about each are on the [Errors](https://docs.gnani.ai/api/LLM/errors.md) page.

## Retrying

Which errors to retry, and how, is in [Errors: Retrying](https://docs.gnani.ai/api/LLM/errors.md#retrying).

***

## Code examples

```bash cURL theme={null}
curl https://api.vachana.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: $GNANI_API_KEY" \
  -d '{
    "model": "evon-v3.5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
      {"role": "user", "content": "What is the capital of Karnataka?"}
    ],
    "temperature": 0.3,
    "max_tokens": 512,
    "reasoning_effort": "none"
  }'
```

```python Python (OpenAI SDK) theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.vachana.ai/v1",
    api_key=os.environ["GNANI_API_KEY"],
)

completion = client.chat.completions.create(
    model="evon-v3.5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
        {"role": "user", "content": "What is the capital of Karnataka?"},
    ],
    temperature=0.3,
    max_tokens=512,
    reasoning_effort="none",
)

choice = completion.choices[0]
print(choice.message.content)
if choice.finish_reason == "length":
    print("(the reply was cut short; raise max_tokens)")
print(completion.usage)
```

```python Python (Gnani SDK) theme={null}
# pip install "gnani-vachana[llm]"   (the async client is AsyncGnaniLLMClient; await the call)
from gnani.llm import GnaniLLMClient

client = GnaniLLMClient()  # reads GNANI_API_KEY

completion = client.chat.completions.create(
    model="evon-v3.5",
    messages=[
        {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
        {"role": "user", "content": "What is the capital of Karnataka?"},
    ],
    temperature=0.3,
    max_tokens=512,
    reasoning_effort="none",
)

choice = completion.choices[0]
print(choice.message.content)
if choice.finish_reason == "length":
    print("(the reply was cut short; raise max_tokens)")
print(completion.usage)
```

```javascript JavaScript (OpenAI SDK) theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.vachana.ai/v1",
  apiKey: process.env.GNANI_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "evon-v3.5",
  messages: [
    { role: "system", content: "You are a helpful assistant. Answer in one or two sentences." },
    { role: "user", content: "What is the capital of Karnataka?" },
  ],
  temperature: 0.3,
  max_tokens: 512,
  reasoning_effort: "none",
});

const choice = completion.choices[0];
console.log(choice.message.content);
if (choice.finish_reason === "length") {
  console.log("(the reply was cut short; raise max_tokens)");
}
console.log(completion.usage);
```

```python Python (requests) theme={null}
import os
import requests

response = requests.post(
    "https://api.vachana.ai/v1/chat/completions",
    headers={"X-API-Key-ID": os.environ["GNANI_API_KEY"]},
    json={
        "model": "evon-v3.5",
        "messages": [
            {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
            {"role": "user", "content": "What is the capital of Karnataka?"},
        ],
        "temperature": 0.3,
        "max_tokens": 512,
        "reasoning_effort": "none",
    },
    timeout=300,
)

body = response.json()
if response.ok:
    print(body["choices"][0]["message"]["content"])
else:
    # LLM errors use {"error": {...}}; authentication and rate-limit errors use {"detail": {...}}
    error = body.get("error") or body.get("detail") or {}
    print(response.status_code, error.get("code") or error.get("error_code"), error.get("message"))
```

***

## Differences from OpenAI

How this API differs from OpenAI's Chat Completions API is on the [OpenAI compatibility](https://docs.gnani.ai/api/LLM/openai-compatibility.md) page.


## OpenAPI

````yaml POST /v1/chat/completions
openapi: 3.1.0
info:
  title: LLM API
  description: |
    OpenAI-compatible Chat Completions API for Gnani's language model.
    Only `POST /v1/chat/completions` is public.
  version: 1.0.0
servers:
  - url: https://api.vachana.ai
    description: Production server
security: []
paths:
  /v1/chat/completions:
    post:
      summary: Chat Completions
      description: |
        Generates the next assistant message for a conversation. The call is
        stateless: send the whole conversation in `messages` every time.
      operationId: create_chat_completion
      parameters:
        - name: X-API-Key-ID
          in: header
          required: true
          description: >-
            Your Gnani API key. You can send it as `Authorization: Bearer <key>`
            instead.
          schema:
            type: string
        - name: X-API-Request-ID
          in: header
          required: false
          description: >-
            Your own ID for this request. It is returned in the
            `X-API-Request-ID` response header.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: Basic request
                value:
                  model: evon-v3.5
                  messages:
                    - role: system
                      content: >-
                        You are a helpful assistant. Answer in one or two
                        sentences.
                    - role: user
                      content: What is the capital of Karnataka?
                  temperature: 0.3
                  max_tokens: 512
                  reasoning_effort: none
              hindi:
                summary: Reply in Hindi
                value:
                  model: evon-v3.5
                  messages:
                    - role: system
                      content: >-
                        You are a helpful assistant. Reply in Hindi, in one or
                        two sentences.
                    - role: user
                      content: UPI से पैसे कैसे भेजते हैं?
                  reasoning_effort: none
              thinking:
                summary: Thinking with a budget
                value:
                  model: evon-v3.5
                  max_tokens: 1024
                  reasoning_budget: 256
                  messages:
                    - role: user
                      content: Plan a 3-day trip to Hampi on a student budget.
              json_schema:
                summary: JSON that follows a schema
                value:
                  model: evon-v3.5
                  reasoning_effort: none
                  temperature: 0
                  messages:
                    - role: system
                      content: Extract the appointment details from the message.
                    - role: user
                      content: Can I see Dr. Rao on Friday at 4 pm? It's for my knee.
                  response_format:
                    type: json_schema
                    json_schema:
                      name: appointment
                      schema:
                        type: object
                        properties:
                          doctor:
                            type: string
                          day:
                            type: string
                          time:
                            type: string
                          reason:
                            type: string
                        required:
                          - doctor
                          - day
                          - time
                          - reason
                        additionalProperties: false
              tool_call:
                summary: Tool calling
                value:
                  model: evon-v3.5
                  reasoning_effort: none
                  messages:
                    - role: system
                      content: You are a support assistant for an online store.
                    - role: user
                      content: Where is my order ORD-48213?
                  tools:
                    - type: function
                      function:
                        name: get_order_status
                        description: Look up the delivery status of a customer's order.
                        parameters:
                          type: object
                          properties:
                            order_id:
                              type: string
                              description: The order ID, for example ORD-48213.
                          required:
                            - order_id
              web_search:
                summary: Web search
                value:
                  model: evon-v3.5
                  messages:
                    - role: user
                      content: Will it rain in Mumbai this weekend?
                  tools:
                    - type: web_search
              streaming:
                summary: Streaming, with usage
                value:
                  model: evon-v3.5
                  stream: true
                  stream_options:
                    include_usage: true
                  messages:
                    - role: system
                      content: >-
                        You are a helpful assistant. Answer in one or two
                        sentences.
                    - role: user
                      content: What is the capital of Karnataka?
                  reasoning_effort: none
      responses:
        '200':
          description: |
            `application/json` (a `chat.completion` object) by default, or
            `text/event-stream` (`chat.completion.chunk` events ending in
            `data: [DONE]`) when `stream` is `true`.
          headers:
            X-API-Request-ID:
              description: The request ID. Quote it when you contact support.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
              examples:
                basic:
                  summary: A plain reply
                  value:
                    id: chatcmpl-6b1f4f0c2a5e4d8b
                    object: chat.completion
                    created: 1794390000
                    model: evon-v3.5
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: The capital of Karnataka is Bengaluru.
                        finish_reason: stop
                    usage:
                      prompt_tokens: 41
                      completion_tokens: 9
                      total_tokens: 50
                tool_call:
                  summary: The model asks you to run a function
                  value:
                    id: chatcmpl-6b1f4f0c2a5e4d8c
                    object: chat.completion
                    created: 1794390000
                    model: evon-v3.5
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: null
                          tool_calls:
                            - id: call_9f2c41
                              type: function
                              function:
                                name: get_order_status
                                arguments: '{"order_id": "ORD-48213"}'
                        finish_reason: tool_calls
                web_search:
                  summary: An answer with web sources
                  value:
                    id: chatcmpl-6b1f4f0c2a5e4d8d
                    object: chat.completion
                    created: 1794390000
                    model: evon-v3.5
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: >-
                            Light rain is likely in Mumbai on Saturday, with a
                            drier Sunday [1]. Carry an umbrella if you are out
                            on Saturday afternoon [2].
                          web_search:
                            queries:
                              - Mumbai weather forecast this weekend
                            sources:
                              - id: 1
                                title: Mumbai weekend forecast
                                url: https://example.com/mumbai-forecast
                                snippet: >-
                                  Saturday: light showers in the afternoon.
                                  Sunday: partly cloudy...
                              - id: 2
                                title: Monsoon update for the Konkan coast
                                url: https://example.org/konkan-update
                                snippet: >-
                                  Isolated showers are expected along the coast
                                  on Saturday...
                            remaining_today: 9
                        finish_reason: stop
                    usage:
                      prompt_tokens: 1630
                      completion_tokens: 112
                      total_tokens: 1742
            text/event-stream:
              schema:
                type: string
                description: >-
                  Server-Sent Events. Each `data:` line holds one
                  `chat.completion.chunk`; the last is `data: [DONE]`.
              example: >
                data:
                {"id":"chatcmpl-6b1f4f0c2a5e4d8b","object":"chat.completion.chunk","created":1794390000,"model":"evon-v3.5","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}


                data:
                {"id":"chatcmpl-6b1f4f0c2a5e4d8b","object":"chat.completion.chunk","created":1794390000,"model":"evon-v3.5","choices":[{"index":0,"delta":{"content":"The
                capital of Karnataka"},"finish_reason":null}]}


                data:
                {"id":"chatcmpl-6b1f4f0c2a5e4d8b","object":"chat.completion.chunk","created":1794390000,"model":"evon-v3.5","choices":[{"index":0,"delta":{"content":"
                is Bengaluru."},"finish_reason":"stop"}]}


                data: [DONE]
        '400':
          description: >-
            The request is invalid, too long, or was refused by the safety
            filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_request:
                  summary: A parameter is out of range
                  value:
                    error:
                      message: temperature must be between 0 and 2, got -1
                      type: invalid_request_error
                      param: null
                      code: invalid_request
                context_length_exceeded:
                  summary: The input is too long
                  value:
                    error:
                      message: The input is about 70120 tokens; the limit is 63488.
                      type: invalid_request_error
                      param: null
                      code: context_length_exceeded
                content_filter:
                  summary: Refused by the safety filters
                  value:
                    error:
                      message: The request was blocked by the input guardrails.
                      type: invalid_request_error
                      param: null
                      code: content_filter
        '401':
          description: The API key is missing or not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                detail:
                  error_code: MISSING_API_KEY
                  message: Missing API key
                  status_code: 401
        '403':
          description: The API key does not have access to the LLM API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GatewayError'
              example:
                detail:
                  error_code: SCOPE_NOT_ALLOWED
                  message: Service 'LLM' not in allowed scopes
                  status_code: 403
        '404':
          description: >-
            `model` is not a model this API serves. Send `evon-v3.5`, or leave
            out `model`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                model_not_found:
                  summary: Unknown model
                  value:
                    error:
                      message: '`model` is not a model this API serves.'
                      type: invalid_request_error
                      param: null
                      code: model_not_found
        '413':
          description: >-
            The body is over 10 MB, or the messages hold more than 1 MB of text.
            Send less text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                request_too_large:
                  summary: The request is too large
                  value:
                    error:
                      message: >-
                        The body is over 10 MB, or the messages hold more than 1
                        MB of text.
                      type: invalid_request_error
                      param: null
                      code: request_too_large
        '429':
          description: |
            A rate limit or the daily token quota was reached. Wait for the
            number of seconds in `Retry-After` when it is sent.
          headers:
            Retry-After:
              description: >-
                The number of seconds to wait before retrying. Sent on some
                `429` responses; when it is sent, wait at least that long.
              schema:
                type: integer
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GatewayError'
                  - $ref: '#/components/schemas/ErrorResponse'
              examples:
                rate_limited:
                  summary: Too many requests
                  value:
                    detail:
                      error_code: RATE_LIMITED
                      message: 'Request rate exceeded: at most 60 requests per minute.'
                      status_code: 429
                daily_quota:
                  summary: Daily token quota used up
                  value:
                    error:
                      message: >-
                        Daily token quota of 100000 tokens used up. It resets at
                        midnight IST.
                      type: rate_limit_error
                      param: null
                      code: daily_token_quota_exceeded
                web_search_limit_exceeded:
                  summary: Daily web searches used up
                  value:
                    error:
                      message: You have used today's web searches.
                      type: rate_limit_error
                      param: null
                      code: web_search_limit_exceeded
                model_overloaded:
                  summary: The model is busy
                  value:
                    error:
                      message: The model is busy.
                      type: rate_limit_error
                      param: null
                      code: model_overloaded
        '500':
          description: Something went wrong on our side. Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal error
                  value:
                    error:
                      message: Something went wrong on our side.
                      type: server_error
                      param: null
                      code: internal_error
        '502':
          description: >-
            The model could not be reached or could not serve the request. Retry
            with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                upstream_error:
                  summary: The model could not be reached
                  value:
                    error:
                      message: >-
                        The model could not be reached or could not serve the
                        request.
                      type: server_error
                      param: null
                      code: upstream_error
        '503':
          description: >-
            The safety check could not run, or web search is not available.
            Retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                guardrail_unavailable:
                  summary: The safety check could not run
                  value:
                    error:
                      message: >-
                        The safety check could not run, so the request was not
                        sent to the model.
                      type: server_error
                      param: null
                      code: guardrail_unavailable
                web_search_unavailable:
                  summary: Web search is not available
                  value:
                    error:
                      message: Web search is not available right now.
                      type: server_error
                      param: null
                      code: web_search_unavailable
        '504':
          description: >-
            The model did not respond in time. Retry, or ask for a shorter
            reply.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                upstream_timeout:
                  summary: The model did not finish in time
                  value:
                    error:
                      message: The model did not finish within the time limit.
                      type: server_error
                      param: null
                      code: upstream_timeout
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl https://api.vachana.ai/v1/chat/completions \
              -H "Content-Type: application/json" \
              -H "X-API-Key-ID: $GNANI_API_KEY" \
              -d '{
                "model": "evon-v3.5",
                "messages": [
                  {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
                  {"role": "user", "content": "What is the capital of Karnataka?"}
                ],
                "temperature": 0.3,
                "max_tokens": 512,
                "reasoning_effort": "none"
              }'
        - lang: python
          label: Python (OpenAI SDK)
          source: |
            import os
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.vachana.ai/v1",
                api_key=os.environ["GNANI_API_KEY"],
            )

            completion = client.chat.completions.create(
                model="evon-v3.5",
                messages=[
                    {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
                    {"role": "user", "content": "What is the capital of Karnataka?"},
                ],
                temperature=0.3,
                max_tokens=512,
                reasoning_effort="none",
            )

            choice = completion.choices[0]
            print(choice.message.content)
            if choice.finish_reason == "length":
                print("(the reply was cut short; raise max_tokens)")
            print(completion.usage)
        - lang: javascript
          label: JavaScript (OpenAI SDK)
          source: |
            import OpenAI from "openai";

            const client = new OpenAI({
              baseURL: "https://api.vachana.ai/v1",
              apiKey: process.env.GNANI_API_KEY,
            });

            const completion = await client.chat.completions.create({
              model: "evon-v3.5",
              messages: [
                { role: "system", content: "You are a helpful assistant. Answer in one or two sentences." },
                { role: "user", content: "What is the capital of Karnataka?" },
              ],
              temperature: 0.3,
              max_tokens: 512,
              reasoning_effort: "none",
            });

            const choice = completion.choices[0];
            console.log(choice.message.content);
            if (choice.finish_reason === "length") {
              console.log("(the reply was cut short; raise max_tokens)");
            }
            console.log(completion.usage);
        - lang: python
          label: Python (requests)
          source: |
            import os
            import requests

            response = requests.post(
                "https://api.vachana.ai/v1/chat/completions",
                headers={"X-API-Key-ID": os.environ["GNANI_API_KEY"]},
                json={
                    "model": "evon-v3.5",
                    "messages": [
                        {"role": "system", "content": "You are a helpful assistant. Answer in one or two sentences."},
                        {"role": "user", "content": "What is the capital of Karnataka?"},
                    ],
                    "temperature": 0.3,
                    "max_tokens": 512,
                    "reasoning_effort": "none",
                },
                timeout=300,
            )

            body = response.json()
            if response.ok:
                print(body["choices"][0]["message"]["content"])
            else:
                # LLM errors use {"error": {...}}; authentication and rate-limit errors use {"detail": {...}}
                error = body.get("error") or body.get("detail") or {}
                print(response.status_code, error.get("code") or error.get("error_code"), error.get("message"))
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - messages
      description: |
        Only `messages` is required. Every other field has a default.

        **Every value is checked before the model runs.** A value of the wrong
        type or out of range is refused with `400 invalid_request`, and the
        message names the field, for example
        `temperature must be between 0 and 2, got -1`. Sending `null` for a
        field means "use the default". Fields that are not listed here are
        ignored.
      properties:
        model:
          type: string
          default: evon-v3.5
          description: |
            The model to use. `evon-v3.5` is the only model; leave it out
            to use it. Another name returns `404 model_not_found`.
        messages:
          type: array
          minItems: 1
          description: |
            The conversation so far, oldest message first. At least one
            message. Send every turn on every request.
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
          description: |
            Send `true` to receive the reply as Server-Sent Events while the
            model writes it. See [Streaming](/api/LLM/streaming).
        stream_options:
          type: object
          description: Only allowed when `stream` is `true`.
          properties:
            include_usage:
              type: boolean
              default: false
              description: >-
                Add a last chunk, with an empty `choices` list, that carries
                token `usage`.
        max_tokens:
          type: integer
          minimum: 1
          maximum: 131072
          description: >
            The most tokens the reply may use, **thinking included**. From `1`

            up to your plan's maximum. If the reply reaches it, it is cut short
            and

            `finish_reason` is `length`.


            On Free and Pay-as-you-go plans the maximum is **1,024**, and a

            request without `max_tokens` gets 1,024. A larger value returns

            `400 invalid_request`

            (`max_tokens is 2048; the maximum for your plan is 1024.`). On

            Enterprise plans, the input plus `max_tokens` must fit in the

            128K-token (131,072) context window. See [Limits](/api/LLM/limits).
        max_completion_tokens:
          type: integer
          minimum: 1
          maximum: 131072
          description: Another name for `max_tokens`. If you send both, they must be equal.
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 0.6
          description: |
            How random the reply is, from `0` to `2`. Lower is more focused
            and repeatable; higher is more varied. Use low values (`0`–`0.3`)
            for factual answers, extraction and classification, and higher
            values for creative writing.
        top_p:
          type: number
          exclusiveMinimum: 0
          maximum: 1
          default: 0.95
          description: |
            Nucleus sampling, above `0` and up to `1`. The model picks only
            from the most likely tokens whose probabilities add up to `top_p`.
            Change `temperature` or `top_p`, not usually both.
        stop:
          description: |
            Up to 4 sequences where the model stops writing. The stop sequence
            is not included in the reply. Empty strings are refused.
          oneOf:
            - type: string
              minLength: 1
            - type: array
              maxItems: 4
              items:
                type: string
                minLength: 1
        seed:
          type: integer
          description: |
            Makes sampling repeatable: the same request with the same seed
            tends to give the same reply. It is not guaranteed.
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: >-
            From `-2` to `2`. Positive values make the model less likely to
            repeat the same words.
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          default: 0
          description: >-
            From `-2` to `2`. Positive values make the model more likely to move
            on to new topics.
        reasoning_effort:
          type: string
          enum:
            - none
            - minimal
            - low
            - medium
            - high
          description: |
            `none` turns thinking off. `minimal`, `low`, `medium` and `high`
            leave it on, and do not change how long the model thinks. See
            [Thinking](/api/LLM/thinking).
        enable_thinking:
          type: boolean
          default: true
          description: |
            Turns thinking on or off. If you send it with `reasoning_effort`,
            `enable_thinking` wins. Not part of OpenAI's API; with OpenAI's
            Python SDK, pass it in `extra_body`.
        reasoning_budget:
          type: integer
          minimum: 0
          maximum: 65536
          default: 32768
          description: |
            The most tokens the model may spend thinking, from `0` to `65536`.
            `0` sets no budget. Thinking also counts toward `max_tokens`. Not
            part of OpenAI's API; with OpenAI's Python SDK, pass it in
            `extra_body`.
        tools:
          type: array
          description: >
            Functions the model may ask you to run, each

            `{"type": "function", "function": {"name", "description",
            "parameters"}}`.

            `parameters` is a JSON Schema. See

            [Tool calling](/api/LLM/tool-calling).


            Add `{"type": "web_search"}` to let the model search the web. The

            service runs the searches itself. See

            [Web search](/api/LLM/web-search).
          items:
            $ref: '#/components/schemas/Tool'
        tool_choice:
          description: >
            Whether and which tool the model calls. Default `auto`.


            | Value | Meaning |

            | --- | --- |

            | `auto` | The model decides. |

            | `none` | The model does not call any tool. |

            | `required` | The model must call a tool. Allowed only when `tools`
            has exactly one tool. |

            | `{"type": "function", "function": {"name": "get_weather"}}` | The
            model must call this function. It must be in `tools`. |


            With `web_search` in `tools`, only `auto` and `none` are allowed.
          oneOf:
            - type: string
              enum:
                - auto
                - none
                - required
            - type: object
              required:
                - type
                - function
              properties:
                type:
                  type: string
                  const: function
                function:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
        parallel_tool_calls:
          type: boolean
          description: >-
            Whether the model may ask for more than one function call in one
            reply.
        response_format:
          description: >
            `{"type": "text"}` (the default), `{"type": "json_object"}` for a

            JSON reply, or

            `{"type": "json_schema", "json_schema": {"name": "...", "schema":
            {...}}}`

            for JSON that follows your schema. See

            [JSON output](/api/LLM/structured-outputs).
          oneOf:
            - type: object
              required:
                - type
              properties:
                type:
                  type: string
                  enum:
                    - text
                    - json_object
            - type: object
              required:
                - type
                - json_schema
              properties:
                type:
                  type: string
                  const: json_schema
                json_schema:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                    schema:
                      type: object
                    strict:
                      type: boolean
        top_k:
          type: integer
          minimum: -1
          default: 40
          description: >
            The model picks only from the `top_k` most likely next tokens.

            `-1` or `0` means no limit; otherwise a positive integer. Not part
            of OpenAI's

            API; with OpenAI's Python SDK, pass it in `extra_body`.
        min_p:
          type: number
          minimum: 0
          maximum: 1
          description: |
            From `0` to `1`. Leaves out tokens that are less likely than
            `min_p` times the most likely one. Not part of OpenAI's API; with
            OpenAI's Python SDK, pass it in `extra_body`.
        typical_p:
          type: number
          exclusiveMinimum: 0
          maximum: 1
          description: |
            Typical sampling, above `0` and up to `1`. `1` turns it off. Not
            part of OpenAI's API; with OpenAI's Python SDK, pass it in
            `extra_body`.
        repetition_penalty:
          type: number
          exclusiveMinimum: 0
          maximum: 2
          default: 1
          description: |
            Above `0` and up to `2`. Values above `1` discourage repetition;
            `1` turns it off. Not part of OpenAI's API; with OpenAI's Python
            SDK, pass it in `extra_body`.
        no_repeat_ngram_size:
          type: integer
          minimum: 0
          maximum: 20
          default: 0
          description: |
            From `0` to `20`. The reply never repeats a run of this many
            tokens. `0` turns it off. Not part of OpenAI's API; with OpenAI's
            Python SDK, pass it in `extra_body`.
        user:
          type: string
          description: An ID for your end user, for your own tracking.
    ChatCompletion:
      type: object
      required:
        - id
        - object
        - choices
      properties:
        id:
          type: string
        object:
          type: string
          const: chat.completion
        created:
          type: integer
          description: Unix time, in seconds.
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            required:
              - index
              - message
              - finish_reason
            properties:
              index:
                type: integer
              finish_reason:
                type:
                  - string
                  - 'null'
                description: '`stop`, `length`, `tool_calls` or `content_filter`.'
              message:
                type: object
                required:
                  - role
                properties:
                  role:
                    type: string
                    const: assistant
                  content:
                    type:
                      - string
                      - 'null'
                    description: The reply. `null` when the model only calls tools.
                  reasoning:
                    type:
                      - string
                      - 'null'
                    description: The model's thinking, when thinking is on.
                  tool_calls:
                    type:
                      - array
                      - 'null'
                    items:
                      $ref: '#/components/schemas/ToolCall'
                  web_search:
                    $ref: '#/components/schemas/WebSearchResult'
        usage:
          $ref: '#/components/schemas/Usage'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
            - type
            - code
          properties:
            message:
              type: string
            type:
              type: string
              enum:
                - invalid_request_error
                - rate_limit_error
                - server_error
            param:
              type:
                - string
                - 'null'
            code:
              type: string
    GatewayError:
      type: object
      description: Authentication and request-rate errors use this shape.
      properties:
        detail:
          type: object
          properties:
            error_code:
              type: string
            message:
              type: string
            status_code:
              type: integer
    ChatMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - system
            - developer
            - user
            - assistant
            - tool
          description: >
            Who wrote the message.


            | Value | Meaning |

            | --- | --- |

            | `system` | Your instructions for the whole conversation. Put it
            first. |

            | `developer` | Same as `system`. |

            | `user` | Your end user's message. |

            | `assistant` | One of the model's earlier replies. |

            | `tool` | The result of a function call. Needs `tool_call_id`. |
        content:
          description: |
            The text of the message. Send a string, or a non-empty list of
            text parts such as `[{"type": "text", "text": "Hello"}]`.

            Required on every message. The only exception is an `assistant`
            message that has `tool_calls`, where `content` may be left out or
            `null`. A message without `content` is refused with
            `400 invalid_request` (`messages[0].content is required`).
          oneOf:
            - type: string
            - type: array
              minItems: 1
              items:
                type: object
                required:
                  - type
                  - text
                properties:
                  type:
                    type: string
                    const: text
                  text:
                    type: string
            - type: 'null'
        name:
          type: string
          description: Optional name of the author, to tell participants apart.
        tool_calls:
          type: array
          description: |
            **Only on `assistant` messages.** The tool calls from the model's
            earlier reply, copied unchanged. See
            [Tool calling](/api/LLM/tool-calling).
          items:
            $ref: '#/components/schemas/ToolCall'
        tool_call_id:
          type: string
          description: |
            **Only on `tool` messages, where it is required.** The `id` of the
            tool call that this message answers.
    Tool:
      oneOf:
        - type: object
          required:
            - type
            - function
          properties:
            type:
              type: string
              const: function
            function:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                description:
                  type: string
                parameters:
                  type: object
                  description: A JSON Schema for the function's arguments.
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              const: web_search
    ToolCall:
      type: object
      required:
        - id
        - type
        - function
      properties:
        id:
          type: string
        type:
          type: string
          const: function
        function:
          type: object
          required:
            - name
            - arguments
          properties:
            name:
              type: string
            arguments:
              type: string
              description: >-
                The arguments as a JSON-encoded string, written by the model.
                Validate it before use.
    WebSearchResult:
      type: object
      description: Present when the model searched the web.
      properties:
        queries:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                description: The number the answer cites, as `[id]`.
              title:
                type: string
              url:
                type: string
              snippet:
                type: string
        remaining_today:
          type: integer
          description: Searches you have left today.
    Usage:
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      properties:
        prompt_tokens:
          type: integer
          description: Input tokens.
        completion_tokens:
          type: integer
          description: Output tokens, thinking included.
        total_tokens:
          type: integer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.