> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a response

Создаёт потоковый или непотоковый ответ в формате API OpenAI Responses.

## Аутентификация

<ParamField header="Authorization" type="string" required>
  Bearer-токен. Используйте ваш API-ключ в качестве Bearer-токена в заголовке Authorization.

  Формат: `Bearer <SUNRA_KEY>`
</ParamField>

## Запрос

Этот эндпоинт принимает объект.

<ParamField body="model" type="string" required>
  Идентификатор модели для генерации ответа. Просмотрите доступные модели на [sunra.ai/models](https://sunra.ai/models).
</ParamField>

<ParamField body="input" type="string | object[]">
  Входные данные для запроса ответа. Может быть строкой или массивом входных элементов.

  <Expandable title="properties (when array)">
    <ParamField body="type" type="string">
      Тип входного элемента. Поддерживаемые значения: `message`, `item_reference`.
    </ParamField>

    <ParamField body="role" type="string">
      Роль автора сообщения. Поддерживаемые значения: `user`, `assistant`, `system`.
    </ParamField>

    <ParamField body="content" type="string | object[]">
      Содержание входного сообщения. Может быть строкой или массивом частей контента.
    </ParamField>

    <ParamField body="id" type="string">
      Идентификатор элемента. Обязателен для сообщений `assistant` в истории беседы.
    </ParamField>

    <ParamField body="status" type="string">
      Статус элемента. Обязателен для сообщений `assistant` в истории беседы.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="instructions" type="string | null">
  Вставляет системное (или разработческое) сообщение в качестве первого элемента в контексте модели. При использовании с `input` инструкции вставляются в начало ввода.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  Если установлено значение `true`, ответ будет передаваться в потоковом режиме с использованием Server-Sent Events (SSE).
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Верхний предел количества выходных токенов, включая видимые выходные токены и токены рассуждений.
</ParamField>

<ParamField body="temperature" type="number" default={1}>
  Температура сэмплирования от 0 до 2. Более высокие значения увеличивают случайность.
</ParamField>

<ParamField body="top_p" type="number" default={1}>
  Параметр nucleus-сэмплирования. Альтернатива сэмплированию по температуре.
</ParamField>

<ParamField body="frequency_penalty" type="number" default={0}>
  Число от -2.0 до 2.0. Положительные значения штрафуют новые токены на основе их существующей частоты в тексте.
</ParamField>

<ParamField body="presence_penalty" type="number" default={0}>
  Число от -2.0 до 2.0. Положительные значения штрафуют новые токены на основе их предыдущего появления в тексте.
</ParamField>

<ParamField body="tools" type="object[]">
  Массив инструментов, которые модель может вызвать.

  <Expandable title="properties">
    <ParamField body="type" type="string" required>
      Тип инструмента. Поддерживаемые значения: `function`, `web_search_preview`.
    </ParamField>

    <ParamField body="name" type="string">
      Имя функции. Обязательно, когда type — `function`.
    </ParamField>

    <ParamField body="description" type="string">
      Описание функции.
    </ParamField>

    <ParamField body="parameters" type="object">
      Объект JSON Schema, определяющий параметры функции.
    </ParamField>

    <ParamField body="strict" type="boolean" default={false}>
      Включено ли строгое соблюдение схемы.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Управляет поведением выбора инструментов. Поддерживаемые строковые значения: `none`, `auto`, `required`. Также можно указать конкретную функцию.
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean" default={true}>
  Разрешить ли модели выполнять вызовы инструментов параллельно.
</ParamField>

<ParamField body="text" type="object">
  Конфигурация формата текстового ответа.

  <Expandable title="properties">
    <ParamField body="format" type="object">
      Конфигурация текстового формата.

      <Expandable title="properties">
        <ParamField body="type" type="string" required>
          Тип формата. Поддерживаемые значения: `text`, `json_object`, `json_schema`.
        </ParamField>

        <ParamField body="name" type="string">
          Имя формата ответа. Обязательно, когда type — `json_schema`.
        </ParamField>

        <ParamField body="schema" type="object">
          JSON-схема. Обязательно, когда type — `json_schema`.
        </ParamField>

        <ParamField body="strict" type="boolean">
          Включено ли строгое соблюдение схемы.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reasoning" type="object">
  Конфигурация вывода рассуждений.

  <Expandable title="properties">
    <ParamField body="effort" type="string">
      Ограничивает усилия на рассуждения. Поддерживаемые значения: `low`, `medium`, `high`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="store" type="boolean" default={true}>
  Сохранять ли сгенерированный ответ для последующего извлечения.
</ParamField>

<ParamField body="metadata" type="object">
  Набор из 16 пар ключ-значение, которые можно прикрепить к ответу. Ключи — строки длиной до 64 символов. Значения — строки длиной до 512 символов.
</ParamField>

<ParamField body="user" type="string">
  Уникальный идентификатор вашего конечного пользователя. Максимум 128 символов.
</ParamField>

## Ответ

Успешный объект ответа.

<ResponseField name="id" type="string">
  Уникальный идентификатор ответа.
</ResponseField>

<ResponseField name="object" type="string">
  Тип объекта. Всегда `response`.
</ResponseField>

<ResponseField name="created_at" type="number">
  Unix-временная метка (в секундах) создания ответа.
</ResponseField>

<ResponseField name="status" type="string">
  Статус ответа. Возможные значения: `completed`, `failed`, `in_progress`, `cancelled`.
</ResponseField>

<ResponseField name="model" type="string">
  Модель, использованная для генерации ответа.
</ResponseField>

<ResponseField name="output" type="object[]">
  Массив элементов контента, сгенерированных моделью.

  <Expandable title="properties">
    <ResponseField name="type" type="string">
      Тип выходного элемента. Например, `message`.
    </ResponseField>

    <ResponseField name="id" type="string">
      Уникальный идентификатор выходного элемента.
    </ResponseField>

    <ResponseField name="role" type="string">
      Роль. Всегда `assistant`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Статус сообщения. Например, `completed`.
    </ResponseField>

    <ResponseField name="content" type="object[]">
      Содержание выходного сообщения.

      <Expandable title="properties">
        <ResponseField name="type" type="string">
          Тип контента. Например, `output_text`.
        </ResponseField>

        <ResponseField name="text" type="string">
          Сгенерированный текстовый контент.
        </ResponseField>

        <ResponseField name="annotations" type="object[]">
          Аннотации к контенту (например, цитаты из веб-поиска).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="usage" type="object">
  Статистика использования токенов для ответа.

  <Expandable title="properties">
    <ResponseField name="input_tokens" type="integer">
      Количество входных токенов.
    </ResponseField>

    <ResponseField name="output_tokens" type="integer">
      Количество выходных токенов.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Общее количество токенов.
    </ResponseField>

    <ResponseField name="input_tokens_details" type="object">
      Детализация входных токенов.

      <Expandable title="properties">
        <ResponseField name="cached_tokens" type="integer">
          Количество кэшированных токенов.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="output_tokens_details" type="object">
      Детализация выходных токенов.

      <Expandable title="properties">
        <ResponseField name="reasoning_tokens" type="integer">
          Количество токенов рассуждений.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="temperature" type="number">
  Использованная температура сэмплирования.
</ResponseField>

<ResponseField name="top_p" type="number">
  Использованное значение nucleus-сэмплирования.
</ResponseField>

<ResponseField name="max_output_tokens" type="integer | null">
  Использованная настройка максимальных выходных токенов.
</ResponseField>

<ResponseField name="error" type="object | null">
  Объект ошибки, если генерация не удалась.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api-llm.sunra.ai/v1/responses \
    -H "Authorization: Bearer <SUNRA_KEY>" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "input": [
        {
          "type": "message",
          "role": "user",
          "content": "Hello, how are you?"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api-llm.sunra.ai/v1/responses",
      headers={
          "Authorization": "Bearer <SUNRA_KEY>",
          "Content-Type": "application/json"
      },
      json={
          "model": "openai/gpt-4o",
          "input": [
              {
                  "type": "message",
                  "role": "user",
                  "content": "Hello, how are you?"
              }
          ]
      }
  )
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api-llm.sunra.ai/v1/responses", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <SUNRA_KEY>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "openai/gpt-4o",
      input: [
        {
          type: "message",
          role: "user",
          content: "Hello, how are you?"
        }
      ]
    })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "resp-abc123",
    "object": "response",
    "created_at": 1704067200,
    "status": "completed",
    "model": "openai/gpt-4o",
    "output": [
      {
        "type": "message",
        "id": "msg_abc123",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "Hello! I'm doing well, thank you for asking. How can I help you today?",
            "annotations": []
          }
        ]
      }
    ],
    "temperature": 1.0,
    "top_p": 1.0,
    "max_output_tokens": null,
    "usage": {
      "input_tokens": 15,
      "output_tokens": 18,
      "total_tokens": 33,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens_details": {
        "reasoning_tokens": 0
      }
    },
    "error": null
  }
  ```
</ResponseExample>