创建 Response

POST/responses

鉴权

Bearer API Key

执行方式

按所调用的完整地址执行

查看调用示例

接口说明

本页说明创建 Response能力的共同请求与响应结构，各地址的权益、错误与限制按完整公开地址分别列出。

请求

余额使用地址

套餐使用地址

以下请求头、参数与报文结构适用于本页列出的全部完整公开地址。

• 方法：POST

• 鉴权：Authorization: Bearer ${TOKENFACTORY_API_KEY}

请求头

名称	必填	值或类型	说明
Authorization	是	Bearer ${TOKENFACTORY_API_KEY}	Token Factory API Key
Content-Type	是	application/json	请求体媒体类型

路径参数：无

查询参数：无

请求字段

字段	类型	必填	说明	示例或约束
background	boolean	否	官方后台执行开关；允许省略、null 或 false。Token Factory 当前不实现 Responses 后台生命周期，true 会返回 400 invalid_request_error。	可为 null
context_management	object[]	否	上下文管理配置；允许为 null。	可为 null
context_management[].compact_threshold	integer (int32)	否	触发自动压缩的 Token 阈值；至少为 1000。	最小值：1000；可为 null
context_management[].type	string	父字段存在时必填	当前支持 compaction。	—
conversation	string 或 object	否	官方 Conversation 引用；允许为 null，且不能与 previous_response_id 同时使用。 Token Factory 当前未实现 Conversations 生命周期，非 null 会返回 400 invalid_request_error。	可为 null；形式：string 或 object
include	string[]	否	额外响应数据选择；允许为 null。	可为 null
input	string 或 object[]	否	OpenAI 官方可选的字符串或 Responses 输入项数组；数组项保持开放，可包含文本、图片与内联文件内容块。	示例：[{"content":[{"text":"解释图片与文档","type":"input_text"},{"detail":"auto","image_u...；形式：string 或 object[]
input[].acknowledged_safety_checks	object[]	否	已确认的计算机操作安全检查数组。	—
input[].action	object	否	Web Search 或 Computer 操作。	—
input[].approval_request_id	string	否	MCP 审批请求 ID。	—
input[].approve	boolean	否	是否批准 MCP 调用。	—
input[].arguments	string	否	函数参数 JSON 字符串。	—
input[].authorization	string	否	MCP 调用授权值。	—
input[].call_id	string	否	工具调用 ID。	—
input[].caller	object	否	工具调用来源。	—
input[].command	object	否	Shell 或计算机命令。	—
input[].commands	string[]	否	命令字符串数组。	—
input[].connector_id	string	否	MCP Connector ID。	—
input[].content	string 或 object[]	否	消息文本或图片/内联文件内容块数组。	示例：[{"text":"解释图片与文档","type":"input_text"},{"detail":"auto","image_url":"data:im...；形式：string 或 object[]
input[].content[].detail	string	否	输入图片细节级别；Responses 额外支持 original。	可选值："auto"、"low"、"high"、"original"
input[].content[].file_data	string	否	Base64 data URL 文件内容。	—
input[].content[].file_id	string	否	官方 Files 引用 ID；Token Factory 当前未实现 Files 生命周期，发送即返回 400 invalid_request_error。	—
input[].content[].file_url	string	否	文件 URL。	—
input[].content[].filename	string	否	内联文件名。	—
input[].content[].image_url	string	否	图片 URL 或 data URL。	—
input[].content[].prompt_cache_breakpoint	object	否	显式 Prompt Cache 断点。	—
input[].content[].text	string	否	输入文本。	示例："解释图片与文档"
input[].content[].type	string	父字段存在且匹配该形式时必填	输入内容块类型。	示例："input_text"；可选值："input_text"、"input_image"、"input_file"
input[].encrypted_content	string	否	不透明加密上下文。	—
input[].id	string	否	既有输入项 ID。	—
input[].name	string	否	工具或函数名。	—
input[].namespace	string	否	工具命名空间。	—
input[].output	object	否	工具调用输出。	—
input[].pending_safety_checks	object[]	否	等待确认的计算机操作安全检查数组。	—
input[].queries	string[]	否	搜索查询字符串数组。	—
input[].results	object[]	否	工具调用结果数组。	—
input[].role	string	否	消息角色。	示例："user"
input[].server_label	string	否	MCP Server 标签。	—
input[].server_url	string	否	MCP Server URL。	—
input[].shell_id	string	否	Shell 会话 ID。	—
input[].status	string	否	输出项状态。	可选值："in_progress"、"completed"、"incomplete"
input[].summary	object[]	否	Reasoning 摘要块数组。	—
input[].tools	object[]	否	动态发现的工具定义数组。	—
input[].type	string	否	输入项类型。	—
instructions	string	否	系统级指令字符串。	示例："请准确回答"；可为 null
max_output_tokens	integer (int32)	否	最大输出 Token 数，包含可见与 Reasoning Token；至少为 16。	最小值：16；可为 null
max_tool_calls	integer (int32)	否	单次响应允许处理的内置工具调用总数；官方未规定最小值。	可为 null
metadata	object	否	随 Response 保存的元数据；最多 16 个字符串键值对。	可为 null
model	string	否	OpenAI 官方可选且提供时不能为 null 的模型 ID；Token Factory 仅在 previous_response_id 或加密上下文能恢复原模型亲和时允许省略，无上下文省略时返回 400 invalid_request_error。	示例："YOUR_MODEL_ID"
moderation	object	否	输入和输出的 Moderation 配置。	可为 null
moderation.model	string	父字段存在时必填	Moderation 模型 ID。	—
moderation.policy	object	否	输入和输出的 score/block 策略。	—
parallel_tool_calls	boolean	否	是否允许并行工具调用；允许为 null。	可为 null
previous_response_id	string	否	要延续的上一次 Response ID；允许为 null。	可为 null
prompt	object	否	官方可复用 Prompt 模板引用；允许为 null。Token Factory 当前未实现远程 Prompt 生命周期，提供带非 null id 的引用会返回 400 invalid_request_error。	可为 null
prompt_cache_key	string	否	Prompt Cache 路由键；允许为 null，最长 64 个字符。	示例："example-cache-key"；最长：64 字符；可为 null
prompt_cache_options	object	否	Prompt Cache 选项。	—
prompt_cache_options.mode	string	否	缓存断点模式。	可选值："implicit"、"explicit"
prompt_cache_options.ttl	string	否	缓存生存时间。	可选值："30m"
prompt_cache_retention	string	否	已弃用的 Prompt Cache 保留策略；允许为 null。	可选值："in_memory"、"24h"；可为 null
reasoning	object	否	Reasoning 设置；允许为 null。	示例：{"effort":"high","summary":"auto"}；可为 null
reasoning.context	string	否	纳入 Reasoning 上下文的范围；允许为 null。	可选值："auto"、"current_turn"、"all_turns"；可为 null
reasoning.effort	string	否	Reasoning 强度；允许为 null，具体可用值取决于模型。	示例："high"；可选值："none"、"minimal"、"low"、"medium"、"high"、"xhigh"、"max"；可为 null
reasoning.generate_summary	string	否	已弃用的摘要模式；请改用 summary。允许为 null。	可选值："auto"、"concise"、"detailed"；可为 null
reasoning.mode	string	否	Reasoning 模式；当前官方已知 standard、pro，字符串值域向前兼容。	—
reasoning.summary	string	否	Reasoning 摘要模式；允许为 null。	示例："auto"；可选值："auto"、"concise"、"detailed"；可为 null
safety_identifier	string	否	非识别性的安全标识；建议使用哈希值，禁止直接发送 PII。	最长：64 字符；可为 null
service_tier	string	否	服务处理等级；允许为 null。	可选值："auto"、"default"、"flex"、"scale"、"priority"、"fast"、"ultrafast"；可为 null
store	boolean	否	是否存储生成结果；允许为 null。	示例：false；可为 null
stream	boolean	否	是否使用 Responses SSE 事件流；省略或 null 等同 false。	示例：false；可为 null
stream_options	object	否	仅在 stream=true 时使用的 Responses 流式选项。	可为 null
stream_options.include_obfuscation	boolean	否	是否在事件中加入混淆填充字段。	—
temperature	number	否	采样温度，范围 0 到 2。	最小值：0；最大值：2；可为 null
text	object	否	结构化文本输出与回答详细程度设置。	示例：{"format":{"name":"answer","schema":{"type":"object"},"type":"json_schema"}}
text.format	object	否	文本或 JSON 结构化输出格式。	示例：{"name":"answer","schema":{"type":"object"},"type":"json_schema"}
text.format.description	string	否	JSON Schema 说明。	—
text.format.name	string	否	JSON Schema 名称。	示例："answer"
text.format.schema	object	否	JSON Schema 定义。	示例：
text.format.strict	boolean	否	是否严格遵守 JSON Schema；允许为 null。	可为 null
text.format.type	string	父字段存在时必填	输出格式类型。	示例："json_schema"；可选值："text"、"json_object"、"json_schema"
text.verbosity	string	否	回答详细程度；允许为 null。	可选值："low"、"medium"、"high"；可为 null
tool_choice	string 或 object	否	工具选择模式或指定工具对象。	形式：string 或 object
tools	object[]	否	官方 Responses 工具定义数组；未知未来工具字段保持开放。	示例：[{"name":"lookup","parameters":{"properties":{},"type":"object"},"type":"func...
top_logprobs	integer (int32)	否	每个位置返回的候选 Token 数，范围 0 到 20。	最小值：0；最大值：20；可为 null
top_p	number	否	核采样概率质量，范围 0 到 1。	最小值：0；最大值：1；可为 null
truncation	string	否	上下文截断策略；允许为 null。	可选值："auto"、"disabled"；可为 null
user	string	否	已弃用的终端用户标识；请改用 safety_identifier 与 prompt_cache_key。	—

请求报文

媒体类型：application/json

{
  "input": [
    {
      "content": [
        {
          "text": "解释图片与文档",
          "type": "input_text"
        },
        {
          "detail": "auto",
          "image_url": "data:image/png;base64,...",
          "type": "input_image"
        },
        {
          "file_data": "data:application/pdf;base64,...",
          "filename": "example.pdf",
          "type": "input_file"
        }
      ],
      "role": "user"
    }
  ],
  "instructions": "请准确回答",
  "model": "YOUR_MODEL_ID",
  "prompt_cache_key": "example-cache-key",
  "reasoning": {
    "effort": "high",
    "summary": "auto"
  },
  "store": false,
  "stream": false,
  "text": {
    "format": {
      "name": "answer",
      "schema": {
        "type": "object"
      },
      "type": "json_schema"
    }
  },
  "tools": [
    {
      "name": "lookup",
      "parameters": {
        "properties": {},
        "type": "object"
      },
      "type": "function"
    }
  ]
}

响应

成功状态：200

响应头

名称	值或类型	说明
Content-Type	application/json 或 text/event-stream	响应媒体类型
retry-after	string	上游限流或暂时不可用时保留的重试等待秒数。
x-ratelimit-limit-input-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-output-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-requests	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-limit-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-input-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-output-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-requests	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-remaining-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-input-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-output-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-requests	string	上游返回时安全保留的 OpenAI 限额信息。
x-ratelimit-reset-tokens	string	上游返回时安全保留的 OpenAI 限额信息。
x-request-id	string	本次 OpenAI 协议请求的关联 ID；上游未提供时由 Token Factory 生成。

响应字段

OpenAI Responses 成功终态；官方新增字段保持开放。 下表完整列出当前公开协议明确声明的字段；开放扩展只允许未声明的附加字段，不会放宽已声明字段的必填、类型或枚举约束。

字段	类型	必填	说明	示例或约束
background	boolean	否	是否在后台运行；允许为 null。	可为 null
completed_at	number	否	完成时的 Unix 秒时间戳；未完成时为 null。	最小值：0；可为 null
conversation	object	否	所属 Conversation；允许为 null。	可为 null
created_at	number	是	Response 创建时间的 Unix 秒时间戳；官方 wire 类型为 number。	示例：1787832000；最小值：0
error	object	是	失败详情；没有失败时为 null。	示例：null；可为 null
id	string	是	Response ID。	示例："resp_example"
incomplete_details	object	是	未完成详情；状态不是 incomplete 时为 null。	示例：null；可为 null
instructions	string 或 object[]	是	本次使用的系统/开发者指令；允许为 null。	示例："请准确回答"；可为 null；形式：string 或 object[]
instructions[].acknowledged_safety_checks	object[]	否	已确认的计算机操作安全检查数组。	—
instructions[].action	object	否	Web Search 或 Computer 操作。	—
instructions[].approval_request_id	string	否	MCP 审批请求 ID。	—
instructions[].approve	boolean	否	是否批准 MCP 调用。	—
instructions[].arguments	string	否	函数参数 JSON 字符串。	—
instructions[].authorization	string	否	MCP 调用授权值。	—
instructions[].call_id	string	否	工具调用 ID。	—
instructions[].caller	object	否	工具调用来源。	—
instructions[].command	object	否	Shell 或计算机命令。	—
instructions[].commands	string[]	否	命令字符串数组。	—
instructions[].connector_id	string	否	MCP Connector ID。	—
instructions[].content	string 或 object[]	否	消息文本或图片/内联文件内容块数组。	形式：string 或 object[]
instructions[].content[].detail	string	否	输入图片细节级别；Responses 额外支持 original。	可选值："auto"、"low"、"high"、"original"
instructions[].content[].file_data	string	否	Base64 data URL 文件内容。	—
instructions[].content[].file_id	string	否	官方 Files 引用 ID；Token Factory 当前未实现 Files 生命周期，发送即返回 400 invalid_request_error。	—
instructions[].content[].file_url	string	否	文件 URL。	—
instructions[].content[].filename	string	否	内联文件名。	—
instructions[].content[].image_url	string	否	图片 URL 或 data URL。	—
instructions[].content[].prompt_cache_breakpoint	object	否	显式 Prompt Cache 断点。	—
instructions[].content[].text	string	否	输入文本。	—
instructions[].content[].type	string	父字段存在且匹配该形式时必填	输入内容块类型。	可选值："input_text"、"input_image"、"input_file"
instructions[].encrypted_content	string	否	不透明加密上下文。	—
instructions[].id	string	否	既有输入项 ID。	—
instructions[].name	string	否	工具或函数名。	—
instructions[].namespace	string	否	工具命名空间。	—
instructions[].output	object	否	工具调用输出。	—
instructions[].pending_safety_checks	object[]	否	等待确认的计算机操作安全检查数组。	—
instructions[].queries	string[]	否	搜索查询字符串数组。	—
instructions[].results	object[]	否	工具调用结果数组。	—
instructions[].role	string	否	消息角色。	—
instructions[].server_label	string	否	MCP Server 标签。	—
instructions[].server_url	string	否	MCP Server URL。	—
instructions[].shell_id	string	否	Shell 会话 ID。	—
instructions[].status	string	否	输出项状态。	可选值："in_progress"、"completed"、"incomplete"
instructions[].summary	object[]	否	Reasoning 摘要块数组。	—
instructions[].tools	object[]	否	动态发现的工具定义数组。	—
instructions[].type	string	否	输入项类型。	—
max_output_tokens	integer (int32)	否	本次最大输出 Token 数；允许为 null。	最小值：1；可为 null
max_tool_calls	integer (int32)	否	本次最大内置工具调用数；允许为 null。	可为 null
metadata	object	是	随 Response 返回的元数据；允许为 null。	示例：{"request_kind":"documentation_example"}；可为 null
model	string	是	实际模型 ID。	示例："YOUR_MODEL_ID"
moderation	object	否	输入与输出 Moderation 结果；官方允许省略或为 null。	可为 null
moderation.input	object	父字段存在时必填	输入内容的 Moderation 结果或错误。	—
moderation.output	object	父字段存在时必填	输出内容的 Moderation 结果或错误。	—
object	string	是	固定为 response。	示例："response"；可选值："response"
output	object 或 object 或 object 或 object 或 object[]	是	Responses 输出项数组；可为空。	示例：[{"content":[{"annotations":[],"logprobs":[],"text":"你好","type":"output_text"...；最少：0 项
output[].content	object 或 object[] 或 object[]	匹配该形式时必填	文本输出或拒答内容块数组。；Reasoning 正文；官方可省略或为 null。	示例：[{"annotations":[],"logprobs":[],"text":"你好","type":"output_text"}]；示例：[{"annotations":[],"logprobs":[],"text":"你好","type":"output_text"}]；可为 null
output[].content[].annotations	object[]	匹配该形式时必填	输出文本注释数组。	示例：[]
output[].content[].logprobs	object[]	否	输出 Token 对数概率数组。	示例：[]
output[].content[].logprobs[].logprob	number	父字段存在且匹配该形式时必填	Token 对数概率。	—
output[].content[].logprobs[].token	string	父字段存在且匹配该形式时必填	Token 文本。	—
output[].content[].logprobs[].top_logprobs	object[]	否	该位置的候选 Token 对数概率数组。	—
output[].content[].text	string	父字段存在且匹配该形式时必填	输出文本。；Reasoning 正文文本。	示例："你好"
output[].content[].type	string	父字段存在且匹配该形式时必填	固定为 output_text。；固定为 refusal。；固定为 reasoning_text。	示例："output_text"；可选值："output_text"；示例："output_text"；可选值："refusal"；示例："output_text"；可选值："reasoning_text"
output[].content[].refusal	string	匹配该形式时必填	拒答说明。	—
output[].id	string	匹配该形式时必填	输出消息 ID。；Reasoning 项 ID。；Compaction 项 ID。；输出项 ID；官方可省略或为 null。 ；输出项 ID。	示例："msg_example"；示例："msg_example"；可为 null；示例："msg_example"
output[].phase	string	否	Codex 类模型的中间说明或最终答案阶段；官方可省略。	可选值："commentary"、"final_answer"；可为 null
output[].role	string	匹配该形式时必填	固定为 assistant。	示例："assistant"；可选值："assistant"
output[].status	string	匹配该形式时必填	输出项状态。；Reasoning 输出项状态；官方可省略或为 null。 ；调用状态；官方可省略或为 null。 ；工具输出项状态；不同类型可省略或为 null。	示例："completed"；可选值："in_progress"、"completed"、"incomplete"；示例："completed"；可选值："in_progress"、"completed"、"incomplete"；可为 null；示例："completed"；可选值："in_progress"、"completed"、"incomplete"；可为 null；示例："completed"；可选值："in_progress"、"completed"、"incomplete"；可为 null
output[].type	string	匹配该形式时必填	固定为 message。；固定为 reasoning。；固定为 compaction。；固定为 function_call。；工具输出项类型。	示例："message"；可选值："message"；示例："message"；可选值："reasoning"；示例："message"；可选值："compaction"；示例："message"；可选值："function_call"；示例："message"；可选值："additional_tools"、"apply_patch_call"、"apply_patch_call_output"、"code_interpreter_call"、"computer_call"、"computer_call_output"、"custom_tool_call"、"custom_tool_call_output"、"file_search_call"、"function_call_output"、"image_generation_call"、"local_shell_call"、"local_shell_call_output"、"mcp_call"、"mcp_approval_request"、"mcp_approval_response"、"mcp_list_tools"、"program"、"program_output"、"shell_call"、"shell_call_output"、"tool_search_call"、"tool_search_output"、"web_search_call"
output[].encrypted_content	string	匹配该形式时必填	可原样续接的不透明加密上下文。；必须原样续接的不透明加密上下文。	可为 null
output[].summary	object[]	匹配该形式时必填	Reasoning 摘要文本块数组。	—
output[].summary[].text	string	匹配该形式时必填	摘要文本。	—
output[].summary[].type	string	匹配该形式时必填	固定为 summary_text。	可选值："summary_text"
output[].created_by	string	否	创建该项的 actor ID。	—
output[].arguments	string	匹配该形式时必填	函数参数字符串；官方不保证有效 JSON，也允许空字符串。	—
output[].call_id	string	匹配该形式时必填	客户端回传结果时使用的调用 ID。	—
output[].caller	object 或 object	否	调用来源；官方可省略或为 null。	可为 null；形式：object 或 object
output[].caller.type	string	父字段存在且匹配该形式时必填	固定为 direct。；固定为 program。	可选值："direct"；可选值："program"
output[].caller.caller_id	string	父字段存在且匹配该形式时必填	来源 program 调用 ID。	—
output[].name	string	匹配该形式时必填	函数名。	—
output[].namespace	string	否	函数命名空间；官方可省略或为 null。	可为 null
parallel_tool_calls	boolean	是	是否允许模型并行调用工具。	示例：true
previous_response_id	string	否	上一次 Response ID；允许为 null。	可为 null
prompt	object	否	可复用 Prompt 引用；允许为 null。	可为 null
prompt_cache_key	string	否	Prompt Cache 路由键；允许为 null。	可为 null
prompt_cache_options	object	否	Prompt Cache 选项。	—
prompt_cache_options.mode	string	否	缓存断点模式。	可选值："implicit"、"explicit"
prompt_cache_options.ttl	string	否	缓存生存时间。	可选值："30m"
prompt_cache_retention	string	否	已弃用的 Prompt Cache 保留策略；允许为 null。	可选值："in_memory"、"24h"；可为 null
reasoning	object	否	本次实际使用的 Reasoning 设置；允许为 null。	可为 null
reasoning.context	string	否	纳入 Reasoning 上下文的范围；允许为 null。	可选值："auto"、"current_turn"、"all_turns"；可为 null
reasoning.effort	string	否	Reasoning 强度；允许为 null，具体可用值取决于模型。	可选值："none"、"minimal"、"low"、"medium"、"high"、"xhigh"、"max"；可为 null
reasoning.generate_summary	string	否	已弃用的摘要模式；请改用 summary。允许为 null。	可选值："auto"、"concise"、"detailed"；可为 null
reasoning.mode	string	否	Reasoning 模式；当前官方已知 standard、pro，字符串值域向前兼容。	—
reasoning.summary	string	否	Reasoning 摘要模式；允许为 null。	可选值："auto"、"concise"、"detailed"；可为 null
safety_identifier	string	否	非识别性的安全标识；允许为 null。	可为 null
service_tier	string	否	实际服务处理等级；允许为 null。	可选值："auto"、"default"、"flex"、"scale"、"priority"、"fast"、"ultrafast"；可为 null
status	string	否	响应状态；官方可省略或为 null，提供非 null 值时必须是合法状态。	示例："completed"；可选值："cancelled"、"completed"、"failed"、"in_progress"、"incomplete"、"queued"；可为 null
temperature	number	是	本次采样温度；允许为 null。	示例：1；最小值：0；最大值：2；可为 null
text	object	否	本次实际使用的文本输出设置；官方可省略。	—
text.format	object	否	文本或 JSON 结构化输出格式。	—
text.format.description	string	否	JSON Schema 说明。	—
text.format.name	string	否	JSON Schema 名称。	—
text.format.schema	object	否	JSON Schema 定义。	—
text.format.strict	boolean	否	是否严格遵守 JSON Schema；允许为 null。	可为 null
text.format.type	string	父字段存在时必填	输出格式类型。	可选值："text"、"json_object"、"json_schema"
text.verbosity	string	否	回答详细程度；允许为 null。	可选值："low"、"medium"、"high"；可为 null
tool_choice	string 或 object	是	工具选择模式或指定工具对象。	示例："auto"；形式：string 或 object
tools	object[]	是	本次可用的工具数组。	示例：[]
top_logprobs	integer (int32)	否	每个位置返回的候选 Token 数；允许为 null。	最小值：0；最大值：20；可为 null
top_p	number	是	本次核采样概率质量；允许为 null。	示例：1；最小值：0；最大值：1；可为 null
truncation	string	否	上下文截断策略；允许为 null。	可选值："auto"、"disabled"；可为 null
usage	object	否	官方可省略或为 null；Token Factory 对需要计费的可兑现成功终态额外要求可信 Usage，缺失时失败关闭而不会把不完整 2xx 返回给客户端。	示例：{"input_tokens":31,"input_tokens_details":{"cache_write_tokens":0,"cached_tok...；可为 null
usage.input_tokens	integer (int32)	父字段存在时必填	输入 Token 数。	示例：31；最小值：0
usage.input_tokens_details	object	父字段存在时必填	输入 Token 分类明细。	示例：
usage.input_tokens_details.cache_write_tokens	integer (int32)	父字段存在时必填	写入 Prompt Cache 的 Token 数。	示例：0；最小值：0
usage.input_tokens_details.cached_tokens	integer (int32)	父字段存在时必填	从 Prompt Cache 读取的 Token 数。	示例：0；最小值：0
usage.output_tokens	integer (int32)	父字段存在时必填	输出 Token 数。	示例：9；最小值：0
usage.output_tokens_details	object	父字段存在时必填	输出 Token 分类明细。	示例：
usage.output_tokens_details.reasoning_tokens	integer (int32)	父字段存在时必填	Reasoning Token 数。	示例：0；最小值：0
usage.total_tokens	integer (int32)	父字段存在时必填	输入与输出 Token 总数。	示例：40；最小值：0
user	string	否	已弃用的终端用户标识；允许为 null。	可为 null

返回报文

媒体类型：application/json

{
  "created_at": 1787832000,
  "error": null,
  "id": "resp_example",
  "incomplete_details": null,
  "instructions": "请准确回答",
  "metadata": {
    "request_kind": "documentation_example"
  },
  "model": "YOUR_MODEL_ID",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "你好",
          "type": "output_text"
        }
      ],
      "id": "msg_example",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "status": "completed",
  "temperature": 1,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1,
  "usage": {
    "input_tokens": 31,
    "input_tokens_details": {
      "cache_write_tokens": 0,
      "cached_tokens": 0
    },
    "output_tokens": 9,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 40
  }
}

SSE 返回报文

媒体类型：text/event-stream

允许事件：response.created、response.in_progress、response.queued、response.output_item.*、response.content_part.*、response.output_text.*、response.refusal.*、response.function_call_arguments.*、response.reasoning_summary_part.*、response.reasoning_summary_text.*、response.reasoning_text.*、response.audio.*、response.audio_transcript.*、response.file_search_call.*、response.web_search_call.*、response.image_generation_call.*、response.code_interpreter_call.*、response.mcp_call.*、response.mcp_call_arguments.*、response.custom_tool_call_input.*、response.completed、response.incomplete、response.failed、error

协议终态：response.completed、response.incomplete、response.failed、error

event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_example","object":"response","created_at":1787832000,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"请准确回答","metadata":{},"model":"YOUR_MODEL_ID","output":[],"parallel_tool_calls":true,"temperature":1.0,"tool_choice":"auto","tools":[],"top_p":1.0}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{"id":"resp_example","object":"response","created_at":1787832000,"status":"in_progress","error":null,"incomplete_details":null,"instructions":"请准确回答","metadata":{},"model":"YOUR_MODEL_ID","output":[],"parallel_tool_calls":true,"temperature":1.0,"tool_choice":"auto","tools":[],"top_p":1.0}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"msg_example","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":3,"item_id":"msg_example","output_index":0,"content_index":0,"part":{"type":"output_text","annotations":[],"logprobs":[],"text":""}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":4,"item_id":"msg_example","output_index":0,"content_index":0,"delta":"你好","logprobs":[]}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":5,"item_id":"msg_example","output_index":0,"content_index":0,"text":"你好","logprobs":[]}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":6,"item_id":"msg_example","output_index":0,"content_index":0,"part":{"type":"output_text","annotations":[],"logprobs":[],"text":"你好"}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":7,"output_index":0,"item":{"id":"msg_example","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"你好"}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":8,"response":{"id":"resp_example","object":"response","created_at":1787832000,"status":"completed","error":null,"incomplete_details":null,"instructions":"请准确回答","metadata":{},"model":"YOUR_MODEL_ID","output":[{"id":"msg_example","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"你好"}]}],"parallel_tool_calls":true,"temperature":1.0,"tool_choice":"auto","tools":[],"top_p":1.0,"usage":{"input_tokens":31,"input_tokens_details":{"cached_tokens":0,"cache_write_tokens":0},"output_tokens":9,"output_tokens_details":{"reasoning_tokens":0},"total_tokens":40}}}

只有上方列出的协议终态才表示流正常结束；连接中断不代表请求未执行。若已经收到部分内容，不要无条件重放同一请求。

错误

适用完整地址	状态	错误码	常见触发	重试	建议动作	结果风险
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	401	invalid_api_key	Authorization 缺失、Bearer 格式错误、Key 不可用或账户未实名	否	检查 Bearer API Key、Key 状态与实名状态	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	400	model_not_found	模型存在，但不具备当前端点要求的能力	否	改用支持当前端点能力的模型，或改为调用该模型支持的端点	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	404	model_not_found	模型不存在、未上架或当前入口不可用	否	调用模型列表并改用当前入口可用模型	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	404	MODEL_ROUTING_PROTOCOL_UNSUPPORTED	模型未开放当前 API 接口对应协议	否	改用该模型已开放的协议或其他模型	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	503	MODEL_ROUTING_NOT_CONFIGURED	模型的协议路由尚未配置	视情况	稍后重试；持续出现时联系平台确认路由配置	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	503	MODEL_ROUTING_POLICY_INVALID	模型协议路由策略状态异常	视情况	稍后重试；持续出现时联系平台检查路由策略	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	503	MODEL_ROUTING_NO_HEALTHY_ROUTE	模型当前没有健康供应路线	是，退避后	指数退避后重试或临时改用其他模型	无
https://api.tokenfactory.cn/v1/responses	429	insufficient_balance	账户可用余额不足	否	充值后重新发起请求	无
https://api.tokenfactory.cn/v1/responses	429	balance_daily_limit_exceeded	账户当天余额消费已达到自助上限	否	调整每日上限或等待次日恢复	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	413	request_too_large	请求体超过平台接收上限	否	缩小请求体后重试	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	400	invalid_request_error	请求参数或请求体缺字段、格式错误或不受支持	否	修正请求后重试	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	502	upstream_error	供应商连接失败或返回异常响应	视情况	确认未收到有效结果后再决定是否重试	中到高
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	504	upstream_timeout	供应商在平台超时时间内未完成响应	视情况	先确认是否已有部分输出，再决定是否重试	中到高
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	500	internal_error	平台内部出现未预期错误	视情况	确认未收到有效结果并记录请求时间后再决定是否重试	中到高
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	405	method_not_allowed	请求方法不是该公开地址允许的方法	否	改用文档列出的 HTTP 方法	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	415	unsupported_media_type	Content-Type 与该公开地址要求的媒体类型不一致	否	按文档发送正确 Content-Type	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	403	permission_denied	当前 API Key 或上游账户无权执行该请求	否	检查权限、模型可见性与供应商授权	无
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	409	conflict_error	请求与上游资源当前状态冲突	视情况	读取最新状态后修正请求或稍后重试	中到高
https://api.tokenfactory.cn/v1/responses https://api.tokenfactory.cn/v1/coding/responses	422	unprocessable_entity	请求结构正确但上游无法处理其中的语义	否	按错误信息修正参数或输入内容	无
https://api.tokenfactory.cn/v1/coding/responses	429	insufficient_package	账户没有可用 Coding Plan	否	购买或启用可用套餐	无
https://api.tokenfactory.cn/v1/coding/responses	429	package_expired	Coding Plan 已过期	否	续费套餐后重新发起请求	无
https://api.tokenfactory.cn/v1/coding/responses	400	model_not_in_package	所选模型不在当前套餐支持范围	否	改用套餐支持的模型	无
https://api.tokenfactory.cn/v1/coding/responses	429	package_5h_quota_exhausted	5 小时套餐窗口额度已用尽	否	等待窗口恢复或升级套餐	无
https://api.tokenfactory.cn/v1/coding/responses	429	package_weekly_quota_exhausted	每周套餐窗口额度已用尽	否	等待窗口恢复或升级套餐	无
https://api.tokenfactory.cn/v1/coding/responses	429	package_concurrency_limited	当前套餐并发调用数已达上限	是，退避后	等待在途调用结束后再试	无
https://api.tokenfactory.cn/v1/coding/responses	413	package_input_too_large	请求超过 Coding Plan 输入字节上限	否	缩短输入后重试	无
https://api.tokenfactory.cn/v1/coding/responses	400	package_output_limit_exceeded	请求的输出 Token 上限超过套餐限制	否	降低输出上限后重试	无

错误返回报文

适用完整地址

https://api.tokenfactory.cn/v1/responses、https://api.tokenfactory.cn/v1/coding/responses

HTTP 400；Content-Type: application/json；响应头：retry-after: string、x-ratelimit-limit-input-tokens: string、x-ratelimit-limit-output-tokens: string、x-ratelimit-limit-requests: string、x-ratelimit-limit-tokens: string、x-ratelimit-remaining-input-tokens: string、x-ratelimit-remaining-output-tokens: string、x-ratelimit-remaining-requests: string、x-ratelimit-remaining-tokens: string、x-ratelimit-reset-input-tokens: string、x-ratelimit-reset-output-tokens: string、x-ratelimit-reset-requests: string、x-ratelimit-reset-tokens: string、x-request-id: string

{
  "error": {
    "code": "model_not_found",
    "message": "模型存在，但不具备当前端点要求的能力",
    "param": null,
    "type": "invalid_request_error"
  }
}

适用完整地址：https://api.tokenfactory.cn/v1/responses、https://api.tokenfactory.cn/v1/coding/responses

供应商非 2xx 响应会归一化为当前公开协议的错误信封，并只保留安全响应头；502、504 或连接中断时，调用结果可能未知。

限制与计费

适用完整地址	限制或计费说明
https://api.tokenfactory.cn/v1/responses	请求成功后按通用余额计费；余额不足时调用失败。 受全局请求体上限约束。 模型上下文与输出限制依当前模型和上游事实而定。 支持文本、图片/OCR/看图问答、内联文件、Tools、Structured Output、Reasoning 和 Prompt Cache。 不支持 file_id/Files 生命周期、background、Conversations 资源、WebSocket 或独立 Realtime。 余额计费调用不会自动改用 Coding Plan 权益。
https://api.tokenfactory.cn/v1/coding/responses	请求按 Coding Plan 独立权益计入用量；套餐不可用时调用失败。 受全局请求体上限约束。 Coding Plan 权益、并发与模型限制按当前套餐事实执行。 支持文本、图片/OCR/看图问答、内联文件、Tools、Structured Output、Reasoning 和 Prompt Cache。 不支持 file_id/Files 生命周期、background、Conversations 资源、WebSocket 或独立 Realtime。 Coding Plan 权益独立核验；套餐不可用时不会自动改扣余额。

调用示例

cURL · https://api.tokenfactory.cn/v1/responses

curl --request POST "https://api.tokenfactory.cn/v1/responses" --silent --show-error --fail-with-body --max-time 60 --header "Authorization: Bearer ${TOKENFACTORY_API_KEY}" --header "Content-Type: application/json" --data "{\"model\":\"${TOKENFACTORY_MODEL_ID}\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"你好\"}]}],\"stream\":false}"

cURL · https://api.tokenfactory.cn/v1/coding/responses

curl --request POST "https://api.tokenfactory.cn/v1/coding/responses" --silent --show-error --fail-with-body --max-time 60 --header "Authorization: Bearer ${TOKENFACTORY_API_KEY}" --header "Content-Type: application/json" --data "{\"model\":\"${TOKENFACTORY_MODEL_ID}\",\"input\":[{\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"你好\"}]}],\"stream\":false}"

相关说明

请求与响应按当前 OpenAI 兼容能力开放；供应商扩展字段可能随所选模型变化。

• 兼容性说明

• 错误处理

• 流式与重试