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

← Быстрый старт с APIОткрыть как Markdown

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

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

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

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

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

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

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

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

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 } }).