{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.latenth.com/docs/realtime.schema.json",
  "title": "LatenTX PaaS Realtime events",
  "description": "公开推荐接入契约；仅声明当前支持的 WS 子集。",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "session.update"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "session": {
          "$ref": "#/$defs/SessionUpdate"
        }
      },
      "required": [
        "type",
        "session"
      ],
      "description": "收到 session.created 后设置当前会话；需空闲、无缓冲音频及待完成工具。失败不提交配置。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.create"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item": {
          "oneOf": [
            {
              "$ref": "#/$defs/UserItem"
            },
            {
              "$ref": "#/$defs/FunctionOutput"
            },
            {
              "$ref": "#/$defs/Approval"
            }
          ]
        }
      },
      "required": [
        "type",
        "item"
      ],
      "description": "追加用户文本、Function 结果或 MCP 审批；不支持插入历史位置。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.retrieve"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "item_id"
      ],
      "description": "读取当前连接中的 item。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.truncate"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "content_index": {
          "const": 0
        },
        "audio_end_ms": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "type",
        "item_id",
        "content_index",
        "audio_end_ms"
      ],
      "description": "截断 assistant 音频历史；content_index 必须为 0；audio_end_ms 不得超过已生成时长。当前实现清空该 item 的历史转写，不承诺逐字对齐。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.create"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response": {
          "$ref": "#/$defs/ResponseOptions"
        }
      },
      "required": [
        "type"
      ],
      "description": "创建一次响应；有待完成工具时拒绝。自动 VAD 已触发时不要重复发送。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.cancel"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        }
      },
      "required": [
        "type"
      ],
      "description": "取消活动响应；可指定 response_id 防止取消错误响应。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.append"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "audio": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "audio"
      ],
      "description": "追加 Base64 PCM16LE 单声道 24kHz；单包最多 10 秒、缓冲最多 120 秒。示例为两个静音采样，实际提交至少 100ms。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.commit"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        }
      },
      "required": [
        "type"
      ],
      "description": "手动提交至少 100ms 音频；等待转写，再 response.create。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.clear"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        }
      },
      "required": [
        "type"
      ],
      "description": "丢弃尚未提交的音频缓冲。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "session.created"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "session": {
          "$ref": "#/$defs/Session"
        }
      },
      "required": [
        "type",
        "event_id",
        "session"
      ],
      "description": "返回当前生效会话配置；工具凭据不回显。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "session.updated"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "session": {
          "$ref": "#/$defs/Session"
        }
      },
      "required": [
        "type",
        "event_id",
        "session"
      ],
      "description": "返回当前生效会话配置；工具凭据不回显。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.added"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item": {
          "$ref": "#/$defs/Item"
        },
        "previous_item_id": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "type",
        "event_id",
        "item"
      ],
      "description": "会话 item 新增、完成或读取结果；MCP item 的字段由 type 决定。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item": {
          "$ref": "#/$defs/Item"
        },
        "previous_item_id": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "type",
        "event_id",
        "item"
      ],
      "description": "会话 item 新增、完成或读取结果；MCP item 的字段由 type 决定。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.retrieved"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item": {
          "$ref": "#/$defs/Item"
        },
        "previous_item_id": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "type",
        "event_id",
        "item"
      ],
      "description": "会话 item 新增、完成或读取结果；MCP item 的字段由 type 决定。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.truncated"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "content_index": {
          "type": "integer"
        },
        "audio_end_ms": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "content_index",
        "audio_end_ms"
      ],
      "description": "确认历史截断。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.speech_started"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "audio_start_ms": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "audio_start_ms"
      ],
      "description": "VAD 检测到语音边界；毫秒位置属于当前音频时间线。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.speech_stopped"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "audio_end_ms": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "audio_end_ms"
      ],
      "description": "VAD 检测到语音边界；毫秒位置属于当前音频时间线。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.committed"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "previous_item_id": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "previous_item_id"
      ],
      "description": "音频转写已提交为用户 item。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "input_audio_buffer.cleared"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        }
      },
      "required": [
        "type",
        "event_id"
      ],
      "description": "缓冲已清空。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "conversation.item.input_audio_transcription.completed"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "content_index": {
          "type": "integer"
        },
        "transcript": {
          "type": "string"
        },
        "usage": {
          "$ref": "#/$defs/TranscriptionUsage"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "content_index",
        "transcript"
      ],
      "description": "转写完成。仅 transcription 模式单列 usage；即使没有模型响应，也可收到本事件。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.created"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response": {
          "$ref": "#/$defs/Response"
        }
      },
      "required": [
        "type",
        "event_id",
        "response"
      ],
      "description": "响应开始或结束；只有 done 且 status=completed 才表示模型响应成功，MCP 执行仍可能未结束。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response": {
          "$ref": "#/$defs/Response"
        }
      },
      "required": [
        "type",
        "event_id",
        "response"
      ],
      "description": "响应开始或结束；只有 done 且 status=completed 才表示模型响应成功，MCP 执行仍可能未结束。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_item.added"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "item": {
          "$ref": "#/$defs/Item"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "output_index",
        "item"
      ],
      "description": "响应输出项开始或结束。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_item.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "item": {
          "$ref": "#/$defs/Item"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "output_index",
        "item"
      ],
      "description": "响应输出项开始或结束。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.content_part.added"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "part": {
          "$ref": "#/$defs/Content"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "part"
      ],
      "description": "消息内容部分开始或结束。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.content_part.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "part": {
          "$ref": "#/$defs/Content"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "part"
      ],
      "description": "消息内容部分开始或结束。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_text.delta"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "delta": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "delta"
      ],
      "description": "增量按到达顺序累积；音频 delta 为 Base64 PCM，done 文本为本项完整内容。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_text.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "text": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "text"
      ],
      "description": "增量按到达顺序累积；音频 delta 为 Base64 PCM，done 文本为本项完整内容。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_audio.delta"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "delta": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "delta"
      ],
      "description": "增量按到达顺序累积；音频 delta 为 Base64 PCM，done 文本为本项完整内容。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_audio_transcript.delta"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "delta": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "delta"
      ],
      "description": "增量按到达顺序累积；音频 delta 为 Base64 PCM，done 文本为本项完整内容。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_audio_transcript.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        },
        "transcript": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index",
        "transcript"
      ],
      "description": "增量按到达顺序累积；音频 delta 为 Base64 PCM，done 文本为本项完整内容。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.output_audio.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "content_index": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "content_index"
      ],
      "description": "本项音频生成结束，不代表客户端已播放完。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.function_call_arguments.delta"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "call_id": {
          "type": "string"
        },
        "delta": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "call_id",
        "delta"
      ],
      "description": "客户执行的 Function 参数；等待 response.done 后执行并回传全部结果。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.function_call_arguments.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "call_id": {
          "type": "string"
        },
        "arguments": {
          "type": "string"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "call_id",
        "arguments",
        "name"
      ],
      "description": "客户执行的 Function 参数；等待 response.done 后执行并回传全部结果。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.mcp_call_arguments.delta"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "delta": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "delta"
      ],
      "description": "MCP 参数；工具由平台执行，客户只处理需要的审批。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.mcp_call_arguments.done"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "response_id": {
          "type": "string"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        },
        "arguments": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "response_id",
        "item_id",
        "output_index",
        "arguments"
      ],
      "description": "MCP 参数；工具由平台执行，客户只处理需要的审批。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "mcp_list_tools.in_progress"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id"
      ],
      "description": "工具发现状态；失败会导致配置更新失败。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.mcp_call.in_progress"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "output_index"
      ],
      "description": "MCP 执行状态；最终 output/error 在对应 mcp_call item 中。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "mcp_list_tools.completed"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id"
      ],
      "description": "工具发现状态；失败会导致配置更新失败。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.mcp_call.completed"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "output_index"
      ],
      "description": "MCP 执行状态；最终 output/error 在对应 mcp_call item 中。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "mcp_list_tools.failed"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id"
      ],
      "description": "工具发现状态；失败会导致配置更新失败。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "response.mcp_call.failed"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "item_id": {
          "type": "string"
        },
        "output_index": {
          "type": "integer"
        }
      },
      "required": [
        "type",
        "event_id",
        "item_id",
        "output_index"
      ],
      "description": "MCP 执行状态；最终 output/error 在对应 mcp_call item 中。"
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "const": "error"
        },
        "event_id": {
          "type": "string",
          "description": "客户端可选，用于关联错误；服务端事件始终携带。"
        },
        "error": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "code": {
              "type": "string",
              "description": "Public codes include invalid_tool_arguments, invalid_knowledge_id, tool_timeout, tool_cancelled, tool_execution_failed, conversation_storage_unavailable, realtime_key_invalid, realtime_quota_rejected, invalid_realtime_event, invalid_realtime_input, invalid_response_done, missing_realtime_usage, usage_estimation_failed and voice_operation_failed. Branch on code, not message."
            },
            "message": {
              "type": "string"
            },
            "event_id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "code",
            "message"
          ]
        }
      },
      "required": [
        "type",
        "event_id",
        "error"
      ],
      "description": "协议错误；用 error.event_id 关联客户端事件。配置失败不会覆盖旧配置。"
    }
  ],
  "$defs": {
    "KnowledgeRef": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "version"
      ],
      "additionalProperties": false
    },
    "Skill": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "preload": {
          "type": "boolean",
          "default": false,
          "description": "true 全量预加载；false 仅描述，按需读取。"
        },
        "markdown": {
          "type": "string",
          "description": "内联正文，仅用于 Realtime session.latentx.skills。自定义模型 config.skills 只接受已保存版本引用 {id,version,preload}：先 PUT /voice/v1/skills/{id}/versions/{version}，再引用；带 markdown、resources 或 required_tools 时校验返回400。"
        },
        "resources": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "required_tools": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "id",
        "version"
      ],
      "additionalProperties": false
    },
    "FunctionTool": {
      "type": "object",
      "properties": {
        "type": {
          "const": "function"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "parameters": {
          "type": "object",
          "description": "工具参数的 JSON Schema；由客户执行前再次校验。"
        }
      },
      "required": [
        "type",
        "name",
        "parameters"
      ],
      "additionalProperties": false
    },
    "MCPTool": {
      "type": "object",
      "properties": {
        "type": {
          "const": "mcp"
        },
        "server_label": {
          "type": "string"
        },
        "server_url": {
          "type": "string",
          "description": "公网 HTTPS:443，无 query、凭据或重定向；同会话成功导入后可仅传 label 复用。"
        },
        "server_description": {
          "type": "string"
        },
        "authorization": {
          "type": "string",
          "description": "仅写入：Bearer token；响应不回显。"
        },
        "headers": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "仅写入；响应不回显。"
        },
        "allowed_tools": {
          "oneOf": [
            {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            {
              "type": "object",
              "properties": {
                "tool_names": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [
                "tool_names"
              ],
              "additionalProperties": false
            }
          ]
        },
        "require_approval": {
          "oneOf": [
            {
              "enum": [
                "always",
                "never"
              ]
            },
            {
              "type": "object",
              "properties": {
                "always": {
                  "type": "object",
                  "properties": {
                    "tool_names": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "tool_names"
                  ]
                },
                "never": {
                  "type": "object",
                  "properties": {
                    "tool_names": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": [
                    "tool_names"
                  ]
                }
              },
              "required": []
            }
          ],
          "default": "always"
        }
      },
      "required": [
        "type",
        "server_label"
      ],
      "additionalProperties": false
    },
    "Tool": {
      "oneOf": [
        {
          "$ref": "#/$defs/FunctionTool"
        },
        {
          "$ref": "#/$defs/MCPTool"
        }
      ]
    },
    "ToolChoice": {
      "oneOf": [
        {
          "enum": [
            "auto",
            "none",
            "required"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "function"
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "name"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "mcp"
            },
            "server_label": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "server_label",
            "name"
          ],
          "additionalProperties": false
        }
      ]
    },
    "Modalities": {
      "enum": [
        [
          "text"
        ],
        [
          "audio"
        ]
      ],
      "description": "只能选一种；audio 同时返回音频与转写文本。"
    },
    "Format": {
      "type": "object",
      "properties": {
        "type": {
          "const": "audio/pcm"
        },
        "rate": {
          "const": 24000
        }
      },
      "required": [
        "type",
        "rate"
      ],
      "additionalProperties": false
    },
    "TurnDetection": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "const": "server_vad"
            },
            "silence_duration_ms": {
              "type": "integer",
              "minimum": 200,
              "maximum": 2000,
              "default": 300
            },
            "create_response": {
              "type": "boolean",
              "default": true
            },
            "interrupt_response": {
              "type": "boolean",
              "default": true
            }
          },
          "required": [],
          "additionalProperties": false
        }
      ],
      "description": "null 为手动 commit + response.create；默认 server_vad。"
    },
    "Audio": {
      "type": "object",
      "properties": {
        "input": {
          "type": "object",
          "properties": {
            "format": {
              "$ref": "#/$defs/Format"
            },
            "turn_detection": {
              "$ref": "#/$defs/TurnDetection"
            },
            "transcription": {
              "type": "null",
              "description": "仅允许 null；识别使用所选模型的 ASR，不支持会话覆盖。"
            }
          },
          "required": [],
          "additionalProperties": false
        },
        "output": {
          "type": "object",
          "properties": {
            "format": {
              "$ref": "#/$defs/Format"
            },
            "voice": {
              "type": "string",
              "description": "从 /voice/v1/voices 取得；首次输出音频后锁定。"
            }
          },
          "required": [],
          "additionalProperties": false
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "Resources": {
      "type": "object",
      "properties": {
        "skills": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Skill"
          },
          "maxItems": 16
        },
        "knowledge_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/KnowledgeRef"
          },
          "maxItems": 16
        },
        "mcp_refs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [],
      "additionalProperties": false,
      "description": "LatenTX 扩展。省略保留原配置，[] 清空。仅当前会话生效；引用必须属于当前租户。"
    },
    "SessionUpdate": {
      "type": "object",
      "properties": {
        "type": {
          "const": "realtime"
        },
        "model": {
          "type": "string",
          "description": "如传入必须与连接的 model 一致，不能切换模型。"
        },
        "instructions": {
          "type": "string",
          "description": "替换当前会话的业务提示词；空字符串清空业务提示词；平台输出规则仍生效；UTF-8 最多 64 KiB。"
        },
        "output_modalities": {
          "$ref": "#/$defs/Modalities"
        },
        "tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Tool"
          },
          "maxItems": 32
        },
        "tool_choice": {
          "$ref": "#/$defs/ToolChoice"
        },
        "audio": {
          "$ref": "#/$defs/Audio"
        },
        "latentx": {
          "$ref": "#/$defs/Resources"
        }
      },
      "required": [],
      "additionalProperties": false
    },
    "ResponseOptions": {
      "type": "object",
      "properties": {
        "instructions": {
          "type": "string",
          "description": "只覆盖本次响应的业务提示词；平台输出规则仍生效；UTF-8 最多 64 KiB。"
        },
        "output_modalities": {
          "$ref": "#/$defs/Modalities"
        },
        "tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Tool"
          },
          "maxItems": 32
        },
        "tool_choice": {
          "$ref": "#/$defs/ToolChoice"
        }
      },
      "required": [],
      "additionalProperties": false,
      "description": "只覆盖本次响应；不会写回会话。max_output_tokens 等未列字段不支持。"
    },
    "Content": {
      "type": "object",
      "properties": {
        "type": {
          "enum": [
            "input_text",
            "input_audio",
            "output_text",
            "output_audio"
          ]
        },
        "text": {
          "type": "string"
        },
        "transcript": {
          "type": "string"
        }
      },
      "required": [
        "type"
      ]
    },
    "UserItem": {
      "type": "object",
      "properties": {
        "type": {
          "const": "message"
        },
        "id": {
          "type": "string"
        },
        "role": {
          "const": "user"
        },
        "content": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "const": "input_text"
              },
              "text": {
                "type": "string",
                "description": "非空；合计最多 64 KiB。"
              }
            },
            "required": [
              "type",
              "text"
            ]
          },
          "minItems": 1
        }
      },
      "required": [
        "type",
        "role",
        "content"
      ]
    },
    "FunctionOutput": {
      "type": "object",
      "properties": {
        "type": {
          "const": "function_call_output"
        },
        "id": {
          "type": "string"
        },
        "call_id": {
          "type": "string"
        },
        "output": {
          "type": "string",
          "description": "字符串；建议 JSON 字符串，最多 64 KiB。"
        }
      },
      "required": [
        "type",
        "call_id",
        "output"
      ]
    },
    "Approval": {
      "type": "object",
      "properties": {
        "type": {
          "const": "mcp_approval_response"
        },
        "id": {
          "type": "string"
        },
        "approval_request_id": {
          "type": "string"
        },
        "approve": {
          "type": "boolean"
        },
        "reason": {
          "type": "string"
        }
      },
      "required": [
        "type",
        "approval_request_id",
        "approve"
      ]
    },
    "Item": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "object": {
          "type": "string",
          "description": "通常为 realtime.item；部分 MCP 事件省略。"
        },
        "type": {
          "enum": [
            "message",
            "function_call",
            "function_call_output",
            "mcp_list_tools",
            "mcp_call",
            "mcp_approval_request",
            "mcp_approval_response"
          ]
        },
        "status": {
          "type": "string"
        },
        "role": {
          "type": "string"
        },
        "content": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Content"
          }
        },
        "call_id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "arguments": {
          "type": "string",
          "description": "累积后的 JSON 字符串。"
        },
        "output": {
          "type": "string"
        },
        "server_label": {
          "type": "string"
        },
        "tools": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "input_schema": {
                "type": "object"
              }
            },
            "required": []
          }
        },
        "error": {},
        "approval_request_id": {
          "type": "string"
        },
        "approve": {
          "type": "boolean"
        },
        "reason": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "type"
      ],
      "description": "按 type 使用对应字段；非所有字段都会同时返回。"
    },
    "Usage": {
      "type": "object",
      "properties": {
        "total_tokens": {
          "type": "integer"
        },
        "input_tokens": {
          "type": "integer"
        },
        "output_tokens": {
          "type": "integer"
        },
        "input_token_details": {
          "type": "object",
          "properties": {
            "text_tokens": {
              "type": "integer"
            },
            "audio_tokens": {
              "type": "integer"
            },
            "cached_tokens": {
              "type": "integer"
            },
            "cached_tokens_details": {
              "type": "object",
              "properties": {
                "text_tokens": {
                  "type": "integer"
                },
                "audio_tokens": {
                  "type": "integer"
                }
              },
              "required": []
            }
          },
          "required": []
        },
        "output_token_details": {
          "type": "object",
          "properties": {
            "text_tokens": {
              "type": "integer"
            },
            "audio_tokens": {
              "type": "integer"
            }
          },
          "required": []
        }
      },
      "required": [
        "total_tokens",
        "input_tokens",
        "output_tokens",
        "input_token_details",
        "output_token_details"
      ]
    },
    "Response": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "object": {
          "const": "realtime.response"
        },
        "status": {
          "enum": [
            "in_progress",
            "completed",
            "cancelled",
            "failed"
          ]
        },
        "status_details": {
          "description": "正常为 null；失败或取消时可能包含原因。"
        },
        "output": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Item"
          }
        },
        "conversation_id": {
          "type": "string"
        },
        "output_modalities": {
          "$ref": "#/$defs/Modalities"
        },
        "usage": {
          "$ref": "#/$defs/Usage"
        }
      },
      "required": [
        "id",
        "object",
        "status",
        "output",
        "usage"
      ]
    },
    "SessionResources": {
      "type": "object",
      "properties": {
        "skills": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Skill"
          },
          "maxItems": 16
        },
        "knowledge_refs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/KnowledgeRef"
          },
          "maxItems": 16
        },
        "mcp_refs": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "usage_mode": {
          "const": "transcription",
          "readOnly": true,
          "description": "开启独立转写计量时返回；默认 response 模式可省略此字段。"
        }
      },
      "required": [],
      "description": "服务端回显，不可通过 session.update 写入 usage_mode。"
    },
    "TranscriptionUsage": {
      "type": "object",
      "properties": {
        "type": {
          "const": "duration"
        },
        "seconds": {
          "type": "number",
          "minimum": 0
        }
      },
      "required": [
        "type",
        "seconds"
      ],
      "description": "transcription 模式下，此条转写的计量秒数，可以含小数。"
    },
    "Session": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "object": {
          "const": "realtime.session"
        },
        "type": {
          "const": "realtime"
        },
        "model": {
          "type": "string",
          "description": "如传入必须与连接的 model 一致，不能切换模型。"
        },
        "instructions": {
          "type": "string",
          "description": "替换当前会话的业务提示词；空字符串清空业务提示词；平台输出规则仍生效；UTF-8 最多 64 KiB。"
        },
        "output_modalities": {
          "$ref": "#/$defs/Modalities"
        },
        "tools": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Tool"
          },
          "maxItems": 32
        },
        "tool_choice": {
          "$ref": "#/$defs/ToolChoice"
        },
        "audio": {
          "$ref": "#/$defs/Audio"
        },
        "latentx": {
          "$ref": "#/$defs/SessionResources"
        }
      },
      "required": [
        "id",
        "object",
        "model",
        "instructions",
        "output_modalities",
        "tools",
        "audio"
      ]
    }
  },
  "x-version": "2026-11-19.1",
  "x-client-events": [
    "session.update",
    "conversation.item.create",
    "conversation.item.retrieve",
    "conversation.item.truncate",
    "response.create",
    "response.cancel",
    "input_audio_buffer.append",
    "input_audio_buffer.commit",
    "input_audio_buffer.clear"
  ],
  "x-server-events": [
    "session.created",
    "session.updated",
    "conversation.item.added",
    "conversation.item.done",
    "conversation.item.retrieved",
    "conversation.item.truncated",
    "input_audio_buffer.speech_started",
    "input_audio_buffer.speech_stopped",
    "input_audio_buffer.committed",
    "input_audio_buffer.cleared",
    "conversation.item.input_audio_transcription.completed",
    "response.created",
    "response.done",
    "response.output_item.added",
    "response.output_item.done",
    "response.content_part.added",
    "response.content_part.done",
    "response.output_text.delta",
    "response.output_text.done",
    "response.output_audio.delta",
    "response.output_audio_transcript.delta",
    "response.output_audio_transcript.done",
    "response.output_audio.done",
    "response.function_call_arguments.delta",
    "response.function_call_arguments.done",
    "response.mcp_call_arguments.delta",
    "response.mcp_call_arguments.done",
    "mcp_list_tools.in_progress",
    "response.mcp_call.in_progress",
    "mcp_list_tools.completed",
    "response.mcp_call.completed",
    "mcp_list_tools.failed",
    "response.mcp_call.failed",
    "error"
  ]
}
