請求標頭

閘道支援三個選用請求標頭:兩個把你自己的鏈路上下文帶進我們的日誌,一個讓同一段工作階段固定落在同一個上游,使 prompt caching 持續命中。三個都不帶也完全不影響呼叫。

請求標頭	閘道的處理	用途
`X-Trace-Id`	原樣回顯在回應標頭上;寫入存取日誌。	把一次呼叫對回你自己的鏈路追蹤系統。
`X-Span-Id`	原樣回顯在回應標頭上;寫入存取日誌。	標識該鏈路中的某一個 span。
`X-Session-Id`	原樣回顯。帶同一個值的連續請求會被固定到同一條通道、同一把上游 key。	讓一段工作階段裡的 prompt caching 持續命中。
`X-Request-ID`	不採信你傳入的值。你傳的值會以 `X-Client-Request-ID` 回顯;回應裡的 `X-Request-ID` 永遠是閘道自己產生的 UUIDv7。	閘道側對這次呼叫的唯一識別 —— 提工單時報這個。

怎麼發

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"}]
  }'

工作階段親和

快取項目是綁在廠商側的某一把 API key 上的。一條通道可能配了多把 key,沒有提示時閘道會把請求分散到這些 key 上 —— 於是一段工作階段的第二輪可能落到一把從沒見過你前綴的 key 上,又付一次寫入費用。

同一段工作階段的每次呼叫都帶同一個值,不同工作階段用不同的值。伺服器端不存任何工作階段表、也沒有過期:這個值經雜湊決定選哪條通道、哪把 key,因此同一個值永遠解析到同一處。

在 /v1/chat/completions 與 /v1/responses 這兩個 OpenAI 相容端點上,可以完全不帶這個標頭:如果請求主體裡有 prompt_cache_key,閘道就用它作為親和鍵。/v1/messages 與 Gemini 端點請用這個標頭。

親和是 best-effort:它只決定在同等優先的候選裡選誰。故障轉移、限流冷卻、重試以及你顯式指定的路由偏好都優先於它。同一個模型在我們可能選中的每條通道上,刊例價都是一樣的。

限制

每個標頭上限 128 位元組。超出會被截斷。含控制字元或可列印 ASCII 之外字元的值會被整體丟棄 —— 既不回顯也不記日誌。這些值會進入回應標頭和日誌行,這條限制用於擋住標頭注入與日誌偽造。
它們止步於閘道。三個標頭都不會轉發給模型廠商 —— 出站請求只帶鑑權、Content-Type 和各廠商專有標頭。
三個標頭都不是計費身分。計費、去重和對帳一律以閘道自己產生的 X-Request-ID 為準,絕不使用由你控制的值。

出問題時

報上你發的 X-Trace-Id,或回應裡的 X-Request-ID —— 任一個都能讓我們定位到那一次具體呼叫。
你的 trace ID 也會顯示在主控台「用量分析」的該次請求上,提工單前你可以自己先查。
想確認親和是否生效:用同一個 X-Session-Id 把同一段長前綴連發幾次,看用量分析裡的 Cache R 與 Cache W 兩欄 —— 第一次是寫入快取,後面幾次應當變成讀取;換一個值,寫入應當重新出現。

延伸閱讀: Prompt Caching · Usage Analytics