提示缓存

使用与定价

聊天完成 API

缓存的令牌显示在 usage.prompt_tokens_details.cached_tokens 中：

{
  "usage": {
    "prompt_tokens": 125,
    "completion_tokens": 48,
    "total_tokens": 173,
    "prompt_tokens_details": {
      "text_tokens": 125,
      "audio_tokens": 0,
      "image_tokens": 0,
      "cached_tokens": 98
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0,
      "audio_tokens": 0,
      "accepted_prediction_tokens": 0,
      "rejected_prediction_tokens": 0
    }
  }
}

回应 API

缓存的令牌显示在 usage.input_tokens_details.cached_tokens 中：

{
  "usage": {
    "input_tokens": 125,
    "output_tokens": 48,
    "total_tokens": 173,
    "input_tokens_details": {
      "cached_tokens": 98
    },
    "output_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

验证缓存命中

要确定您的请求是否受益于提示缓存，请检查响应中的 cached_tokens 值：

cached_tokens 值	含义
0	缓存未命中 — 整个提示是从头开始计算的。这在首次请求或缓存清除后是预期的结果。
> 0	缓存命中 — 您的部分或全部提示前缀是从缓存中提供的。该数字表示重用了多少令牌。
等于 prompt_tokens	完全缓存命中 — 您的整个提示是从缓存中提供的（罕见情况，通常发生在重新发送完全相同的请求时）。

典型的多轮对话会显示 cached_tokens 值随时间增加：

Turn 1: prompt_tokens=50,  cached_tokens=0    # First request, cache established
Turn 2: prompt_tokens=120, cached_tokens=50   # Previous 50 tokens cached
Turn 3: prompt_tokens=200, cached_tokens=120  # Previous 120 tokens cached

NOTE

如果在同一对话的多个请求中 cached_tokens 一致为 0，请验证您是否设置了 x-grok-conv-id（或 prompt_cache_key），并且您没有在请求之间修改之前的消息。

定价

缓存令牌按缓存提示令牌价格计费，该价格明显低于常规提示令牌价格。具体费率因模型而异 — 请查看 定价 页面了解当前价格。

令牌类型	计费费率
提示令牌（非缓存）	完整提示令牌价格
缓存提示令牌	降低的缓存提示令牌价格
完成令牌	完整完成令牌价格
推理令牌	完整完成令牌价格

NOTE

当总提示令牌（包括缓存令牌）超过模型的长上下文阈值时，适用长上下文定价。在这种情况下，缓存和非缓存令牌都使用各自的长上下文费率。

下一步

• 最佳实践与常见问题解答