ResponsesRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kimi-ai/json-schema/kimi-ai-responses-request-schema.json",
  "title": "ResponsesRequest",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/kimi-ai-responses-api-openapi.yml#/components/schemas/ResponsesRequest",
  "type": "object",
  "required": [
    "model",
    "input"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "使用的模型 ID。本接口当前支持 `kimi-k3.1-pro`、`kimi-k3.1-pro-highspeed` 和 `kimi-k3`。"
    },
    "input": {
      "description": "本次请求的输入。传字符串等价于一条 user 消息；传数组时按顺序给出带类型的 item，可包含历史对话、工具调用与工具结果。",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ResponsesInputItem"
          }
        }
      ]
    },
    "instructions": {
      "type": "string",
      "description": "顶层系统指令，作为最靠前的指令生效。"
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "为 true 时以 SSE 事件流返回响应。"
    },
    "max_output_tokens": {
      "type": "integer",
      "description": "本次响应最多生成的 Token 数量。Kimi K3 系列（`kimi-k3.1-pro`、`kimi-k3.1-pro-highspeed`、`kimi-k3`）默认为 131072，最大可设置为 1048576。此值为期望返回的 Token 长度，而非输入加输出的总长度。达到上限时 `status` 为 `incomplete`，`incomplete_details.reason` 为 `max_output_tokens`。"
    },
    "reasoning": {
      "type": "object",
      "description": "推理相关配置。",
      "properties": {
        "effort": {
          "type": "string",
          "enum": [
            "low",
            "high",
            "max"
          ],
          "default": "max",
          "description": "推理强度。档位越高，模型推理越充分，通常也会带来更高的延迟与推理 Token 消耗。"
        }
      }
    },
    "text": {
      "type": "object",
      "description": "输出文本配置。",
      "properties": {
        "format": {
          "type": "object",
          "required": [
            "type",
            "schema"
          ],
          "description": "用 JSON Schema 约束输出结构。",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "json_schema"
              ]
            },
            "name": {
              "type": "string",
              "description": "Schema 名称，缺省为 `output`。"
            },
            "schema": {
              "type": "object",
              "description": "描述输出结构的 JSON Schema。"
            },
            "strict": {
              "type": "boolean",
              "description": "是否严格按 Schema 约束输出。"
            }
          }
        }
      }
    },
    "tools": {
      "type": "array",
      "description": "模型可调用的工具列表。",
      "items": {
        "$ref": "#/$defs/ResponsesTool"
      }
    },
    "tool_choice": {
      "$ref": "#/$defs/ResponsesToolChoice"
    },
    "include": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "web_search_call.results",
          "web_search_call.action.sources"
        ]
      },
      "description": "要额外返回的字段，仅在使用 `web_search` 工具时有效。`web_search_call.action.sources` 返回搜索命中的网页来源；`web_search_call.results` 返回图片搜索结果。"
    },
    "prompt_cache_key": {
      "type": "string",
      "description": "上下文缓存标识，同一会话使用相同取值可提升缓存命中率。"
    },
    "prompt_cache_options": {
      "type": "object",
      "description": "上下文缓存写入选项。不传时默认开启缓存写入（5m 档）：系统自动将请求前缀写入 5m 档缓存",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "implicit"
          ],
          "default": "implicit",
          "description": "缓存写入模式，仅支持 implicit：自动将请求前缀写入缓存"
        },
        "ttl": {
          "type": "string",
          "enum": [
            "5m",
            "1h"
          ],
          "default": "5m",
          "description": "缓存写入的有效期，5m 与 1h 两档缓存相互独立。相同前缀的请求在有效期内命中后，缓存有效期按原 TTL 刷新"
        }
      }
    },
    "safety_identifier": {
      "type": "string",
      "description": "用于检测可能违反使用政策的用户的稳定标识符。应为唯一标识每个用户的字符串。建议对用户名或邮箱进行哈希处理以避免发送可识别信息"
    }
  },
  "$defs": {
    "ResponsesAdditionalToolsItem": {
      "type": "object",
      "title": "动态工具",
      "description": "在对话中途追加可调用的工具，作用范围从该 item 所在位置开始。",
      "required": [
        "type",
        "role",
        "tools"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "additional_tools"
          ]
        },
        "id": {
          "type": "string"
        },
        "role": {
          "type": "string",
          "enum": [
            "developer"
          ]
        },
        "tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/ResponsesTool"
          }
        }
      }
    },
    "ResponsesCustomTool": {
      "type": "object",
      "title": "自定义工具",
      "description": "接收自由文本输入的自定义工具。当前仅支持名为 `apply_patch` 的自定义工具，且必须提供 `grammar` + `lark` 格式定义；模型调用时在 output 中返回 `custom_tool_call` item。",
      "required": [
        "type",
        "name",
        "format"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "custom"
          ]
        },
        "name": {
          "type": "string",
          "enum": [
            "apply_patch"
          ],
          "description": "工具名称，当前仅支持 `apply_patch`。"
        },
        "description": {
          "type": "string"
        },
        "format": {
          "type": "object",
          "description": "输入格式约束。当前仅支持 `grammar` 类型与 `lark` 语法。",
          "required": [
            "type",
            "syntax",
            "definition"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "grammar"
              ]
            },
            "syntax": {
              "type": "string",
              "enum": [
                "lark"
              ]
            },
            "definition": {
              "type": "string",
              "description": "Lark 语法定义。"
            }
          }
        }
      }
    },
    "ResponsesCustomToolCallItem": {
      "type": "object",
      "title": "自定义工具调用",
      "description": "回放一次自定义工具调用。",
      "required": [
        "type",
        "call_id",
        "name",
        "input"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "custom_tool_call"
          ]
        },
        "id": {
          "type": "string"
        },
        "call_id": {
          "type": "string",
          "description": "与对应 `custom_tool_call_output` 配对的调用 ID。"
        },
        "name": {
          "type": "string"
        },
        "namespace": {
          "type": "string",
          "description": "工具所属的命名空间，调用命名空间工具时返回。"
        },
        "input": {
          "type": "string",
          "description": "模型生成的自由文本输入。"
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      }
    },
    "ResponsesCustomToolCallOutputItem": {
      "type": "object",
      "title": "自定义工具调用结果",
      "description": "自定义工具调用的执行结果。",
      "required": [
        "type",
        "call_id",
        "output"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "custom_tool_call_output"
          ]
        },
        "call_id": {
          "type": "string",
          "description": "与对应 `custom_tool_call` 相同的调用 ID。"
        },
        "output": {
          "description": "工具返回的内容。",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ResponsesInputContentPart"
              }
            }
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      }
    },
    "ResponsesFunctionCallItem": {
      "type": "object",
      "title": "函数调用",
      "description": "回放一次函数调用。",
      "required": [
        "type",
        "call_id",
        "name",
        "arguments"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function_call"
          ]
        },
        "id": {
          "type": "string"
        },
        "call_id": {
          "type": "string",
          "description": "与对应 `function_call_output` 配对的调用 ID。"
        },
        "name": {
          "type": "string"
        },
        "namespace": {
          "type": "string",
          "description": "工具所属的命名空间，调用命名空间工具时返回。"
        },
        "arguments": {
          "type": "string",
          "description": "函数参数的 JSON 字符串。"
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      }
    },
    "ResponsesFunctionCallOutputItem": {
      "type": "object",
      "title": "函数调用结果",
      "description": "函数调用的执行结果。",
      "required": [
        "type",
        "call_id",
        "output"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function_call_output"
          ]
        },
        "call_id": {
          "type": "string",
          "description": "与对应 `function_call` 相同的调用 ID。"
        },
        "output": {
          "description": "工具返回的内容。",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ResponsesInputContentPart"
              }
            }
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      }
    },
    "ResponsesFunctionTool": {
      "type": "object",
      "title": "函数工具",
      "description": "用 JSON Schema 描述参数的函数工具。",
      "required": [
        "type",
        "name"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function"
          ]
        },
        "name": {
          "type": "string",
          "description": "函数名称。必须符合正则表达式：^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$",
          "pattern": "^[a-zA-Z_][a-zA-Z0-9-_]{0,127}$"
        },
        "description": {
          "type": "string"
        },
        "parameters": {
          "type": "object",
          "description": "描述函数参数的 JSON Schema。"
        },
        "strict": {
          "type": "boolean"
        }
      }
    },
    "ResponsesInputContentPart": {
      "description": "content 数组的元素，按 `type` 区分。",
      "oneOf": [
        {
          "type": "object",
          "title": "输入文本",
          "required": [
            "type",
            "text"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "input_text"
              ]
            },
            "text": {
              "type": "string"
            }
          }
        },
        {
          "type": "object",
          "title": "输入图片",
          "required": [
            "type",
            "image_url"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "input_image"
              ]
            },
            "image_url": {
              "type": "string",
              "description": "图片的 data URL，例如 `data:image/png;base64,<base64>`。不支持公网 http(s) URL。"
            },
            "detail": {
              "type": "string",
              "enum": [
                "auto",
                "low",
                "high",
                "original"
              ]
            }
          }
        },
        {
          "type": "object",
          "title": "输出文本",
          "description": "回放 assistant 历史文本时使用。",
          "required": [
            "type",
            "text"
          ],
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "output_text"
              ]
            },
            "text": {
              "type": "string"
            }
          }
        }
      ]
    },
    "ResponsesInputItem": {
      "description": "input 数组的元素，按 `type` 区分。省略 `type` 时按 `message` 处理。",
      "oneOf": [
        {
          "$ref": "#/$defs/ResponsesMessageItem"
        },
        {
          "$ref": "#/$defs/ResponsesReasoningItem"
        },
        {
          "$ref": "#/$defs/ResponsesFunctionCallItem"
        },
        {
          "$ref": "#/$defs/ResponsesFunctionCallOutputItem"
        },
        {
          "$ref": "#/$defs/ResponsesCustomToolCallItem"
        },
        {
          "$ref": "#/$defs/ResponsesCustomToolCallOutputItem"
        },
        {
          "$ref": "#/$defs/ResponsesWebSearchCallItem"
        },
        {
          "$ref": "#/$defs/ResponsesAdditionalToolsItem"
        }
      ]
    },
    "ResponsesMessageItem": {
      "type": "object",
      "title": "消息",
      "description": "一条对话消息。`type` 可省略。",
      "required": [
        "role",
        "content"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "message"
          ]
        },
        "role": {
          "type": "string",
          "enum": [
            "user",
            "assistant",
            "developer"
          ],
          "description": "消息角色。`developer` 按系统指令处理。"
        },
        "content": {
          "description": "消息内容，字符串或 content part 数组。",
          "oneOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {
                "$ref": "#/$defs/ResponsesInputContentPart"
              }
            }
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      }
    },
    "ResponsesNamespaceTool": {
      "type": "object",
      "title": "命名空间工具",
      "description": "把一组函数工具或自定义工具收纳到同一个命名空间下。",
      "required": [
        "type",
        "name",
        "description",
        "tools"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "namespace"
          ]
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "tools": {
          "type": "array",
          "items": {
            "oneOf": [
              {
                "$ref": "#/$defs/ResponsesFunctionTool"
              },
              {
                "$ref": "#/$defs/ResponsesCustomTool"
              }
            ]
          }
        }
      }
    },
    "ResponsesReasoningItem": {
      "type": "object",
      "title": "推理",
      "description": "回放上一轮的推理内容。`content` 优先于 `summary`。",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "reasoning"
          ]
        },
        "id": {
          "type": "string"
        },
        "summary": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "type",
              "text"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "summary_text"
                ]
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "content": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "type",
              "text"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "reasoning_text"
                ]
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        }
      }
    },
    "ResponsesTool": {
      "description": "工具定义，按 `type` 区分。支持 `function`、`custom`（仅 `apply_patch`）、`namespace` 与 `web_search`，其他工具类型不支持。",
      "oneOf": [
        {
          "$ref": "#/$defs/ResponsesFunctionTool"
        },
        {
          "$ref": "#/$defs/ResponsesCustomTool"
        },
        {
          "$ref": "#/$defs/ResponsesNamespaceTool"
        },
        {
          "$ref": "#/$defs/ResponsesWebSearchTool"
        }
      ]
    },
    "ResponsesToolChoice": {
      "type": "string",
      "enum": [
        "auto"
      ],
      "description": "控制工具调用行为。取 `auto` 时由模型自行决定是否调用工具。"
    },
    "ResponsesWebSearchCallItem": {
      "type": "object",
      "title": "联网搜索调用",
      "description": "回放上一轮的联网搜索调用。仅用于保留历史，转换时会被忽略；搜索结果已包含在其后的 assistant 消息中。",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "web_search_call"
          ]
        },
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "completed"
          ]
        },
        "action": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "search"
              ]
            },
            "query": {
              "type": "string"
            }
          }
        }
      }
    },
    "ResponsesWebSearchTool": {
      "type": "object",
      "title": "联网搜索工具",
      "description": "由服务端执行的联网搜索工具。加入后服务端会先根据输入判断是否需要搜索；需要时执行搜索并把结果注入模型上下文，同时在 output 中返回一个 `web_search_call` item。每个请求最多包含一个 `web_search` 工具。`search_context_size`、`blocked_domains`、`filters.blocked_domains` 不支持，传入会返回 `invalid_request_error`；`user_location`、`external_web_access`、`indexed_web_access` 会被忽略。",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "web_search"
          ]
        },
        "filters": {
          "type": "object",
          "description": "搜索范围过滤。",
          "properties": {
            "allowed_domains": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "maxItems": 100,
              "description": "仅在这些域名内搜索，最多 100 个。"
            }
          }
        },
        "search_content_types": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "text",
              "image"
            ]
          },
          "default": [
            "text"
          ],
          "description": "搜索结果类型，默认仅 `text`。包含 `image` 时会额外执行图片搜索。"
        },
        "image_settings": {
          "type": "object",
          "description": "图片搜索设置，仅在 `search_content_types` 包含 `image` 时生效。",
          "properties": {
            "max_results": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 3,
              "description": "最多返回的图片数量。"
            },
            "caption": {
              "type": "boolean",
              "default": false,
              "description": "是否为图片生成说明文字。"
            }
          }
        }
      }
    }
  }
}