KToken Docs

Appearance

POST /v1/responses ​

接口用途 ​

OpenAI Responses API 兼容入口，是接入新一代 OpenAI 协议时最重要的接口之一。

请求路径 ​

text
POST /v1/responses
POST /v1/responses/*subpath

完整地址示例：

text
https://your-domain/api/v1/v1/responses

认证方式 ​

  • Authorization: Bearer <API_KEY>，推荐
  • x-api-key: <API_KEY>

Gemini 风格的 x-goog-api-key 不建议用于这个接口。

路由别名 ​

  • POST /responses
  • POST /responses/*subpath
  • POST /backend-api/codex/responses
  • POST /backend-api/codex/responses/*subpath

这些别名语义与主接口一致。

适用平台 ​

  • OpenAI 分组：进入 OpenAI Responses 实现
  • 非 OpenAI 分组：进入 Anthropic 兼容 Responses 实现

上游官方规范 ​

本项目支持说明 ​

  • 自动按分组平台分流
  • 支持流式与非流式
  • 支持根路径别名与 Codex 直连别名
  • 会做内容审核、并发、余额 / 订阅与账号调度
  • 对图片意图会额外做权限判断

参数说明 ​

常用上游标准字段 ​

参数类型必填说明
modelstring是目标模型；本项目用它做调度、映射和限制判断
input`stringarray`否
streamboolean否是否以流式返回事件
toolsarray否工具列表
metadataobject否元数据
previous_response_idstring否上下文续写标识

完整字段请参考 OpenAI 官方规范。

KToken 差异与限制 ​

字段 / 行为说明
model必填，缺失返回 400 invalid_request_error
stream类型必须是布尔值，否则返回 400 invalid stream field type
previous_response_idHTTP 接口当前不支持续写；仅 Responses WebSocket v2 支持
previous_response_id 传 message id如果看起来像 message id 而不是 resp_*，会直接返回 400
function_call_outputHTTP 请求中必须带可关联的 call_id / item_reference；否则返回 400
图片意图当请求被识别为图片生成意图时，还要检查分组是否允许图片能力

响应说明 ​

成功时返回标准 Responses API 对象；流式时返回 SSE 事件流。

成功响应示例 ​

json
{
  "id": "resp_123",
  "object": "response",
  "model": "gpt-4.1",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "你好"
        }
      ]
    }
  ]
}

错误响应 ​

previous_response_id 不支持 ​

json
{
  "error": {
    "type": "invalid_request_error",
    "message": "previous_response_id is only supported on Responses WebSocket v2"
  }
}

传入了 message id ​

json
{
  "error": {
    "type": "invalid_request_error",
    "message": "previous_response_id must be a response.id (resp_*), not a message id"
  }
}

示例请求 ​

bash
curl https://your-domain/api/v1/v1/responses \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "请给我一句简短问候",
    "stream": false
  }'

使用根路径别名 ​

bash
curl https://your-domain/api/v1/responses \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "input": "hello"
  }'

注意事项 ​

  • 如果你确实需要 previous_response_id 续写，请使用 Responses WebSocket
  • 当客户端是 Codex 直连场景时，可改用 /backend-api/codex/responses*
  • 如果你是在配置 Codex 客户端本身，建议先阅读 Codex 配置