Sitzungen: Anfragen zu einer Unterhaltung bündeln

← API-SchnellstartAls Markdown anzeigen

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:

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

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

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