指南

缓存

你和上游之间可能有两层缓存:提供者为行情类数据开启的 API 响应缓存,以及你按请求开启、用来降低重复提示词成本的 AI 缓存。

	AI 提示词缓存	API 响应缓存
由谁开启	你,按请求开启(`X-Pikeway-Cache`)	提供者,按 API 开启
作用范围	非流式 chat completion	`/gw/` 的 `GET` 调用
是否共享	否,只在你的账户内	是,所有调用方共享
命中价格	token 价格的 10%	正常按次价格

AI 提示词缓存

agent 经常重复发送完全相同的提示词:重试、循环、对重复输入做分类。给非流式 POST /ai/v1/chat/completions 调用加上 X-Pikeway-Cache,TTL 内来自你账户的相同请求会直接从缓存返回,不调用模型,只收原 token 费用的 10%。

bash

curl -i https://gw.pikeway.ai/ai/v1/chat/completions \
  -H "Authorization: Bearer $PIKEWAY_KEY" \
  -H "X-Pikeway-Cache: 300" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","temperature":0,"messages":[{"role":"user","content":"Classify: \"WBTC pumps 5%\""}]}'

# 1st call → X-Pikeway-Cache: MISS   X-Pikeway-Cost: 0.000210
# 2nd call → X-Pikeway-Cache: HIT    X-Pikeway-Cost: 0.000021   (10%, model not called)

请求头

X-Pikeway-Cacheseconds

响应保留的秒数,最大 3600;1(或 true 等非数字值)表示 300 秒;0、false 或不带此头表示不缓存。

响应头

X-Pikeway-CacheHIT | MISS

HIT:来自缓存。MISS:调用了模型并存入缓存。

X-Pikeway-CostUSD

命中时为缓存响应 token 原价的 10%。

什么算“相同请求”

同一账户、同一模型(别名会解析到同一个模型),请求体除 model、user、stream、stream_options 外完全一致。JSON 键的顺序不影响。
精确匹配:提示词改一个字符,或任意参数(temperature、tools…)不同,都算未命中。
缓存按账户隔离、从不共享,别人无法通过命中时间推断你的提示词。
只缓存用 key 调用的非流式 chat completion;Messages、Responses 接口、流式请求和 x402 调用不缓存。

这和模型厂商自己的提示词缓存是两回事。当厂商报告了命中缓存的输入 token 时,无论是否带这个头,Pikeway 都会自动按模型的缓存读取价计费。见 AI 网关。

API 响应缓存

提供者可以让网关把 API 成功的 GET 响应缓存几秒,比如所有调用方同时都在请求的价格或热门榜单。开启后:

TTL 内的相同 GET 请求(同一 API、路径和查询字符串)由网关在几毫秒内直接返回,不调用提供者。
响应带 X-Pikeway-Cache: HIT 或 MISS。没有这个头说明该 API 未开启缓存。
命中和实时调用价格相同。你得到更快的响应,提供者节省上游成本。
TTL 由提供者设置(未设置时为 30 秒),也可以只对部分路径开启,因此报价、swap 等每次都应实时的端点不会被缓存。
只缓存成功的响应。POST 请求和自带 key 的 API 从不缓存。

bash

curl -i "https://gw.pikeway.ai/gw/<slug>/<path>" -H "Authorization: Bearer $PIKEWAY_KEY"

# X-Pikeway-Cache: HIT        ← served by the gateway, the provider wasn't called
# X-Pikeway-Cost: 0.0003      ← same price as a live call