Skip to main content
POST
Early accessGnani 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. New to the API? Start with the Overview.

Endpoint


Authentication

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

Request body

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.

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

Response

The chat completion object

Without streaming (the default), the response is 200 OK with Content-Type: application/json:
string
An ID for this completion.
string
Always chat.completion.
integer
When the reply was created, in Unix seconds.
string
The model that wrote the reply.
object[]
Always one choice.
object
Tokens used by this request. See the usage object.
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.

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]:
string
An ID for this completion.
string
Always chat.completion.chunk.
integer
When the reply was created, in Unix seconds.
string
The model that wrote the reply.
object[]
One choice, or an empty list on the last usage chunk.
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.
How to read the stream, and what happens when it fails part-way, is on the Streaming page.

The usage object

integer
Input tokens.
integer
Output tokens, thinking included.
integer
Total tokens.
These are the numbers counted against your daily quota. 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

string
The call’s ID. Send it back as tool_call_id on the tool message that holds the result.
string
Always function.
object
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:
string[]
The searches the model ran, in order.
object[]
Every result the model was given. Numbering runs across all searches in the request.
integer
How many searches you have left today.
When streaming, delta.web_search reports each search as it happens:
string
string
What is being searched.
object[]
On completed: the results, with the same fields as above.
integer
On completed: the searches left today.

Response headers


Errors

Error codes, shapes and what to do about each are on the Errors page.

Retrying

Which errors to retry, and how, is in Errors: Retrying.

Code examples


Differences from OpenAI

How this API differs from OpenAI’s Chat Completions API is on the OpenAI compatibility page.

Authorizations

X-API-Key-ID
string
header
required

Headers

X-API-Key-ID
string
required

Your Gnani API key. You can send it as Authorization: Bearer <key> instead.

X-API-Request-ID
string

Your own ID for this request. It is returned in the X-API-Request-ID response header.

Body

application/json

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.

messages
object[]
required

The conversation so far, oldest message first. At least one message. Send every turn on every request.

Minimum array length: 1
model
string
default:evon-v3.5

The model to use. evon-v3.5 is the only model; leave it out to use it. Another name returns 404 model_not_found.

stream
boolean
default:false

Send true to receive the reply as Server-Sent Events while the model writes it. See Streaming.

stream_options
object

Only allowed when stream is true.

max_tokens
integer

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.

Required range: 1 <= x <= 131072
max_completion_tokens
integer

Another name for max_tokens. If you send both, they must be equal.

Required range: 1 <= x <= 131072
temperature
number
default:0.6

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.

Required range: 0 <= x <= 2
top_p
number
default:0.95

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.

Required range: x <= 1
stop

Up to 4 sequences where the model stops writing. The stop sequence is not included in the reply. Empty strings are refused.

Minimum string length: 1
seed
integer

Makes sampling repeatable: the same request with the same seed tends to give the same reply. It is not guaranteed.

frequency_penalty
number
default:0

From -2 to 2. Positive values make the model less likely to repeat the same words.

Required range: -2 <= x <= 2
presence_penalty
number
default:0

From -2 to 2. Positive values make the model more likely to move on to new topics.

Required range: -2 <= x <= 2
reasoning_effort
enum<string>

none turns thinking off. minimal, low, medium and high leave it on, and do not change how long the model thinks. See Thinking.

Available options:
none,
minimal,
low,
medium,
high
enable_thinking
boolean
default:true

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
integer
default:32768

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.

Required range: 0 <= x <= 65536
tools
object[]

Functions the model may ask you to run, each {"type": "function", "function": {"name", "description", "parameters"}}. parameters is a JSON Schema. See Tool calling.

Add {"type": "web_search"} to let the model search the web. The service runs the searches itself. See Web search.

tool_choice

Whether and which tool the model calls. Default auto.

With web_search in tools, only auto and none are allowed.

Available options:
auto,
none,
required
parallel_tool_calls
boolean

Whether the model may ask for more than one function call in one reply.

response_format
object

{"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.

top_k
integer
default:40

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.

Required range: x >= -1
min_p
number

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.

Required range: 0 <= x <= 1
typical_p
number

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.

Required range: x <= 1
repetition_penalty
number
default:1

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.

Required range: x <= 2
no_repeat_ngram_size
integer
default:0

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.

Required range: 0 <= x <= 20
user
string

An ID for your end user, for your own tracking.

Response

application/json (a chat.completion object) by default, or text/event-stream (chat.completion.chunk events ending in data: [DONE]) when stream is true.

id
string
required
object
string
required
Allowed value: "chat.completion"
choices
object[]
required
created
integer

Unix time, in seconds.

model
string
usage
object