TokenPostie 最终用户文档

Chat Completions API

接口

POST /v1/chat/completions
Authorization: Bearer tp_your_api_key
Content-Type: application/json
X-TokenPostie-Session-Id: your_stable_business_session_id

请求体

字段必填说明
model是GET /v1/models 返回的模型 id
messages是聊天消息数组，支持 system、user、assistant、tool
stream否true 时返回 SSE 流
temperature否当目标模型支持时透传
max_tokens否最大输出 token 数
tools否OpenAI 兼容工具定义
tool_choice否OpenAI 兼容工具选择
response_format否OpenAI 兼容响应格式约束
session_id否未传会话 Header 时使用的会话标识
prompt_cache_key否兼容的输入缓存会话标识

提高输入缓存命中率

项目开启会话亲和后，请为同一段业务会话持续传同一个 X-TokenPostie-Session-Id。TokenPostie 会优先复用此前成功的上游路径，减少多次路由导致的输入缓存失效。

  • 这是路由优化，不会直接缓存模型回答。
  • 原始会话标识不会写入日志。
  • 未传 Header 时，平台依次识别 session_id、metadata.session_id、prompt_cache_key 和 metadata.prompt_cache_key。
  • 默认使用软亲和；目标不可用时自动回退。项目配置为严格亲和时，目标不可用会返回 session_affinity_target_unavailable。

语义缓存

语义缓存是单独开通的项目权益。项目启用后，平台可复用同一租户、项目和模型范围内的相似文本请求结果，减少上游调用和 Token 消耗。

  • 工具调用、图片、结构化响应和包含凭据特征的内容不会进入语义缓存。
  • 只有最后一个用户问题参与相似度；系统提示、此前消息和生成参数必须一致。
  • 单次请求可发送 X-TokenPostie-Semantic-Cache: bypass 跳过查询和回填。
  • 响应头 X-TokenPostie-Semantic-Cache 返回 miss、hit、shadow-hit、bypass 或 store_error。
  • hit 表示本次响应未调用上游；shadow-hit 只用于平台评估，本次仍调用上游。
  • 原始提示词不会作为缓存索引保存。

非流式示例

curl -X POST "https://newapi.yxhhkj.com/v1/chat/completions" \
  -H "Authorization: Bearer tp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model_from_models_api",
    "messages": [
      { "role": "user", "content": "你好" }
    ],
    "temperature": 0
  }'

流式示例

curl -N -X POST "https://newapi.yxhhkj.com/v1/chat/completions" \
  -H "Authorization: Bearer tp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "model_from_models_api",
    "stream": true,
    "messages": [
      { "role": "user", "content": "请分三段输出" }
    ]
  }'

行为说明

  • TokenPostie 会先校验 API Key、模型权限、余额和限额，再请求上游模型。
  • 最终用户侧只收到 TokenPostie 标准错误结构。
  • 系统内部诊断证据不会直接暴露给最终用户。
  • 流已开始后发生错误时，HTTP 状态仍为 200；最后一个 SSE 数据帧包含 TokenPostie 标准 error.code 和安全文案，随后连接结束。
  • 流式请求取得完整 final usage 时进入确定性账本；缺少完整 usage 时进入复核，最终账单以 TokenPostie 账单结果为准。