Request-Header

Drei optionale Header, die das Gateway versteht: zwei tragen Ihren eigenen Trace-Kontext bis in unsere Logs, einer hält ein Gespräch auf demselben Upstream, damit Prompt Caching weiter greift. Ohne sie ändert sich nichts.

Header	Was das Gateway tut	Wofür
`X-Trace-Id`	Wird unverändert in der Antwort zurückgegeben und ins Access-Log geschrieben.	Einen Aufruf Ihrem eigenen Tracing-System zuordnen.
`X-Span-Id`	Wird unverändert in der Antwort zurückgegeben und ins Access-Log geschrieben.	Einen einzelnen Span innerhalb dieses Traces kennzeichnen.
`X-Session-Id`	Wird zurückgegeben. Aufeinanderfolgende Requests mit demselben Wert werden an denselben Kanal und denselben Upstream-Key gebunden.	Prompt Caching über ein ganzes Gespräch hinweg warm halten.
`X-Request-ID`	Wird nicht von Ihnen übernommen. Ihr Wert kommt als `X-Client-Request-ID` zurück; die `X-Request-ID` der Antwort ist immer die vom Gateway erzeugte UUIDv7.	Die Gateway-seitige Identität des Aufrufs - im Support-Ticket angeben.

So senden Sie sie

curl https://synthorai.io/v1/chat/completions \
  -H "Authorization: Bearer $SYNTHORAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: conv-8f3a2b" \
  -H "X-Trace-Id: 7c1d9e40f2b84a17" \
  -H "X-Span-Id: 2f9b41c8" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Session-Affinität

Ein Cache-Eintrag liegt auf genau einem API-Key beim Anbieter. Ein Kanal kann mehrere Keys halten, und ohne Hinweis verteilt das Gateway die Aufrufe darauf - der zweite Zug eines Gesprächs landet dann womöglich auf einem Key, der Ihr Präfix nie gesehen hat, und zahlt die Schreibkosten erneut.

Senden Sie bei jedem Aufruf eines Gesprächs denselben Wert und für ein anderes Gespräch einen anderen. Serverseitig wird nichts gespeichert und nichts läuft ab: Der Wert wird gehasht, um Kanal und Key zu wählen - derselbe Wert führt also immer zum selben Ziel.

An den beiden OpenAI-kompatiblen Endpunkten - /v1/chat/completions und /v1/responses - können Sie den Header ganz weglassen: Enthält der Request-Body prompt_cache_key, nutzt das Gateway diesen als Affinitäts-Key. An /v1/messages und den Gemini-Endpunkten senden Sie den Header.

Affinität ist Best Effort: Sie entscheidet nur, welcher Kanal unter gleichrangigen Kandidaten gewählt wird. Failover, Rate-Limit-Cooldown, Retries und eine explizite Routing-Vorgabe gehen ihr immer vor. Der Listenpreis eines Modells ist auf jedem Kanal gleich, den wir wählen können.

Grenzen

Je 128 Byte. Längere Werte werden abgeschnitten. Ein Wert mit Steuerzeichen oder Zeichen außerhalb des druckbaren ASCII wird komplett verworfen - weder zurückgegeben noch geloggt. Diese Werte landen in einem Response-Header und einer Logzeile; das hält Header- und Log-Injection draußen.
Sie enden am Gateway. Keiner der drei wird an den Modellanbieter weitergereicht - der ausgehende Request trägt nur Authentifizierung, Content-Type und anbieterspezifische Header.
Keiner davon identifiziert einen Aufruf für die Abrechnung. Abrechnung, Deduplizierung und Abgleich hängen alle an der gateway-eigenen X-Request-ID, nie an einem Wert, den Sie kontrollieren.

Wenn etwas schiefgeht

Nennen Sie die gesendete X-Trace-Id oder die X-Request-ID aus der Antwort - mit beidem finden wir genau diesen Aufruf.
Ihre Trace-ID erscheint auch am Request in der Nutzungsanalyse - so finden Sie den Aufruf selbst, bevor Sie ein Ticket eröffnen.
Um die Affinität zu prüfen, senden Sie denselben langen Präfix mehrfach mit einer X-Session-Id und sehen Sie sich die Spalten Cache R und Cache W in der Nutzungsanalyse an: Der erste Aufruf schreibt in den Cache, die folgenden sollten daraus lesen. Ändern Sie den Wert, sollte der Schreibvorgang wieder auftauchen.

Siehe auch: Prompt Caching · Usage Analytics