# Сессии: как объединить запросы в разговор

> Объединяйте запросы одного разговора заголовком opencheese-session-uuid: когда его передавать, формат значения и примеры на curl, Python и JavaScript.
>
> Веб-страница: https://opencheese.dev/ru/docs/sessions/ · Все страницы документации: https://opencheese.dev/ru/docs.md

Сессия — это один разговор: все относящиеся к нему запросы, собранные в одну строку на странице
**Транзакции** в панели, с общим числом токенов и стоимостью разговора. Кроме того, сессии
позволяют сжатию контекста (страница **Context Compacter**) удерживать длинный разговор в пределах
контекстного окна модели.

## Поддерживаемые инструменты группируют запросы сами

OpenCode, Claude Code, Claude Desktop, Codex, Harness AI, Zed, RikkaHub и LobeHub (через запись
New API) уже группируют свои запросы: один разговор в инструменте — это одна сессия в панели,
настраивать ничего не нужно. Запросы Chatbox пока отображаются как отдельные сессии.

Всё остальное, например ваши собственные скрипты и вызовы через SDK, начинает новую сессию с каждым
запросом, если сессия не указана явно.

## Укажите сессию в заголовке

Передавайте один и тот же заголовок `opencheese-session-uuid` в каждом запросе разговора:

```bash
SESSION=$(uuidgen)

curl https://api.opencheese.dev/v1/chat/completions \
  -H "Authorization: Bearer $OPENCHEESE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "opencheese-session-uuid: $SESSION" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Name three cheeses."}]}'
```

Заголовок работает одинаково на `/v1/chat/completions`, `/v1/responses`, `/v1/messages` и
эндпоинтах изображений, поэтому разговор, в котором они чередуются, остаётся одной сессией.

## Когда его передавать

Передавайте один идентификатор сессии на разговор, когда:

- чат или цикл агента отправляет несколько запросов, каждый из которых опирается на предыдущие;
- ваше приложение делает фоновые вызовы для разговора, например чтобы получить его название или
  краткое содержание: передайте им идентификатор разговора, чтобы их стоимость учитывалась вместе
  с ним;
- одна задача задействует несколько моделей: сессия объединяет их.

Не передавайте заголовок, если запросы независимы друг от друга: например, пакет задач
классификации или разовый вопрос. Тогда каждый запрос — отдельная сессия.

Никогда не используйте один идентификатор для несвязанных разговоров: они отобразятся как одна
сессия, а сжатие контекста будет считать их одним разговором.

## Формат

- Используйте для каждого разговора новый случайный UUID (версии 4), например
  `2f1c6d0e-8a4b-4c55-9b7e-3d2a1f0e9c84`.
- Шлюз принимает и любой идентификатор длиной от 1 до 256 символов из букв, цифр, `_`, `.`, `:`
  и `-`, но UUID — самый надёжный вариант.
- Любое другое значение отклоняется с ошибкой `invalid_session_header` (HTTP 400; на
  `/v1/chat/completions` она приходит в виде ответа ассистента).

Каждый ответ chat, responses, messages и эндпоинтов изображений, включая потоковые ответы,
возвращает в заголовке ответа `opencheese-session-uuid` идентификатор сессии, под которым он
записан. Если вы не передали свой заголовок, это новый идентификатор: отправьте его в следующем
запросе, чтобы продолжить ту же сессию.

## Python

```python
import uuid
from openai import OpenAI

client = OpenAI(base_url="https://api.opencheese.dev/v1", api_key="YOUR_OPENCHEESE_API_KEY")
session = str(uuid.uuid4())
history = [{"role": "user", "content": "Name three cheeses."}]

first = client.chat.completions.create(
    model="MODEL_ID",
    messages=history,
    extra_headers={"opencheese-session-uuid": session},
)
history.append({"role": "assistant", "content": first.choices[0].message.content})
history.append({"role": "user", "content": "Which one melts best?"})

second = client.chat.completions.create(
    model="MODEL_ID",
    messages=history,
    extra_headers={"opencheese-session-uuid": session},
)
print(second.choices[0].message.content)
```

В SDK Anthropic передайте тот же заголовок через `extra_headers` в `client.messages.create` или
один раз для всего клиента — через `default_headers`.

## JavaScript

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.opencheese.dev/v1",
  apiKey: process.env.OPENCHEESE_API_KEY,
  defaultHeaders: { "opencheese-session-uuid": crypto.randomUUID() }
});

const reply = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "Name three cheeses." }]
});
console.log(reply.choices[0].message.content);
```

Клиент, созданный с `defaultHeaders`, помещает все свои запросы в одну сессию, поэтому создавайте
отдельный клиент на каждый разговор или передавайте заголовок в каждом запросе:
`client.chat.completions.create(body, { headers: { "opencheese-session-uuid": id } })`.