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 数
max_completion_tokens否兼容的输出上限，与 max_tokens 二选一
thinking否DeepSeek 等支持的渠道可使用 { "type": "disabled" } 关闭推理
reasoning_effort否目标模型支持的推理强度，例如 none
top_p、stop否采样与停止条件，按目标模型能力执行
frequency_penalty、presence_penalty否重复惩罚，范围 -2 至 2
logprobs、top_logprobs、seed否目标模型支持时传递
parallel_tool_calls否是否允许并行工具调用
n否当前仅支持单个结果，即 1
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": "请分三段输出" }
    ]
  }'

行为说明

  • 未支持的参数返回明确的 400 和 error.param，不再静默删除。工具调用消息支持 tool_calls、tool_call_id 和 reasoning_content；仅携带工具调用的 assistant 消息可省略 content 或使用 null。
  • max_tokens 与 max_completion_tokens 都参与输出预算，并转换为目标协议的输出上限。平台配置的上限同样生效。
  • Anthropic、Gemini 渠道支持可转换的函数工具定义、工具选择、调用与结果历史，以及流式工具调用。无法无损转换的组合在调用上游前返回参数错误，不会退化为普通文本。
  • Gemini 严格工具 Schema（strict: true）和强制串行工具调用（parallel_tool_calls: false）目前不支持；如有需要请选用支持这些约束的渠道。Gemini 返回的 thought_signature 是不透明的续接凭据；下一轮工具调用历史应原样传回，不要自行生成或修改。
  • 对外 model 为平台模型 ID，不暴露路由选择产生的供应商模型名。
  • 平台需要最终用量完成结算，因此流式上游请求启用 include_usage，即使客户未显式要求。
  • TokenPostie 会先校验 API Key、模型权限、余额和限额，再请求上游模型。
  • 最终用户侧只收到 TokenPostie 标准错误结构。
  • 系统内部诊断证据不会直接暴露给最终用户。
  • 流已开始、但尚未完成时发生错误，HTTP 状态仍为 200；最后一个 SSE 数据帧包含 TokenPostie 标准 error.code 和安全文案，随后连接结束。已经发送完整终态后，不再追加错误帧。
  • 流式请求取得完整、合法的 final usage 和协议终态时进入确定性结算；随后发生断连不会撤销已完成调用的费用。缺少完整证据时进入复核，最终账单以 TokenPostie 账单结果为准。