# Responses (OpenAI Responses API)

```
POST https://api.agentapi.ru/v1/ai/responses
```

Формат OpenAI Responses API: вместо массива `messages` передаётся `input`, а системная
инструкция — отдельным полем `instructions`.

> **Стриминг не поддерживается.** Параметр `stream` принимается, но игнорируется —
> ответ всегда приходит целиком. Если нужен поток, используйте
> [Chat Completions](https://agentapi.ru/docs/endpoints/chat-completions) или
> [Messages](https://agentapi.ru/docs/endpoints/messages).

## Параметры

Здесь параметры в snake_case — как в оригинальном API.

| Параметр | Тип | Описание |
|---|---|---|
| `input` | string \| array | **Основной ввод.** Текст или массив элементов |
| `model` | string | Слаг модели |
| `instructions` | string | Системная инструкция |
| `max_output_tokens` | number | Лимит генерации |
| `temperature` | number | 0–2 |
| `top_p` | number | Nucleus sampling |
| `frequency_penalty` | number | −2…2 |
| `presence_penalty` | number | −2…2 |
| `tools` | array | Инструменты в формате `{type, name, description, parameters}` |
| `tool_choice` | string \| object | Управление выбором инструмента |
| `previous_response_id` | string | Связывание с предыдущим ответом |
| `reasoning` | object | Настройка reasoning |
| `session_id` | string | Группировка запросов |
| `metadata` | object | Метаданные |
| `provider` | object | Предпочтения роутинга |
| `plugins` | array | Дополнительные плагины |
| `user` | string | Идентификатор конечного пользователя |
| `stream` | boolean | Принимается, но не действует |

## Пример запроса

```bash
curl https://api.agentapi.ru/v1/ai/responses \
  -H "x-api-key: agentapi-ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4.1",
    "instructions": "Ты лаконичный ассистент.",
    "input": "Перечисли три принципа SOLID",
    "max_output_tokens": 200
  }'
```

## Ответ

```json
{
  "id": "resp_6a2f9c14",
  "object": "response",
  "created_at": 1753601180,
  "model": "openai/gpt-4.1",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "1. Single Responsibility — у класса одна причина для изменения.\n2. Open/Closed — открыт для расширения, закрыт для модификации.\n3. Liskov Substitution — подтип заменяет базовый тип без нарушения контракта."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 19,
    "output_tokens": 74,
    "total_tokens": 93
  }
}
```

Текст лежит в `output[0].content[0].text` — глубже, чем в Chat Completions.
Терминология токенов — `input_tokens` / `output_tokens`.

## Инструменты

В отличие от Chat Completions, описание инструмента здесь плоское — без вложенного
объекта `function`:

```json
{
  "model": "openai/gpt-4.1",
  "input": "Погода в Иркутске?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Текущая погода в городе",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  ]
}
```

## Коды ошибок

| Код | Причина |
|---|---|
| 400 | Невалидные параметры или нулевой баланс |
| 401 | Проблема с ключом |
| 429 | Rate limit |
| 502 | Ошибка провайдера |