{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/kimi-ai/json-schema/kimi-ai-responses-response-schema.json",
  "title": "ResponsesResponse",
  "description": "一次模型响应。",
  "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/ResponsesResponse",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "响应的唯一标识符。"
    },
    "object": {
      "type": "string",
      "enum": [
        "response"
      ]
    },
    "created_at": {
      "type": "integer",
      "description": "响应创建时的 Unix 时间戳。"
    },
    "completed_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "响应结束时的 Unix 时间戳。`status` 为 `completed` 或 `incomplete` 时给出，为 `in_progress` 或 `failed` 时是 `null`。"
    },
    "status": {
      "type": "string",
      "enum": [
        "in_progress",
        "completed",
        "incomplete",
        "failed"
      ],
      "description": "响应状态。流式的起手快照为 `in_progress`。"
    },
    "model": {
      "type": "string",
      "description": "产生本次响应的模型。"
    },
    "output": {
      "type": "array",
      "description": "输出 item 数组，顺序为 web_search_call（如有）、reasoning、message、工具调用。",
      "items": {
        "$ref": "#/$defs/ResponsesOutputItem"
      }
    },
    "usage": {
      "oneOf": [
        {
          "$ref": "#/$defs/ResponsesUsage"
        },
        {
          "type": "null"
        }
      ]
    },
    "incomplete_details": {
      "type": [
        "object",
        "null"
      ],
      "description": "`status` 为 `incomplete` 时给出原因。",
      "properties": {
        "reason": {
          "type": "string",
          "enum": [
            "max_output_tokens",
            "content_filter"
          ]
        }
      }
    },
    "error": {
      "type": [
        "object",
        "null"
      ],
      "description": "`status` 为 `failed` 时给出错误信息。",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "instructions": {
      "type": [
        "string",
        "null"
      ]
    },
    "reasoning": {
      "type": [
        "object",
        "null"
      ]
    },
    "text": {
      "type": [
        "object",
        "null"
      ]
    },
    "tools": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/ResponsesTool"
      }
    },
    "tool_choice": {
      "oneOf": [
        {
          "$ref": "#/$defs/ResponsesToolChoice"
        },
        {
          "type": "null"
        }
      ]
    },
    "max_output_tokens": {
      "type": [
        "integer",
        "null"
      ]
    },
    "temperature": {
      "type": [
        "number",
        "null"
      ]
    },
    "top_p": {
      "type": [
        "number",
        "null"
      ]
    },
    "metadata": {
      "type": [
        "object",
        "null"
      ]
    },
    "parallel_tool_calls": {
      "type": "boolean"
    },
    "service_tier": {
      "type": [
        "string",
        "null"
      ]
    },
    "store": {
      "type": "boolean",
      "description": "固定为 `false`。"
    },
    "background": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "固定为 `false`。"
    },
    "previous_response_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "固定为 `null`。"
    },
    "conversation": {
      "type": [
        "object",
        "null"
      ],
      "description": "固定为 `null`。"
    },
    "prompt_cache_options": {
      "type": "object",
      "description": "服务端实际应用的上下文缓存写入选项。当请求省略 prompt_cache_options 时，以此处返回的 mode 和 ttl 为准",
      "properties": {
        "mode": {
          "type": "string",
          "enum": [
            "implicit"
          ],
          "description": "实际应用的写入模式"
        },
        "ttl": {
          "type": "string",
          "enum": [
            "5m",
            "1h"
          ],
          "description": "实际应用的缓存有效期"
        }
      }
    }
  },
  "$defs": {
    "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 语法定义。"
            }
          }
        }
      }
    },
    "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"
        }
      }
    },
    "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"
              }
            ]
          }
        }
      }
    },
    "ResponsesOutputCustomToolCallItem": {
      "type": "object",
      "title": "自定义工具调用",
      "description": "模型发起的自定义工具调用。",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "custom_tool_call"
          ]
        },
        "id": {
          "type": "string"
        },
        "call_id": {
          "type": "string",
          "description": "回传结果时在 `custom_tool_call_output` 中使用该值。"
        },
        "name": {
          "type": "string"
        },
        "namespace": {
          "type": "string",
          "description": "调用命名空间工具时返回。"
        },
        "input": {
          "type": "string",
          "description": "模型生成的自由文本输入。"
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress",
            "completed"
          ]
        }
      }
    },
    "ResponsesOutputFunctionCallItem": {
      "type": "object",
      "title": "函数调用",
      "description": "模型发起的函数调用。",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "function_call"
          ]
        },
        "id": {
          "type": "string"
        },
        "call_id": {
          "type": "string",
          "description": "回传结果时在 `function_call_output` 中使用该值。"
        },
        "name": {
          "type": "string"
        },
        "namespace": {
          "type": "string",
          "description": "调用命名空间工具时返回。"
        },
        "arguments": {
          "type": "string",
          "description": "函数参数的 JSON 字符串。"
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress",
            "completed"
          ]
        }
      }
    },
    "ResponsesOutputItem": {
      "description": "output 数组的元素，按 `type` 区分。",
      "oneOf": [
        {
          "$ref": "#/$defs/ResponsesOutputReasoningItem"
        },
        {
          "$ref": "#/$defs/ResponsesOutputMessageItem"
        },
        {
          "$ref": "#/$defs/ResponsesOutputFunctionCallItem"
        },
        {
          "$ref": "#/$defs/ResponsesOutputCustomToolCallItem"
        },
        {
          "$ref": "#/$defs/ResponsesOutputWebSearchCallItem"
        }
      ]
    },
    "ResponsesOutputMessageItem": {
      "type": "object",
      "title": "消息",
      "description": "模型的文本回复。",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "message"
          ]
        },
        "id": {
          "type": "string"
        },
        "role": {
          "type": "string",
          "enum": [
            "assistant"
          ]
        },
        "content": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "output_text"
                ]
              },
              "text": {
                "type": "string"
              },
              "annotations": {
                "type": "array",
                "items": {}
              }
            }
          }
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress",
            "completed"
          ]
        }
      }
    },
    "ResponsesOutputReasoningItem": {
      "type": "object",
      "title": "推理",
      "description": "模型的推理内容。",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "reasoning"
          ]
        },
        "id": {
          "type": "string"
        },
        "summary": {
          "type": "array",
          "description": "推理内容。",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "summary_text"
                ]
              },
              "text": {
                "type": "string"
              }
            }
          }
        },
        "encrypted_content": {
          "type": [
            "string",
            "null"
          ],
          "description": "固定为 `null`。"
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress",
            "completed"
          ]
        }
      }
    },
    "ResponsesOutputWebSearchCallItem": {
      "type": "object",
      "title": "联网搜索调用",
      "description": "服务端执行的联网搜索调用。仅在请求包含 `web_search` 工具且服务端判断需要搜索时返回，位于 output 数组最前面。",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "web_search_call"
          ]
        },
        "id": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "in_progress",
            "completed"
          ]
        },
        "action": {
          "type": "object",
          "description": "本次搜索的动作。",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "search"
              ]
            },
            "query": {
              "type": "string",
              "description": "实际使用的搜索关键词。"
            },
            "sources": {
              "type": "array",
              "description": "搜索命中的网页来源。仅在 `include` 包含 `web_search_call.action.sources` 时返回。",
              "items": {
                "type": "object",
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "url"
                    ]
                  },
                  "url": {
                    "type": "string"
                  },
                  "title": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "results": {
          "type": "array",
          "description": "图片搜索结果。仅在 `include` 包含 `web_search_call.results` 且 `search_content_types` 包含 `image` 时返回。",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "image_result"
                ]
              },
              "image_url": {
                "type": "string"
              },
              "thumbnail_url": {
                "type": "string"
              },
              "source_website_url": {
                "type": "string"
              },
              "caption": {
                "type": "string",
                "description": "图片说明文字，仅在开启 `image_settings.caption` 时返回。"
              }
            }
          }
        }
      }
    },
    "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` 时由模型自行决定是否调用工具。"
    },
    "ResponsesUsage": {
      "type": "object",
      "description": "本次响应的 Token 用量。",
      "properties": {
        "input_tokens": {
          "type": "integer",
          "description": "输入 Token 数量，含命中缓存的部分。"
        },
        "input_tokens_details": {
          "type": "object",
          "properties": {
            "cached_tokens": {
              "type": "integer",
              "description": "命中上下文缓存的 Token 数量。"
            },
            "cache_write_tokens": {
              "type": "integer",
              "description": "写入上下文缓存的 Token 数量。"
            }
          }
        },
        "output_tokens": {
          "type": "integer",
          "description": "输出 Token 数量，含推理 Token。"
        },
        "output_tokens_details": {
          "type": "object",
          "properties": {
            "reasoning_tokens": {
              "type": "integer",
              "description": "推理消耗的 Token 数量。"
            }
          }
        },
        "total_tokens": {
          "type": "integer",
          "description": "总 Token 数量。"
        }
      }
    },
    "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": "是否为图片生成说明文字。"
            }
          }
        }
      }
    }
  }
}