Skip to main content
Early accessGnani Evon v3.5 is now available as an API to early access registrants.

Overview

The SDK has two clients for the Chat Completions API, one blocking and one for asyncio. They are built on the openai package, so you call them the way you call OpenAI’s Python SDK. They add the Gnani defaults: the base URL, your GNANI_API_KEY, and the headers the Gnani API reads.
The PyPI package is gnani-vachana, but the Python import package is gnani. Install gnani-vachana, then from gnani.llm import ....

Installation

The LLM clients need the openai package. It is not installed with the base SDK, so ask for the llm extra:
Requirements: Python 3.9+, and openai 1.40 or later (the extra installs it). Speech-to-Text and Text-to-Speech do not need the extra. If you import gnani.llm without it, Python raises:

Authentication

Create a key in the Gnani API dashboard. The key must have access to the LLM API; a key without it gets 403 SCOPE_NOT_ALLOWED. Set it as an environment variable. Both clients read it automatically:
If there is no key, the constructor raises an error before any network call.
The key is read from GNANI_API_KEY only, never from OPENAI_API_KEY. An OpenAI key in your environment is never sent to Gnani.

Your first request

model defaults to evon-v3.5, the model the API serves, so you can leave it out. The examples on this page set it explicitly. Any other model name fails with 404 model_not_found.
The model thinks before it answers, by default. Thinking counts toward max_tokens, so a short reply can come back with empty content and finish_reason: "length". The examples send reasoning_effort="none" to turn thinking off. See Thinking.

Streaming

stream is False unless you set it. With stream=True the sync client returns an iterator and the async client returns an async iterator.
stream_options is accepted only with stream=True; without it the API returns 400 invalid_request. See Streaming for the event format.

Parameters

Every parameter on the Chat Completions page works with both clients. What changes is how you pass it.

Parameters OpenAI also has

Pass these as normal keyword arguments: messages, model, stream, stream_options, max_tokens, max_completion_tokens, temperature, top_p, stop, seed, frequency_penalty, presence_penalty, reasoning_effort, tools, tool_choice, parallel_tool_calls, response_format and user.

Gnani-only parameters

These are not part of OpenAI’s API, so openai’s method signature does not have them. Pass them in extra_body, as a dictionary. The SDK sends them with the rest of the request. The built-in web search is a tool, so it needs no extra_body: tools=[{"type": "web_search"}]. See Web search.
Passing a Gnani-only field as a keyword argument, for example top_k=50, raises TypeError: unexpected keyword argument. Put it in extra_body.
The SDK does not check values. The API does, and answers 400 invalid_request with a message that names the field. A field name it does not know, such as a typo like topk, is refused with 400 unknown_parameter.

Not supported

n greater than 1 and image content parts are refused with 400. logprobs, top_logprobs, logit_bias, modalities, prediction, store, metadata and service_tier are accepted and ignored. See Migrating from OpenAI.

Thinking

When thinking is on, the model’s reasoning comes back apart from the answer, in message.reasoning. It is not in OpenAI’s typed response, but the SDK keeps it, so you read it as an attribute:
While streaming, thinking arrives in chunk.choices[0].delta.reasoning, before the answer’s content. Because delta is typed by openai, read it with getattr(delta, "reasoning", None). See Thinking for how it counts toward max_tokens and when to turn it off.

Tool calling

Tool calling is the standard OpenAI shape. Both clients take tools and tool_choice, and return message.tool_calls.
Run the function, then send its result back as a tool message. The full loop is in Tool calling. With the async client, await the call and everything else is the same.

Error handling

Errors are openai exceptions, so you can catch them the way you do for OpenAI. e.status_code is the HTTP status and e.code is the error code, for example invalid_request or invalid_api_key.
The two error shapes, and the codes, are on the Errors page. The clients retry connection errors, 408, 409, 429 and 5xx twice by default; change that with max_retries.

Other options

Both clients take every openai constructor option. The ones you will use most:
The client sends your key in both X-API-Key-ID and Authorization: Bearer. Headers you pass in default_headers win.

Further reading

Chat Completions reference

Every request parameter and the response objects.

Migrating from OpenAI

What works as in OpenAI, what differs, and the Gnani-only options.

Streaming

The event format and stream errors.

Errors

Both error shapes and every code.