> For the complete documentation index, see [/llms.txt](/llms.txt).

> Source: /api/responses

# Responses API

## Compatibility with OpenAI

This API is OpenAI-compatible, but key differences exist in parameters, features, and behaviors. Requests process only the parameters listed on this page. Any other OpenAI parameters are accepted and ignored.

Key differences:

- **Unsupported parameters**: `previous_response_id`, `conversation`, `background`, `store: true`, and non-text content parts (`input_image`, `input_file`) are rejected — this API is stateless and text-only. See the [conversation guide](/docs/capabilities/generate/chat#using-the-responses-api).
- **Additional parameters**: Supports `frequency_penalty` beyond OpenAI's spec.

OpenAPI spec: `./openapi/openapi.yaml`

- `POST /responses`

### Response

**Return values**

Returns a `response` object, or a stream of Server-Sent Events if `stream` is `true`.

**The response object**

<table><tbody><tr><td><strong>id</strong> string<br />A unique identifier for the response, prefixed with <code>resp\_</code>.</td></tr><tr><td><strong>object</strong> string<br />The object type, which is always <code>response</code>.</td></tr><tr><td><strong>created\_at</strong> integer<br />The Unix timestamp (in seconds) of when the response was created.</td></tr><tr><td><strong>status</strong> string<br /><code>completed</code> when the model finished normally, <code>incomplete</code> when generation stopped at <code>max\_output\_tokens</code>. Streaming responses also use <code>in\_progress</code> while generation is running and <code>failed</code> for a mid-stream error.</td></tr><tr><td><strong>model</strong> string<br />The model identifier returned by the model backend for non-streaming responses. Streaming responses echo the requested model identifier, for example <code>solar-pro4</code>.</td></tr><tr><td><strong>output</strong> list<br />An ordered list of output items. A <code>reasoning</code> item comes first when reasoning is on, followed by the assistant <code>message</code> and any <code>function\_call</code> items.</td></tr><tr><td><strong>output\[].type</strong> string<br /><code>reasoning</code>, <code>message</code>, or <code>function\_call</code>.</td></tr><tr><td><strong>output\[].id</strong> string<br />A unique identifier for the output item.</td></tr><tr><td><strong>output\[].status</strong> string<br /><code>in\_progress</code> when a streaming output item is added; <code>completed</code> in the final output, including when the response is <code>incomplete</code>.</td></tr><tr><td><strong>output\[].role</strong> string<br />For a <code>message</code> item, always <code>assistant</code>.</td></tr><tr><td><strong>output\[].content</strong> list<br />For a <code>message</code> item, <code>output\_text</code> parts with <code>text</code> and <code>annotations</code>. For a <code>reasoning</code> item, <code>reasoning\_text</code> parts with <code>text</code>.</td></tr><tr><td><strong>output\[].summary</strong> list<br />For a <code>reasoning</code> item, always an empty list — Solar returns raw reasoning text rather than a summary.</td></tr><tr><td><strong>output\[].call\_id</strong> string<br />For a <code>function\_call</code> item, the id used to match the result you send back.</td></tr><tr><td><strong>output\[].name</strong> string<br />For a <code>function\_call</code> item, the name of the function to call.</td></tr><tr><td><strong>output\[].arguments</strong> string<br />For a <code>function\_call</code> item, the function arguments as a JSON string.</td></tr><tr><td><strong>text</strong> object<br />The output format that was applied, echoed back so you can confirm your request was honored. Defaults to <code />.</td></tr><tr><td><strong>incomplete\_details</strong> object or null<br />Present only when <code>status</code> is <code>incomplete</code>. Carries <code>reason</code>, which is <code>max\_output\_tokens</code>.</td></tr><tr><td><strong>error</strong> object<br />Streaming only. Present in the response carried by a <code>response.failed</code> event when a mid-stream error occurs.</td></tr><tr><td><strong>error.code</strong> string<br />An error code, when available.</td></tr><tr><td><strong>error.message</strong> string<br />A description of the mid-stream error.</td></tr><tr><td><strong>usage</strong> object<br />Token usage for the request. May be absent or partial before streaming finishes.</td></tr><tr><td><strong>usage.input\_tokens</strong> integer<br />Number of tokens in the input.</td></tr><tr><td><strong>usage.input\_tokens\_details.cached\_tokens</strong> integer<br />Number of input tokens served from the prompt cache.</td></tr><tr><td><strong>usage.output\_tokens</strong> integer<br />Number of tokens generated, including reasoning tokens.</td></tr><tr><td><strong>usage.output\_tokens\_details.reasoning\_tokens</strong> integer<br />Number of tokens the model used for reasoning. <code>0</code> when reasoning is off.</td></tr><tr><td><strong>usage.total\_tokens</strong> integer<br />Total number of tokens used (input + output).</td></tr></tbody></table>

## Examples

**Request**

### Python

```python
from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v1",
)

response = client.responses.create(
    model="solar-pro4",
    input="Hi, how are you?",
)
print(response.output_text)
```

### cURL

```bash
curl --location 'https://api.upstage.ai/v1/responses' \
  --header 'Authorization: Bearer UPSTAGE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "solar-pro4",
    "input": "Hi, how are you?"
  }'
```

### JavaScript

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "UPSTAGE_API_KEY",
  baseURL: "https://api.upstage.ai/v1",
});

const response = await client.responses.create({
  model: "solar-pro4",
  input: "Hi, how are you?",
});
console.log(response.output_text);
```

**Response**

```json
{
  "id": "resp_75c4def7-5cc8-43eb-9558-545009063a3b",
  "object": "response",
  "created_at": 1785952894,
  "status": "completed",
  "model": "solar-pro4-260806",
  "output": [
    {
      "type": "message",
      "id": "msg_resp_75c4def7-5cc8-43eb-9558-545009063a3b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! I'm doing well, thank you for asking. How can I help you today?",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 19,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 34
  },
  "text": { "format": { "type": "text" } }
}
```

## Streaming

Set `stream` to `true` to receive the response as Server-Sent Events. Each event carries its type on the `event:` line and a JSON payload on the `data:` line; every payload repeats the type and carries a monotonically increasing `sequence_number`. There is no `[DONE]` sentinel — the stream ends with `response.completed`, `response.incomplete`, or `response.failed`.

### Event types

<table><tbody><tr><td><strong>response.created</strong><br />The first event. Carries the response object with <code>status</code> <code>in\_progress</code>.</td></tr><tr><td><strong>response.output\_item.added</strong><br />A new output item opened. Carries <code>output\_index</code> and the item shell.</td></tr><tr><td><strong>response.content\_part.added</strong><br />A content part opened on a <code>message</code> item.</td></tr><tr><td><strong>response.output\_text.delta</strong><br />A fragment of the assistant's visible answer, in <code>delta</code>.</td></tr><tr><td><strong>response.output\_text.done</strong><br />The assistant text is complete. Carries the full <code>text</code>.</td></tr><tr><td><strong>response.reasoning\_text.delta</strong><br />A fragment of the reasoning text, in <code>delta</code>. Emitted only when reasoning is on.</td></tr><tr><td><strong>response.reasoning\_text.done</strong><br />The reasoning text is complete. Carries the full <code>text</code>.</td></tr><tr><td><strong>response.function\_call\_arguments.delta</strong><br />A fragment of a tool call's arguments, in <code>delta</code>. Use <code>item\_id</code> to tell parallel calls apart.</td></tr><tr><td><strong>response.function\_call\_arguments.done</strong><br />A tool call's arguments are complete. Carries the full <code>arguments</code> and the function <code>name</code>.</td></tr><tr><td><strong>response.content\_part.done</strong><br />A content part closed.</td></tr><tr><td><strong>response.output\_item.done</strong><br />An output item closed. Carries the finished item, including the whole <code>arguments</code> for a <code>function\_call</code>.</td></tr><tr><td><strong>response.completed</strong><br />Terminal event for a normal finish. Carries the final response object.</td></tr><tr><td><strong>response.incomplete</strong><br />Terminal event when generation stopped at <code>max\_output\_tokens</code>. Carries the response object with <code>status</code> <code>incomplete</code> and <code>incomplete\_details.reason</code> <code>max\_output\_tokens</code>. The partial output is still delivered.</td></tr><tr><td><strong>response.failed</strong><br />Terminal event for a mid-stream error. Carries the response object with <code>status</code> <code>failed</code> and an <code>error</code> object containing <code>message</code> and, when available, <code>code</code>.</td></tr></tbody></table>

> Python SDK: streaming helper and truncated responses
>
> `client.responses.stream()` builds its final response only from `response.completed`, so `get_final_response()` raises `RuntimeError` when a stream ends with `response.incomplete`. This is a property of the SDK helper rather than of this API. If a response may be truncated, iterate the raw events with `client.responses.create(stream=True)` and handle `response.incomplete` yourself.

## Errors

Errors use the OpenAI error envelope. `param` identifies the field associated with the failure, and `code` classifies it; either may be `null`. Some validation errors use the corresponding Chat Completions field name, such as `max_tokens` or `response_format`.

```json
{
  "error": {
    "message": "the 'previous_response_id' parameter is not supported: this API is stateless and does not store responses. Send the full conversation history in 'input' instead",
    "type": "invalid_request_error",
    "param": "previous_response_id",
    "code": "invalid_request_body"
  }
}
```

<table><tbody><tr><td><strong>400</strong><br />A parameter is invalid, the context length is exceeded, or a stateless-incompatible parameter (<code>previous\_response\_id</code>, <code>conversation</code>, <code>background</code>, <code>store: true</code>) was sent. Depending on the error, <code>code</code> may be <code>invalid\_request\_body</code>, <code>context\_length\_exceeded</code>, another error code, or <code>null</code>.</td></tr><tr><td><strong>401</strong><br />The API key is missing or invalid.</td></tr><tr><td><strong>404</strong> model\_not\_found<br />The model does not exist or does not support the Responses API.</td></tr><tr><td><strong>408</strong><br />The request timed out.</td></tr><tr><td><strong>429</strong><br />Rate limit exceeded.</td></tr><tr><td><strong>5xx</strong><br />An upstream or internal error. Retry with backoff.</td></tr></tbody></table>