# Sitzungen: Anfragen zu einer Unterhaltung bündeln

> Halte die Anfragen einer Unterhaltung mit dem Header opencheese-session-uuid zusammen: wann, in welchem Format, mit Beispielen in curl, Python und JavaScript.
>
> Webseite: https://opencheese.dev/de/docs/sessions/ · Alle Seiten der Doku: https://opencheese.dev/de/docs.md

Eine Sitzung ist eine Unterhaltung: alle Anfragen, die zu ihr gehören, gebündelt in einer Zeile
unter **Transaktionen** im Dashboard, mit den gesamten Tokens und Kosten der Unterhaltung.
Außerdem kann die Context Compaction (Seite **Context Compacter**) dank Sitzungen eine lange
Unterhaltung im Kontextfenster des Modells halten.

## Unterstützte Tools bündeln von selbst

OpenCode, Claude Code, Claude Desktop, Codex, Harness AI, Zed, RikkaHub und LobeHub (über den
Eintrag New API) bündeln ihre Anfragen bereits: Eine Unterhaltung im Tool ist eine Sitzung im
Dashboard, ohne dass du etwas einrichten musst. Anfragen aus Chatbox erscheinen vorerst als
einzelne Sitzungen.

Alles andere, etwa deine eigenen Skripte und SDK-Aufrufe, beginnt mit jeder Anfrage eine neue
Sitzung, sofern die Anfrage keine Sitzung benennt.

## Die Sitzung per Header benennen

Sende bei jeder Anfrage der Unterhaltung denselben Header `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."}]}'
```

Der Header funktioniert bei `/v1/chat/completions`, `/v1/responses`, `/v1/messages` und den
Bild-Endpunkten gleich. Eine Unterhaltung, die mehrere davon nutzt, bleibt so eine Sitzung.

## Wann du ihn senden solltest

Sende eine Sitzungs-ID pro Unterhaltung, wenn:

- ein Chat oder eine Agentenschleife mehrere Anfragen sendet, die aufeinander aufbauen;
- deine App für eine Unterhaltung Aufrufe im Hintergrund macht, etwa für einen Titel oder eine
  Zusammenfassung: Gib ihnen die ID der Unterhaltung, damit ihre Kosten ihr zugerechnet werden;
- eine Aufgabe mehrere Modelle umfasst: Die Sitzung hält sie zusammen.

Lass den Header weg, wenn die Anfragen unabhängig voneinander sind, etwa bei einer Reihe von
Klassifizierungen oder einer einmaligen Frage. Jede Anfrage ist dann eine eigene Sitzung.

Verwende nie dieselbe ID für Unterhaltungen, die nichts miteinander zu tun haben: Sie würden als
eine Sitzung erscheinen, und die Context Compaction würde sie als eine Unterhaltung behandeln.

## Format

- Verwende für jede Unterhaltung eine neue zufällige UUID (Version 4), etwa
  `2f1c6d0e-8a4b-4c55-9b7e-3d2a1f0e9c84`.
- Das Gateway akzeptiert auch jede ID aus 1 bis 256 Zeichen, die nur aus Buchstaben, Ziffern,
  `_`, `.`, `:` und `-` besteht, aber eine UUID ist die sichere Wahl.
- Jeder andere Wert wird mit `invalid_session_header` abgelehnt (HTTP 400; bei
  `/v1/chat/completions` kommt der Fehler als Antwort des Assistenten).

Jede Antwort von Chat, Responses, Messages und den Bild-Endpunkten liefert im Antwort-Header
`opencheese-session-uuid` die Sitzungs-ID, unter der sie erfasst wurde, auch bei
Streaming-Antworten. Ohne deinen eigenen Header ist das eine neue ID, die du bei der nächsten
Anfrage zurückschicken kannst, um dieselbe Sitzung fortzusetzen.

## 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)
```

Mit dem Anthropic-SDK übergibst du denselben Header als `extra_headers` an
`client.messages.create` oder einmal für den ganzen Client als `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);
```

Ein mit `defaultHeaders` erstellter Client legt alle seine Anfragen in eine Sitzung. Erstelle
deshalb einen Client pro Unterhaltung oder übergib den Header pro Anfrage mit
`client.chat.completions.create(body, { headers: { "opencheese-session-uuid": id } })`.