> For clean Markdown of any page, append `.md` to the page URL. > For a complete documentation index, see https://docs.sarvam.ai/llms.txt. > For full documentation content in one file, see https://docs.sarvam.ai/llms-full.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server. # Chat Completion V2 POST https://api.sarvam.ai/v2/chat/completions Content-Type: application/json Creates a model response for the given chat conversation, using an OpenAI-compatible request and response shape. Requires `api-subscription-key` with beta access to this endpoint. **Streaming is optional.** Default is one JSON response (`stream` omitted or `false`). Set `stream: true` for server-sent events; the stream ends with a `[DONE]` line. **Reasoning (`glm5.3`, `deepseekv4-flash`):** set `reasoning_effort` to **`low`**, **`high`**, or **`max`**. Default when omitted is **`max`** — omit the field or pass **`max`** for maximum reasoning. The trace is in `choices[].message.reasoning_content` and counts toward `max_tokens`. `gemma4` does not use reasoning on this route. Request fields documented on this operation are validated by the API. Other OpenAI-compatible fields may be forwarded to the model when sent. Legacy `functions` / `function_call` are rejected — use `tools` and `tool_choice`. Reference: https://docs.sarvam.ai/api-reference/chat/chat-completions-v2 ## Authentication - `api-subscription-key` header (required) — API Key authentication via header - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an object. - `messages` (list of object or object or object or object or object or object, required) — Non-empty conversation history. Roles: `system`, `developer`, `user`, `assistant`, `tool`. Content is a string or an array of parts (`text`, `image_url`). Images must use inline `data:image/…;base64,…` URLs — remote HTTP(S) image URLs are rejected. - ChatCompletionRequestSystemMessage - `content` (string, required) — The contents of the system message. - `role` ("system", required) — The role of the messages author, in this case `system`. - ChatCompletionRequestDeveloperMessage - `content` (string, required) — The contents of the developer message. - `role` ("developer", required) — The role of the messages author, in this case `developer`. - ChatCompletionRequestUserMessage - `role` ("user", required) — The role of the messages author, in this case `user`. - `content` (string or list of object, required) — The contents of the user message. - ChatCompletionRequestAssistantMessage - `role` ("assistant", required) — The role of the messages author, in this case `assistant`. - `content` (string, optional, nullable) — The contents of the assistant message - `tool_calls` (list of object, optional, nullable) — The tool calls generated by the model. - `id` (string, required) — Tool call id (for example `call-`). - `type` ("function", required) — The type of the tool call, currently only `function`. - `function` (object, required) - `name` (string, required) — The name of the function to call. - `arguments` (string, required) — The arguments to call the function with, as a JSON string. - ChatCompletionRequestToolMessage - `role` ("tool", required) — The role of the messages author, in this case `tool`. - `content` (string, required) — The contents of the tool message. - `tool_call_id` (string, required) — Tool call that this message is responding to. - ChatCompletionRequestGenericMessage - `role` (string, required) — The role of the messages author. - `content` (string or list of object, required) — The contents of the message. - `name` (string, optional, nullable) — An optional name for the participant. - `model` (enum, required) — Model IDs accepted by `POST /v2/chat/completions` (case-sensitive; unknown ids return `404`): - **`sarvam-105b`** — Sarvam flagship chat model. - **`glm5.3`** — 1,048,576-token context window; visible reasoning in `reasoning_content` (billed as completion tokens); tool calling; max request size 10,485,760 bytes; `n` must be `1`. - **`gemma4`** — image input (inline base64) and tool calling. - **`deepseekv4-flash`** — 1,048,576-token context window, tool calling, and reasoning. - Allowed values: `sarvam-105b`, `glm5.3`, `gemma4`, `deepseekv4-flash` - `temperature` (double, optional, nullable, default: 1) — Sampling temperature from `0` to `2`. Higher values increase variation; lower values focus the output. Output is not guaranteed to be identical across requests, even at `0`. Prefer changing either `temperature` or `top_p`, not both. - `top_p` (double, optional, nullable, default: 0.95) — Nucleus sampling: greater than `0` and at most `1`. On `glm5.3`, `top_p: 0` is rejected. Prefer changing either `top_p` or `temperature`, not both. - `reasoning_effort` (enum, optional, nullable) — On reasoning models (`glm5.3`, `deepseekv4-flash`): **`low`**, **`high`**, or **`max`**. Default when omitted is **`max`** — omit this field or set **`max`** for maximum reasoning. Trace in `message.reasoning_content`; billed as completion tokens and counts toward `max_tokens`. Ignored on non-reasoning models such as `gemma4`. - Allowed values: `low`, `high`, `max` - `max_tokens` (integer, optional, nullable, default: 2048) — Maximum tokens to generate in the completion, including reasoning tokens on reasoning models. Default `2048`. Set explicitly when you need longer answers — a low limit can yield `finish_reason: "length"` with little or no visible `content` if reasoning consumes the budget. - `stream` (boolean, optional, nullable, default: false) — Optional. Default `false` — omit or `false` for one JSON response. If `true`, the response is streamed as server-sent events and ends with a `[DONE]` line. Use `stream_options.include_usage: true` to receive a final usage chunk (including `reasoning_tokens`). That chunk has an empty `choices` array — do not assume `choices[0]` is present on every event. - `stop` (string or list of string, optional, nullable) — Up to 4 stop sequences (string or array). Generated text excludes the matched sequence. On `glm5.3`, more than four entries may return `503 model_overloaded` rather than `400`. - `n` (integer, optional, nullable, default: 1) — Number of chat completion choices to generate per request. You are billed for tokens across all choices. Default `1`. On `glm5.3`, only `n: 1` is accepted; higher values return `400 invalid_request_error`. - `seed` (integer, optional, nullable) — Optional integer seed for OpenAI SDK compatibility. - `frequency_penalty` (double, optional, nullable, default: 0) — Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim. - `presence_penalty` (double, optional, nullable, default: 0) — Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics. - `tools` (list of object, optional, nullable) — A list of tools the model may call. Currently, only functions are supported as a tool. - `type` ("function", required) — The type of the tool. Currently, only `function` is supported. - `function` (object, required) - `name` (string, required) — The name of the function to be called. - `description` (string, optional, nullable) — A description of what the function does. - `parameters` (map from string to any, optional, nullable) — The parameters the function accepts, described as a JSON Schema object. - `tool_choice` (enum or object, optional, nullable) — Controls tool calling: `auto`, `none`, `required`, or a named function object. `required` with an empty `tools` array returns `400`. A named function that is not listed in `tools` returns `400`. - ChatCompletionNamedToolChoice - `type` ("function", required) — The type of the tool. Currently, only `function` is supported. - `function` (object, required) - `name` (string, required) — The name of the function to call. - `response_format` (object, optional, nullable) — An object specifying the format that the model must output. Setting `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which guarantees the model generates output matching the supplied JSON Schema. Setting `{ "type": "json_object" }` enables the older JSON mode, which guarantees valid JSON but not a specific schema. - `type`: `json_object` (ResponseFormatJsonObject) - `type`: `json_schema` (ResponseFormatJsonSchema) - `json_schema` (object, required) — Structured Outputs configuration options, including a JSON Schema. - `name` (string, required) — The name of the response format. Must contain only alphanumeric characters, underscores and dashes. - `schema` (map from string to any, required) — The schema for the response format, described as a JSON Schema object. - `description` (string, optional, nullable) — A description of what the response format is for, used by the model to determine how to respond in the format. - `strict` (boolean, optional, nullable, default: false) — Whether to enable strict schema adherence when generating the output. - `type`: `text` (ResponseFormatText) - `extra_body` (map from string to any, optional, default: {}) — Additional model-specific options merged into the request. Must not duplicate a top-level field documented on this endpoint; duplicates return `400 invalid_request_error`. - `top_k` (integer, optional, nullable) — Top-k sampling. Omit or set to `-1` to disable. Values `>= 1` enable top-k; `0` is rejected. There is no documented upper bound. - `min_p` (double, optional, nullable) — Minimum probability mass. Must be between 0 and 1 inclusive. Outside that range is `400`. - `repetition_penalty` (double, optional, nullable) — Repetition penalty. Must be greater than 0 and at most 2. `0` and values above 2 are `400`. - `parallel_tool_calls` (boolean, optional, nullable) — **`false`** is correctly enforced (a single tool call) on **`gemma4`** and **`deepseekv4-flash`**. On **`glm5.3`** and **`sarvam-105b`**, **`false`** is accepted without error but is **not** enforced — the model may still return multiple tool calls in one turn. - `stream_options` (object, optional, nullable) — Only valid with `stream: true` (otherwise `400`). Must be a top-level field, not inside `extra_body`. Use `{"include_usage": true}` to receive token usage in the final SSE chunk. - `include_usage` (boolean, optional) — If `true`, a final SSE chunk includes `usage`, with `completion_tokens_details.reasoning_tokens` when applicable. That chunk has an empty `choices` array. - `logprobs` (boolean, optional, nullable) — If `true`, return log probabilities for output tokens (use with `top_logprobs`). Supported on **`sarvam-105b`** and **`gemma4`**. Not supported on **`glm5.3`** (`400` if enabled) or **`deepseekv4-flash`** (returns `503 model_overloaded` instead of a clean rejection — omit this field for that model). - `top_logprobs` (integer, optional, nullable) — How many top token log probabilities to return at each position when `logprobs` is `true` (otherwise **`400`**). Same model support as `logprobs`: works on `sarvam-105b` and `gemma4`; on `glm5.3` and `deepseekv4-flash`, omit entirely — do not send `0`, since many SDKs add it by default. ## Response ### 200 Successful Response - `id` (string, required) — A unique identifier for the chat completion. - `choices` (list of object, required) — A list of chat completion choices. Can be more than one if `n` is greater than 1. - `finish_reason` (enum, required) — 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, `content_filter` if content was omitted due to a flag from our content filters, `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function. - Allowed values: `stop`, `length`, `tool_calls`, `content_filter`, `function_call` - `index` (integer, required) — The index of the choice in the list of choices. - `message` (object, required) - `content` (string, required, nullable) — Assistant message text. May be `null` when `tool_calls` is present. - `role` (enum, required) — The role of the author of this message. - Allowed values: `assistant` - `refusal` (string, optional, nullable) - `reasoning_content` (string, optional, nullable) — Visible reasoning trace from the model, when supported. Billed as completion tokens. - `tool_calls` (list of object, optional, nullable) — The tool calls generated by the model. - `id` (string, required) — Tool call id (for example `call-`). - `type` ("function", required) — The type of the tool call, currently only `function`. - `function` (object, required) - `name` (string, required) — The name of the function to call. - `arguments` (string, required) — The arguments to call the function with, as a JSON string. - `logprobs` (map from string to any, optional, nullable) — Token log probabilities when supported (`sarvam-105b`, `gemma4`). Always `null` on `glm5.3` and `deepseekv4-flash`, which don't support this field. - `created` (integer, required) — The Unix timestamp (in seconds) of when the chat completion was created. - `model` (string, required) — The model used for the chat completion. - `object` ("chat.completion", required) — The object type, which is always `chat.completion`. - `service_tier` (string, optional, nullable) - `system_fingerprint` (string, optional, nullable) — OpenAI-compatible backend fingerprint when available. Always `null` on `glm5.3`. - `usage` (object, optional, nullable) - `completion_tokens` (integer, required) — Number of tokens in the generated completion. - `prompt_tokens` (integer, required) — Number of tokens in the prompt. - `total_tokens` (integer, required) — Total number of tokens used in the request (prompt + completion). - `completion_tokens_details` (object, optional, nullable) - `reasoning_tokens` (integer, optional, nullable) — Tokens spent on the chain-of-thought. Billed as completion / output tokens. - `prompt_tokens_details` (object, optional, nullable) — `null` on a cache miss. On a hit, includes `cached_tokens`. Treat a missing object and `cached_tokens: 0` as different when computing cache-hit rates. - `cached_tokens` (integer, optional) — Prompt tokens served from cache and billed at the cached-input rate. ## Errors ### 400 Bad Request Error Invalid request — wrong types or shapes in the JSON body (the gateway may return a serde-style message such as a field that expected a boolean receiving a string), unsupported parameters, model capability mismatch (e.g. image to a text-only model, remote image URL), or the context-window guard (prompt plus requested completion budget exceeds the model limit). The response includes `error.message` and, when present, `error.request_id` for support. - `any` ### 401 Unauthorized Error Missing or invalid API key — returned as 403 invalid_api_key_error in practice. - `any` ### 403 Forbidden Error Missing or invalid API key (`invalid_api_key_error`). - `any` ### 404 Not Found Error Unknown or wrongly cased model id (`not_found_error`). Model ids are case-sensitive. - `any` ### 413 Content Too Large Error Serialised request body larger than 10,485,760 bytes (10 MB), including text and inline image data. - `any` ### 429 Too Many Requests Error Rate limit exceeded, or account seat budget exhausted. - `any` ### 502 Bad Gateway Error The model backend could not be reached (`model_call_failed`). Retry the request. - `any` ### 503 Service Unavailable Error Model overloaded (`model_overloaded`). Retry with backoff. On `glm5.3`, more than four `stop` sequences may return `503` rather than `400` — client retry logic may treat that as transient overload. - `any` ## Examples **Request** ```json { "messages": [ { "content": "Summarise the causes of the 2008 financial crisis.", "role": "user" } ], "model": "glm5.3" } ``` **Response** ```json { "id": "20250101_0a1b2c3d-1234-5678-9abc-def012345678", "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "The 2008 financial crisis was driven by a housing bubble, subprime lending, and the collapse of mortgage-backed securities.", "role": "assistant", "refusal": null, "reasoning_content": null, "tool_calls": null }, "logprobs": {} } ], "created": 1735689600, "model": "glm5.3", "object": "chat.completion", "system_fingerprint": null, "usage": { "completion_tokens": 24, "prompt_tokens": 18, "total_tokens": 42, "completion_tokens_details": { "reasoning_tokens": 10 }, "prompt_tokens_details": { "cached_tokens": 0 } } } ``` **SDK Code** ```typescript chat_completionsV2_example import { SarvamAIClient } from "sarvamai"; async function main() { const client = new SarvamAIClient({ apiSubscriptionKey: "YOUR_API_KEY_HERE", }); await client.chat.completionsV2({ messages: [ { content: "Summarise the causes of the 2008 financial crisis.", role: "user", }, ], model: "glm5.3", }); } main(); ``` ```python chat_completionsV2_example from sarvamai import SarvamAI client = SarvamAI( api_subscription_key="YOUR_API_KEY_HERE", ) client.chat.completions_v2( messages=[ { "content": "Summarise the causes of the 2008 financial crisis.", "role": "user" } ], model="glm5.3", ) ``` ```go chat_completionsV2_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.sarvam.ai/v2/chat/completions" payload := strings.NewReader("{\n \"messages\": [\n {\n \"content\": \"Summarise the causes of the 2008 financial crisis.\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"glm5.3\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("api-subscription-key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby chat_completionsV2_example require 'uri' require 'net/http' url = URI("https://api.sarvam.ai/v2/chat/completions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["api-subscription-key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"messages\": [\n {\n \"content\": \"Summarise the causes of the 2008 financial crisis.\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"glm5.3\"\n}" response = http.request(request) puts response.read_body ``` ```java chat_completionsV2_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.sarvam.ai/v2/chat/completions") .header("api-subscription-key", "") .header("Content-Type", "application/json") .body("{\n \"messages\": [\n {\n \"content\": \"Summarise the causes of the 2008 financial crisis.\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"glm5.3\"\n}") .asString(); ``` ```php chat_completionsV2_example request('POST', 'https://api.sarvam.ai/v2/chat/completions', [ 'body' => '{ "messages": [ { "content": "Summarise the causes of the 2008 financial crisis.", "role": "user" } ], "model": "glm5.3" }', 'headers' => [ 'Content-Type' => 'application/json', 'api-subscription-key' => '', ], ]); echo $response->getBody(); ``` ```csharp chat_completionsV2_example using RestSharp; var client = new RestClient("https://api.sarvam.ai/v2/chat/completions"); var request = new RestRequest(Method.POST); request.AddHeader("api-subscription-key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"messages\": [\n {\n \"content\": \"Summarise the causes of the 2008 financial crisis.\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"glm5.3\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift chat_completionsV2_example import Foundation let headers = [ "api-subscription-key": "", "Content-Type": "application/json" ] let parameters = [ "messages": [ [ "content": "Summarise the causes of the 2008 financial crisis.", "role": "user" ] ], "model": "glm5.3" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/v2/chat/completions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```