请求头

网关认三个可选请求头:两个把你自己的链路上下文带进我们的日志,一个让同一段会话固定落在同一个上游,使 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(提示词缓存) · 用量分析