> 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

## 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` (string or list of object or object, 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` (false, 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 object, 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).
  - `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)
- `tool_choice` (enum or object or map from string to any, optional, nullable) — Forwarded exactly as written: `none`, `auto`, `required`, `{ "type": "function", "name": "..." }`, or another object.
- `reasoning` (object, 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`.
  - `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`
- `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` (object, 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.
  - `format` (object, required) — `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)
- `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` (string or map from string to any, 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

- `id` (string, required) — Rewritten to this service's request id. The id is for logs and `x-request-id`; responses are not stored for retrieval.
- `object` ("response", required)
- `model` (string, required) — Rewritten to the public model id the caller asked for.
- `output` (list of object or object, required) — Typed output items from the backend — messages, reasoning, function calls, and vendor extras.
  - ResponseOutputMessage
    - `type` ("message", required)
    - `role` (string, required) — Usually `assistant`.
    - `id` (string, optional)
    - `status` (string, optional)
    - `content` (list of object, optional)
      - `type` ("output_text", required)
      - `text` (string, required)
  - ResponsePassThroughItem
    - `type` (string, optional) — Item type, e.g. `function_call`, `function_call_output`, `reasoning`. `item_reference` is `400`.
- `created_at` (double, optional) — Unix timestamp (seconds) when the response was created. Returned as a float (e.g. `1789632469.0`), not an integer.
- `status` (string, optional) — Typically `completed`, `incomplete`, or `failed`. Corrected to `incomplete` with `incomplete_details.reason: max_output_tokens` when the caller set `max_output_tokens`, the backend reported `output_tokens >= max_output_tokens`, `status` was `completed`, and `incomplete_details` was absent.
- `incomplete_details` (object, optional, nullable)
  - `reason` (string, optional) — Why generation stopped early, e.g. `max_output_tokens`.
- `error` (object, optional, nullable)
  - `message` (string, optional)
  - `code` (string, optional) — Machine-readable code, e.g. `invalid_request_error`, `not_found_error`.
  - `request_id` (string, optional)
  - `param` (string, optional, nullable) — Present when a field was named.
  - `spend_limits` (map from string to any, optional, nullable) — Present only on a 429 from an exhausted seat budget.
- `usage` (object, optional, nullable)
  - `input_tokens` (integer, optional)
  - `output_tokens` (integer, optional)
  - `total_tokens` (integer, optional)
  - `input_tokens_details` (object, optional)
    - `cached_tokens` (integer, optional) — Prompt tokens served from cache on `glm5.3`. Always present in `input_tokens_details`; **`0`** on a cache miss. Billed at the cached-input rate when non-zero.
  - `output_tokens_details` (object, optional)
    - `reasoning_tokens` (integer, optional) — Tokens spent on the chain-of-thought. Billed as output tokens.
- `temperature` (double, optional, nullable) — Echoed back from the request.
- `top_p` (double, optional, nullable) — Echoed back from the request.
- `tools` (list of object, optional, nullable) — Echoed back from the request.
  - `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)
- `tool_choice` (enum or object or map from string to any, optional, nullable) — Echoed back from the request.
- `instructions` (string, optional, nullable) — Echoed back from the request when set.
- `store` (boolean, optional, nullable) — Echoed back from the request. Always `false` — nothing created by this endpoint is retrievable.
- `parallel_tool_calls` (boolean, optional, nullable) — Echoed from the request as sent — see the request field description for actual enforcement behavior.
- `max_output_tokens` (integer, optional, nullable) — Echoed back from the request.
- `service_tier` (string, optional, nullable) — OpenAI-compatible service-tier field, present for schema parity. Observed value: `"auto"`.
- `background` (boolean, optional, nullable) — Echoed back from the request. `true` is `400` — see the request field.
- `completed_at` (double, optional, nullable) — Unix timestamp (seconds, float) when generation finished. `null` while incomplete or failed.
- `conversation` (string or map from string to any, optional, nullable) — Echoed back from the request.
- `max_tool_calls` (integer, optional, nullable) — Echoed back from the request. Always `400` if set — not supported by any serving deployment.
- `metadata` (map from string to any, optional) — Not in the documented request schema, but accepted and echoed back. Defaults to `{}`.
- `previous_response_id` (string, optional, nullable) — Echoed back from the request. Always `400` if set — this endpoint holds no state.
- `reasoning` (object, optional, nullable) — Echoed back from the request.
  - `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`
- `text` (object, optional, nullable) — Echoed back from the request.
  - `format` (object, required) — `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)
- `presence_penalty` (double, optional, nullable) — Not in the documented request schema, but accepted and echoed back. Observed default: `0`. Behavior on this route is otherwise unverified.
- `frequency_penalty` (double, optional, nullable) — Not in the documented request schema, but accepted and echoed back. Observed default: `0`. Behavior on this route is otherwise unverified.
- `prompt` (map from string to any, optional, nullable) — Not in the documented request schema. Accepted and echoed back; behavior otherwise unverified.
- `prompt_cache_key` (string, optional, nullable) — Not in the documented request schema. Accepted and echoed back; behavior otherwise unverified.
- `prompt_cache_retention` (string, optional, nullable) — Not in the documented request schema. Accepted and echoed back; behavior otherwise unverified.
- `safety_identifier` (string, optional, nullable) — Not in the documented request schema. Accepted and echoed back; behavior otherwise unverified.
- `top_logprobs` (integer, optional, nullable) — Not in the documented request schema. Accepted and echoed back. Observed default: `0`; behavior otherwise unverified.
- `truncation` (string, optional, nullable) — Not in the documented request schema. Accepted and echoed back. Observed default: `"disabled"`; behavior otherwise unverified.
- `user` (string, optional, nullable) — Not in the documented request schema. Accepted and echoed back; behavior otherwise unverified.
- `billing` (map from string to any, optional, nullable) — Reserved — always observed as `null` in testing. Shape not yet defined; do not rely on this field.

## 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`

## Examples

**Request**

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

**SDK Code**

```typescript responses_create_example
import { SarvamAIClient } from "sarvamai";

async function main() {
    const client = new SarvamAIClient({
        apiSubscriptionKey: "YOUR_API_KEY_HERE",
    });
    await client.responses.createStream({
        model: "glm5.3",
        input: "Summarise the causes of the 2008 financial crisis.",
        stream: false,
        store: false,
    });
}
main();

```

```python responses_create_example
from sarvamai import SarvamAI

client = SarvamAI(
    api_subscription_key="YOUR_API_KEY_HERE",
)

client.responses.create_stream(
    model="glm5.3",
    input="Summarise the causes of the 2008 financial crisis.",
    store=False,
)

```

```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\": false,\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\": false,\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\": false,\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": false,
  "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\": false,\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": false,
  "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()
```