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

# Create Response

POST https://api.sarvam.ai/v2/responses
Content-Type: application/json

Generate a model reply in the OpenAI Responses format.

**Models:** `sarvam-105b`, `glm5.3`, `gemma4`, and `deepseekv4-flash` (ids are case-sensitive).

**Each call is independent.** Send the full conversation in `input` every time — nothing is stored for you. Leave out `store` or set it to `false` (`true` returns **`400`**). You cannot load a past response by id (`GET /v2/responses/{id}` is always **`404`**).

**Streaming is optional.** Default is a single JSON body (`stream` omitted or `false`). Set `stream: true` only if you want server-sent events.

**Reasoning (`glm5.3`, `deepseekv4-flash`):** both support `low`, `high`, and `max`. On `glm5.3`, `reasoning.effort` only accepts **`low`** or **`high`** — omit `reasoning` / `effort` for **`max`**-level reasoning, since sending the literal string **`"max"`** returns **`400`**. On `deepseekv4-flash`, all three values including `max` work directly. On `glm5.3`, read the trace from the reasoning item's `summary[0].text`. Reasoning tokens count toward `max_output_tokens`, which has no default cap — omitting it means unbounded generation.

Other fields are documented below. See the [Responses API guide](/api/api-guides-tutorials/chat-completion/responses-api).

Reference: https://docs.sarvam.ai/api-reference/responses/create-stream

## Authentication

- `api-subscription-key` header (required) — API Key authentication via header
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an object.

- `model` (enum, required) — Model IDs accepted by `POST /v2/responses` (case-sensitive; unknown ids return `404`): - **`sarvam-105b`** — Sarvam flagship model. - **`glm5.3`** — 1,048,576-token context; reasoning in `output` as a `reasoning` item; flat function tools; max request size 10,485,760 bytes. - **`gemma4`** — vision (inline base64 images) and tools. - **`deepseekv4-flash`** — long context, tools, and reasoning.
  - Allowed values: `sarvam-105b`, `glm5.3`, `gemma4`, `deepseekv4-flash`
- `input` (ResponseInput, required) — A prompt string, or the conversation so far as a list of items. Replay the full list on every request because this endpoint does not store prior turns.
- `stream` (true, required) — Optional. Default `false` — same as chat completions. Omit or `false` for one JSON response body. Set `true` to stream named server-sent events. There is no `[DONE]` sentinel — the stream ends on `response.completed`, `response.incomplete`, or `response.failed`.
- `max_output_tokens` (integer, optional, nullable) — Maximum output tokens to generate, including reasoning tokens on reasoning models. If omitted, there is no default cap — generation is unbounded and continues until the model stops on its own or the context window fills. Always set this explicitly in production. Values above the model context window return `400`.
- `temperature` (double, optional, nullable, default: 1) — Sampling temperature between 0 and 2. Default **`1`** on `glm5.3` when omitted. Output is not bit-reproducible, even at `0`.
- `store` (boolean, optional, nullable) — Must be `false` or omitted (omitting is `200` and echoed as `false`). `true` is `400 invalid_request_error` — nothing created here is retrievable. OpenAI SDKs default this to `true`, so a default `client.responses.create(...)` fails.
- `tools` (list of ResponseFunctionTool, optional, nullable) — Function tools use the **flat** Responses shape (`type`, `name`, `parameters`, `strict`) — the nested chat-completions tool shape is **`400`**. `tool_choice: required` with no tools returns **`400`**. Function `arguments` in output are a JSON **string** (parse before use). Multiple tool calls per turn are supported; use **`parallel_tool_calls: true`** or omit (see that field).
- `tool_choice` (V2ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice, optional, nullable) — Forwarded exactly as written: `none`, `auto`, `required`, `{ "type": "function", "name": "..." }`, or another object.
- `reasoning` (ResponseReasoning, optional, nullable) — Optional reasoning config for `glm5.3` and `deepseekv4-flash`. On `glm5.3`, a reasoning item is always in `output` — read `summary[0].text`. **`effort`:** on `glm5.3`, `low` or `high` only — omit for `max`-level reasoning (the literal string `max` returns `400`); on `deepseekv4-flash`, `low`, `high`, or `max` all work directly. Optional **`summary`:** `auto` or `detailed`.
- `extra_body` (map from string to any, optional, default: {}) — Merged into the outbound body. Must not overwrite any modelled field (`400`). `max_tool_calls` and `prompt` are `400` here and in `extra_body` — not supported by any serving deployment.
- `instructions` (string, optional, nullable) — System-style instructions. Echoed back on the response object when set.
- `top_p` (double, optional, nullable, default: 0.95) — Nucleus sampling. Default **`0.95`** on `glm5.3` when omitted. Must be greater than **`0`** and at most **`1`** (`0` is rejected on `glm5.3`).
- `top_k` (integer, optional, nullable) — Top-k sampling on `glm5.3`. Omit or use **`-1`** to disable; values **`≥ 1`** enable top-k. **`0`** is rejected.
- `frequency_penalty` (double, optional, nullable) — Optional. Range `-2` to `2`. May be accepted and echoed on Responses without changing model output.
- `presence_penalty` (double, optional, nullable) — Optional. Range `-2` to `2`. May be accepted and echoed on Responses without changing model output.
- `text` (ResponseTextConfig, optional, nullable) — Output format. If you send `text`, `format` is required (`400` when missing). `json_object` and strict `json_schema` are honoured on `glm5.3` and skip the reasoning item.
- `parallel_tool_calls` (boolean, optional, nullable) — Not currently enforced on this route for any model that supports tool calling here (`glm5.3`, `gemma4`, `deepseekv4-flash`). Setting **`false`** is accepted without error, but the model may still return multiple tool calls in one turn.
- `n` (integer, optional, nullable) — **Ignored** on this route — Responses always returns one output. Accepted for OpenAI SDK compatibility only; omit or leave at `1`.
- `seed` (integer, optional, nullable) — **Ignored** on Responses. Accepted for SDK compatibility only.
- `previous_response_id` (string, optional, nullable) — `400 invalid_request_error`. This endpoint holds no state — replay the conversation in `input`. OpenAI and Fireworks use this to continue a chat; we do not.
- `conversation` (ResponseConversation, optional) — Conversation state is not supported. Omit this field and replay the complete conversation in `input`.
- `background` (boolean, optional, nullable) — `true` is `400 invalid_request_error`. This endpoint is synchronous only.
- `max_tool_calls` (integer, optional, nullable) — `400 invalid_request_error` — not supported by any serving deployment, top-level or via `extra_body`.

## Response

### 200

- Streaming response of `ResponseStreamEvent`.
- `type` (string, required) — The event type.

## Errors

### 400 Bad Request Error

Invalid or refused request — unsupported parameter values, stateful fields such as `store: true`, `background: true`, `previous_response_id`, `conversation`, `max_tool_calls`, `prompt`, or `item_reference`, capability mismatch, or context-window guard (input plus `max_output_tokens` exceeds the model limit). Response body includes `error.message` and, when present, `error.request_id`.

- `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`), or `GET /v2/responses/{id}` when retrieval is not supported.

- `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 (`rate_limit_exceeded_error` or `model_rate_limit_exceeded_error`).

- `any`

### 502 Bad Gateway Error

The model request failed (`model_call_failed`). Retry the request; contact support if the error persists.

- `any`

### 503 Service Unavailable Error

Model overloaded (`model_overloaded`).

- `any`

## Types

### ResponseInput

A prompt string, or the conversation so far as a list of items. Replay the full list on every request because this endpoint does not store prior turns.

### ResponseFunctionTool

- `type` (string, required) — Tool type. Function tools use `function`.
- `name` (string, required) — The function name.
- `description` (string, optional, nullable)
- `parameters` (map from string to any, optional, nullable) — JSON Schema for the function arguments.
- `strict` (boolean, optional, nullable)

### V2ResponsesPostRequestBodyContentApplicationJsonSchemaToolChoice

Forwarded exactly as written: `none`, `auto`, `required`, `{ "type": "function", "name": "..." }`, or another object.

### ResponseReasoning

- `effort` (enum, optional, nullable) — `low`, `high`, or `max`. On **`glm5.3`** specifically, sending the literal string `max` returns `400` — omit the field instead to get `max`-level reasoning. **`deepseekv4-flash`** accepts `max` directly on this route.
  - Allowed values: `low`, `high`, `max`
- `summary` (enum, optional, nullable) — `auto` or `detailed`. A reasoning item is returned on `glm5.3` even when this is omitted.
  - Allowed values: `auto`, `detailed`

### ResponseTextConfig

- `format` (ResponseTextFormat, required) — `type` is `text`, `json_object`, or `json_schema`. For `json_schema`, supply `name`, `schema`, and optionally `strict`.

### ResponseConversation

Conversation state is not supported. Omit this field and replay the complete conversation in `input`.

### ResponseTextFormat

`type` is `text`, `json_object`, or `json_schema`. For `json_schema`, supply `name`, `schema`, and optionally `strict`.

- `type` (enum, required)
  - Allowed values: `text`, `json_object`, `json_schema`
- `name` (string, optional)
- `strict` (boolean, optional, nullable)
- `schema` (map from string to any, optional)

## Examples

**Request**

```json
{
  "model": "glm5.3",
  "input": "Summarise the causes of the 2008 financial crisis.",
  "stream": true,
  "store": false
}
```

**SDK Code**

```python responses_create_example
import requests

url = "https://api.sarvam.ai/v2/responses"

payload = {
    "model": "glm5.3",
    "input": "Summarise the causes of the 2008 financial crisis.",
    "stream": True,
    "store": False
}
headers = {
    "api-subscription-key": "<apiSubscriptionKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript responses_create_example
const url = 'https://api.sarvam.ai/v2/responses';
const options = {
  method: 'POST',
  headers: {
    'api-subscription-key': '<apiSubscriptionKey>',
    'Content-Type': 'application/json'
  },
  body: '{"model":"glm5.3","input":"Summarise the causes of the 2008 financial crisis.","stream":true,"store":false}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go responses_create_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sarvam.ai/v2/responses"

	payload := strings.NewReader("{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"stream\": true,\n  \"store\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("api-subscription-key", "<apiSubscriptionKey>")
	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 responses_create_example
require 'uri'
require 'net/http'

url = URI("https://api.sarvam.ai/v2/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["api-subscription-key"] = '<apiSubscriptionKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"stream\": true,\n  \"store\": false\n}"

response = http.request(request)
puts response.read_body
```

```java responses_create_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.sarvam.ai/v2/responses")
  .header("api-subscription-key", "<apiSubscriptionKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"stream\": true,\n  \"store\": false\n}")
  .asString();
```

```php responses_create_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.sarvam.ai/v2/responses', [
  'body' => '{
  "model": "glm5.3",
  "input": "Summarise the causes of the 2008 financial crisis.",
  "stream": true,
  "store": false
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'api-subscription-key' => '<apiSubscriptionKey>',
  ],
]);

echo $response->getBody();
```

```csharp responses_create_example
using RestSharp;

var client = new RestClient("https://api.sarvam.ai/v2/responses");
var request = new RestRequest(Method.POST);
request.AddHeader("api-subscription-key", "<apiSubscriptionKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"glm5.3\",\n  \"input\": \"Summarise the causes of the 2008 financial crisis.\",\n  \"stream\": true,\n  \"store\": false\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift responses_create_example
import Foundation

let headers = [
  "api-subscription-key": "<apiSubscriptionKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "model": "glm5.3",
  "input": "Summarise the causes of the 2008 financial crisis.",
  "stream": true,
  "store": false
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sarvam.ai/v2/responses")! 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()
```