# API Responses

> OpenAI Responses API в OpenCheese: POST /v1/responses с instructions, элементами input, событиями потока, инструментами-функциями и уровнем рассуждений.
>
> Веб-страница: https://opencheese.dev/ru/docs/responses/ · Все страницы документации: https://opencheese.dev/ru/docs.md

`POST https://api.opencheese.dev/v1/responses` — это OpenAI Responses API. Его использует Codex,
а также методы `responses` в SDK OpenAI.

## Первый запрос

```bash
curl https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "instructions": "Answer in one sentence.", "input": "What is a gateway?"}'
```

Поле `model` обязательно; `input` — это строка или список входных элементов, а `instructions`
становится системным промптом. Текст ответа находится в элементах `output[].content[]` с типом
`output_text`:

```json
{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "MODEL_ID",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "A gateway passes your requests on to the models behind it." }]
    }
  ],
  "usage": { "input_tokens": 24, "output_tokens": 13, "total_tokens": 37 }
}
```

## Параметры

| Поле | Примечания |
| --- | --- |
| `model` | Обязательное. Значение `id` из [`/v1/models`](https://opencheese.dev/ru/docs/models.md). |
| `input` | Строка или элементы `message`, `function_call` и `function_call_output`. |
| `instructions` | Системный промпт. |
| `stream` | `true`, чтобы получить ответ в виде server-sent events. |
| `tools`, `tool_choice` | Инструменты-функции, если модель поддерживает инструменты. |
| `reasoning.effort` | Один из уровней в `supported_reasoning_levels` модели. |
| `temperature`, `top_p`, `max_output_tokens` | Необязательные. Если их не задать, используются значения модели по умолчанию. |

## Разговор отправляется целиком

Каждый запрос передаёт в `input` весь разговор: прежние реплики отправляйте заново как элементы
`message` (реплики ассистента — с `role: "assistant"`). `previous_response_id`, `store` и
`text.format` здесь не поддерживаются; для структурированного вывода используйте
[Chat Completions](https://opencheese.dev/ru/docs/chat-completions.md) с `response_format`.

```json
{
  "model": "MODEL_ID",
  "input": [
    { "type": "message", "role": "user", "content": "Name three cheeses." },
    { "type": "message", "role": "assistant", "content": "Brie, Gouda and Comté." },
    { "type": "message", "role": "user", "content": "Which one melts best?" }
  ]
}
```

## Потоковый ответ

```bash
curl -N https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "stream": true, "input": "Count to three."}'
```

Поток передаёт события Responses API: `response.created` и `response.in_progress`, затем
`response.output_item.added`, `response.output_text.delta` с текстом, соответствующие события
`.done` и в конце `response.completed` с полным ответом и его `usage`. Если запрос завершается
ошибкой уже после начала потока, поток заканчивается событием `response.failed`, в котором
`response.error` содержит `code` и `message`.

```text
event: response.output_text.delta
data: {"type":"response.output_text.delta","output_index":0,"content_index":0,"delta":"One, two"}

event: response.completed
data: {"type":"response.completed","response":{"status":"completed","usage":{"input_tokens":12,"output_tokens":6,"total_tokens":18}}}
```

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

```json
{
  "model": "MODEL_ID",
  "input": "What is the weather in Paris?",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Current weather for a city",
      "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
    }
  ]
}
```

Вызов инструмента приходит как выходной элемент `function_call` с полями `call_id`, `name` и
`arguments`. Результат отправьте в следующем запросе как элемент `function_call_output` с тем же
`call_id`, после самого элемента `function_call`.

## Уровень рассуждений

```bash
curl https://api.opencheese.dev/v1/responses \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "reasoning": {"effort": "high"}, "input": "Plan a three-day trip to Lyon."}'
```

Если уровень не задан, используется уровень модели по умолчанию. Уровень, которого у модели нет,
отклоняется с ошибкой `unsupported_reasoning_effort`, где перечислены уровни, которые модель
поддерживает. Краткие сводки рассуждений, если модель их возвращает, приходят как выходные
элементы `reasoning`.

## Расход токенов

`usage` сообщает `input_tokens` (с `input_tokens_details.cached_tokens`), `output_tokens`
(с `output_tokens_details.reasoning_tokens`) и `total_tokens`.

## Python

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
response = client.responses.create(model="MODEL_ID", input="Write a haiku about cheese.")
print(response.output_text)
```

Ошибки этого эндпоинта всегда приходят как HTTP-статус с телом в JSON и никогда — как ответ
ассистента, в отличие от Chat Completions; если поток уже начался, приходит `response.failed`.
Подробнее — на странице [Ошибки и лимиты запросов](https://opencheese.dev/ru/docs/errors.md). Добавьте заголовок
[`opencheese-session-uuid`](https://opencheese.dev/ru/docs/sessions.md), чтобы объединить запросы одного разговора.