TokenPostie 最终用户文档

Responses API

接口

POST /v1/responses
Authorization: Bearer tp_your_api_key
Content-Type: application/json

请求体

字段必填说明
model是GET /v1/models 返回的模型 id
input条件必填非空字符串或 input Item 数组；原生渠道也可仅提供非空 instructions
instructions否系统或开发者指令
stream否true 时返回 Responses SSE 事件
max_output_tokens否最大输出 token 数，未传时为 4096；不要使用 Chat 的 max_tokens
tools否Responses 函数工具定义
tool_choice否auto、none、required 或指定函数
text.format否text、json_object 或 json_schema
reasoning.effort否目标模型支持时传递给上游
parallel_tool_calls否是否允许并行函数调用
store否当前仅支持 false

input Item 支持：

  • message
  • function_call
  • function_call_output
  • reasoning（需要目标渠道原生支持）
  • 文本内容 input_text
  • URL 图片内容 input_image

文件 ID、OpenAI 托管工具和输入类型取决于模型能力，不能因接口兼容而假定全部支持。previous_response_id 和 conversation 只可省略或为 null；store 和 background 只可省略或为 false。非空响应链、Conversations 和后台执行请求会返回参数错误。

协议选择

已配置原生 Responses 能力的渠道直接请求上游 /responses，保留原生输入、推理历史、函数调用 ID 和流式事件，不转换为 Chat。其他渠道使用 Chat 兼容转换；无法转换的输入会明确报错。

Chat 转换渠道返回的显式 reasoning_content 会保留为 reasoning 输出 Item 和对应摘要事件；平台不会推测或生成供应商未返回的思考内容。工具结果包含图片时，文本保持工具结果语义，图片转换为紧随同批工具结果之后的用户图片消息。无法转换的媒体类型会返回参数错误。

DeepSeek Flash 使用原生路径。强制函数调用需要关闭推理：reasoning: { "effort": "none" }。默认推理模式的工具限制属于模型能力边界，平台不会替客户自动关闭推理。

reasoning.effort 使用标准值 none、minimal、low、medium、high、xhigh、max；省略或 null 使用模型默认行为。非标准 ultra 返回参数错误，不回显非标准枚举。

该组合被模型拒绝时，返回 unsupported_parameter，param 为 tool_choice，文案提示使用自动工具选择，或在模型支持时显式关闭推理。客户不会收到上游原始错误内容。

原生 Responses 不使用平台语义回答缓存，但仍使用会话亲和和上游输入缓存。model 始终返回客户请求的平台模型 ID。

非流式示例

curl -X POST "$TOKENPOSTIE_BASE_URL/v1/responses" \
  -H "Authorization: Bearer $TOKENPOSTIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$TOKENPOSTIE_MODEL"'",
    "input": "请用一句话介绍 TokenPostie",
    "store": false
  }'

响应的 object 为 response。正常完成的 status 为 completed，输出被截断时为 incomplete，原因位于 incomplete_details。文本位于 output 数组的 message Item；函数调用位于独立的 function_call Item。

JavaScript SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKENPOSTIE_API_KEY,
  baseURL: `${process.env.TOKENPOSTIE_BASE_URL}/v1`
});

const response = await client.responses.create({
  model: process.env.TOKENPOSTIE_MODEL,
  input: "请用一句话介绍 TokenPostie",
  store: false
});

console.log(response.output_text);

流式事件

stream: true 时返回 text/event-stream。文本请求至少包含以下生命周期事件：

  • response.created
  • response.output_item.added
  • response.output_text.delta
  • response.output_text.done
  • response.output_item.done
  • response.completed

事件含递增的 sequence_number。正常完成以 response.completed 结束，达到输出上限以 response.incomplete 结束。完成前发生异常、空流或缺少终止事件的连接不会被标记为成功；流已开始时会发送带安全错误文案的 error 事件。完整终态之后不会再追加错误事件。

计费读取真实 usage；input_tokens_details.cached_tokens 按输入缓存价格结算，output_tokens_details.reasoning_tokens 已包含在输出 Token 中，不重复计费。缺失用量不会以估算值冒充真实用量进入确定性账本。

完整 usage 与终态已经确认后，后续网络断连不会撤销已完成调用的费用；内部结算失败会进入恢复核对，不会用估算用量补扣。

普通服务的 access_programs 为 null。供应商提供的缓存写入统计 input_tokens_details.cache_write_tokens 会保留；未提供时不将缓存未命中量或估算值当成实际写入量，部分供应商因此仍存在严格 OpenAI Schema 差异。

TokenPostie-deepseek-flash 未提供缓存写入 Token 数。该字段保持缺失，不是 0；其他真实用量照常返回。严格要求此字段的客户端需要接受这一已声明差异，不能将缺失值当成已知写入量。 该模型默认开启思考。使用 tool_choice: "required" 或指定函数时，应明确设置 reasoning: {"effort":"none"}；平台不会自动关闭思考。

状态边界

TokenPostie 当前不保存 OpenAI response object，因此不能使用 previous_response_id 创建服务端响应链。多轮业务应由客户传回历史 input Item，或使用稳定的 X-TokenPostie-Session-Id 提高上游缓存亲和性。