{
  "openapi": "3.1.0",
  "info": {
    "title": "LatenTX Browser Voice API",
    "version": "2026-11-19.1",
    "description": "使用平台 API Key 管理当前账号的模型、资源、通话与录音。三种语音接入方式均使用模型 ID；可复用业务配置通过自定义模型发布。"
  },
  "servers": [
    {
      "url": "https://api.latenth.com/voice/v1"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/webrtc/credentials": {
      "post": {
        "operationId": "post_webrtc_credentials",
        "summary": "签发单通话网页凭证",
        "description": "从客户后端调用；返回SDK短期凭据、session_id和预占额度。支持MCP需allow_mcp_tools=true；不支持客户执行的Function。",
        "tags": [
          "租户管理"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Credential"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CredentialRequest"
              },
              "example": {
                "model": "latentx-realtime-2.5-mini",
                "from": "web-client",
                "greeting": "您好，请问有什么可以帮您？",
                "allow_mcp_tools": false
              }
            }
          }
        }
      }
    },
    "/conversations": {
      "get": {
        "operationId": "get_conversations",
        "summary": "查询通话列表",
        "description": "合并网页、电话及Realtime会话。默认limit=50，最大500；from/to为RFC3339；origin可选realtime/web/external。下一页传最后一项的cursor，直到返回空数组；无total。",
        "tags": [
          "租户管理"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "origin",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Conversation"
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/conversations/{call_id}": {
      "get": {
        "operationId": "get_conversations_call_id",
        "summary": "读取通话详情、转写与录音",
        "description": "",
        "tags": [
          "租户管理"
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/Conversation"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/conversations/{call_id}/events": {
      "get": {
        "operationId": "get_conversations_call_id_events",
        "summary": "分页查询会话事件",
        "description": "统一查询电话、网页和Realtime事件。新会话默认记录，旧会话仅返回已有内容。完整Realtime历史的data与实时服务端事件具有相同ID、类型和内容，音频Base64分片除外；发送记录不代表客户端收到或已播放。电话和网页保留原生语义。limit默认100、最大200；原样传递不透明next_cursor，空items但有游标时继续。complete=完整采集，collecting=采集中，partial=部分丢失，legacy=旧记录，unavailable=未采集，expired=已过期。各来源内部顺序稳定，跨页不承诺跨来源全局时钟顺序。活跃会话完成后从首页刷新。transcription 模式的历史转写用量位于 items[].data.usage；与实时事件按 event_id 对应，不能重复累计。序号间隙不代表丢失。",
        "tags": [
          "租户管理"
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ConversationEvent"
                          }
                        },
                        "next_cursor": {
                          "type": "string"
                        },
                        "mapping_version": {
                          "type": "integer"
                        },
                        "capture_state": {
                          "enum": [
                            "complete",
                            "collecting",
                            "partial",
                            "legacy",
                            "unavailable",
                            "expired",
                            "unsupported_mapping"
                          ]
                        }
                      },
                      "required": []
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/conversations/{call_id}/recordings": {
      "get": {
        "operationId": "get_conversations_call_id_recordings",
        "summary": "查询录音轨道",
        "description": "按账号开通情况返回录音分段。电话和网页优先从详情 recording 获取整通录音，也可有分段。Realtime 的详情没有整通文件时，仍可有分段。streams[].state、tracks[].state 和整通录音状态分别判断；partial 不代表已有文件都不可用。链接过期重新查询。音频按buffer或item关联，不承诺逐音频事件或逐字重放。",
        "tags": [
          "租户管理"
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "streams": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/CaptureStream"
                          }
                        }
                      },
                      "required": []
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/playground/sessions": {
      "get": {
        "operationId": "get_playground_sessions",
        "summary": "查询网页计费会话",
        "description": "最新50条；当前无分页参数。",
        "tags": [
          "租户管理"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BillingSession"
                      }
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/playground/sessions/{session_id}": {
      "get": {
        "operationId": "get_playground_sessions_session_id",
        "summary": "查询单通网页计费状态",
        "description": "",
        "tags": [
          "租户管理"
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "$ref": "#/components/schemas/BillingSession"
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "delete": {
        "operationId": "delete_playground_sessions_session_id",
        "summary": "请求停止网页通话",
        "description": "异步停止请求；需继续查询最终状态。",
        "tags": [
          "租户管理"
        ],
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "status": {
                          "const": "stopping"
                        }
                      },
                      "required": []
                    }
                  },
                  "required": [
                    "success",
                    "data"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "非2xx失败；可能为JSON、纯文本或空响应。先判断HTTP状态。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "message": {
                      "type": "string"
                    }
                  },
                  "required": []
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "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
      },
      "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"
        ]
      },
      "CustomConfig": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "必填，1–200字符。",
            "minLength": 1,
            "maxLength": 200
          },
          "instructions": {
            "type": "string",
            "description": "最多64KiB。"
          },
          "base_model": {
            "type": "string",
            "description": "从 catalog.voice_models 选择公开语音型号；无需传组件字段。"
          },
          "asr_language": {
            "type": "string",
            "description": "从 catalog.voice_models 对应型号的 input_languages 选择；空值使用模型默认。"
          },
          "tts_language": {
            "type": "string",
            "description": "从 catalog.voice_models 对应型号的 output_languages 选择；空值使用模型默认。"
          },
          "voice": {
            "type": "string"
          },
          "temperature": {
            "type": "number"
          },
          "max_tokens": {
            "type": "integer"
          },
          "silence_duration_ms": {
            "type": "integer",
            "description": "0 为默认；显式值200–2000ms。"
          },
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Skill"
            },
            "description": "固定版本引用 {id,version,preload}，Skill 须先通过 PUT /voice/v1/skills/{id}/versions/{version} 保存；不接受内联 markdown、resources、required_tools。"
          },
          "knowledge_refs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/KnowledgeRef"
            }
          },
          "mcp_refs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FunctionTool"
            }
          }
        },
        "required": [
          "name",
          "base_model"
        ]
      },
      "CustomConfigRead": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "必填，1–200字符。",
            "minLength": 1,
            "maxLength": 200
          },
          "instructions": {
            "type": "string",
            "description": "最多64KiB。"
          },
          "base_model": {
            "type": "string",
            "description": "从 catalog.voice_models 选择公开语音型号；无需传组件字段。"
          },
          "asr_language": {
            "type": "string",
            "description": "从 catalog.voice_models 对应型号的 input_languages 选择；空值使用模型默认。"
          },
          "tts_language": {
            "type": "string",
            "description": "从 catalog.voice_models 对应型号的 output_languages 选择；空值使用模型默认。"
          },
          "voice": {
            "type": "string"
          },
          "temperature": {
            "type": "number"
          },
          "max_tokens": {
            "type": "integer"
          },
          "silence_duration_ms": {
            "type": "integer",
            "description": "0 为默认；显式值200–2000ms。"
          },
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Skill"
            },
            "description": "固定版本引用 {id,version,preload}，Skill 须先通过 PUT /voice/v1/skills/{id}/versions/{version} 保存；不接受内联 markdown、resources、required_tools。"
          },
          "knowledge_refs": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/KnowledgeRef"
            },
            "description": "未挂载时部分保存版本返回null；写入建议使用[]。"
          },
          "mcp_refs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FunctionTool"
            }
          }
        },
        "required": [
          "name",
          "base_model"
        ]
      },
      "VoicePrice": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string"
          },
          "text_input": {
            "type": "number"
          },
          "text_output": {
            "type": "number"
          },
          "audio_input": {
            "type": "number"
          },
          "audio_output": {
            "type": "number"
          }
        },
        "required": [],
        "description": "每百万计费token的公开基础价格。"
      },
      "CustomVersion": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "enabled": {
            "type": "boolean"
          },
          "published_at": {
            "type": "string",
            "description": "",
            "format": "date-time"
          },
          "price": {
            "$ref": "#/components/schemas/VoicePrice"
          },
          "config": {
            "$ref": "#/components/schemas/CustomConfigRead"
          }
        },
        "required": []
      },
      "CustomModel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "config": {
            "$ref": "#/components/schemas/CustomConfigRead"
          },
          "versions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CustomVersion"
            }
          }
        },
        "required": [
          "id",
          "revision",
          "config",
          "versions"
        ]
      },
      "DraftWrite": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer",
            "minimum": 0,
            "description": "新建为0，更新使用最新读取的revision；完整替换config。"
          },
          "config": {
            "$ref": "#/components/schemas/CustomConfig"
          }
        },
        "required": [
          "revision",
          "config"
        ]
      },
      "Revision": {
        "type": "object",
        "properties": {
          "revision": {
            "type": "integer"
          }
        },
        "required": [
          "revision"
        ]
      },
      "BundleWrite": {
        "type": "object",
        "properties": {
          "markdown": {
            "type": "string",
            "description": "Markdown正文，包含name/description元信息；知识可用结构化QA或原文。"
          },
          "resources": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "required_tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "markdown"
        ]
      },
      "Bundle": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "sha256": {
            "type": "string"
          },
          "markdown": {
            "type": "string",
            "description": "Markdown正文，包含name/description元信息；知识可用结构化QA或原文。"
          },
          "resources": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "required_tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "version",
          "markdown",
          "sha256"
        ]
      },
      "MCPWrite": {
        "type": "object",
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "公网HTTPS:443 URL。"
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "writeOnly": true
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "url",
          "tools"
        ]
      },
      "MCPResource": {
        "type": "object",
        "properties": {
          "mcp_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [],
        "description": "不回显headers，当前也不回显enabled；更新时需自行保留所需写入配置。"
      },
      "EndpointConfig": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "instructions": {
            "type": "string",
            "description": "省略继承模型提示词，空字符串清空。"
          },
          "greeting": {
            "type": "string",
            "description": "开场白，最多2000字符。",
            "maxLength": 2000
          },
          "voice": {
            "type": "string"
          },
          "asr_language": {
            "type": "string"
          },
          "tts_language": {
            "type": "string"
          },
          "silence_duration_ms": {
            "type": "integer"
          },
          "idle_timeout_ms": {
            "type": "integer",
            "description": "0继承，显式值3000–60000ms；与ASR断句不同。"
          },
          "allow_mcp_tools": {
            "type": "boolean",
            "default": false
          },
          "enabled": {
            "type": "boolean"
          }
        },
        "required": [
          "model"
        ]
      },
      "CredentialRequest": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string"
          },
          "instructions": {
            "type": "string",
            "description": "省略继承模型提示词，空字符串清空。"
          },
          "greeting": {
            "type": "string",
            "description": "开场白，最多2000字符。",
            "maxLength": 2000
          },
          "voice": {
            "type": "string"
          },
          "asr_language": {
            "type": "string"
          },
          "tts_language": {
            "type": "string"
          },
          "silence_duration_ms": {
            "type": "integer"
          },
          "idle_timeout_ms": {
            "type": "integer",
            "description": "0继承，显式值3000–60000ms；与ASR断句不同。"
          },
          "allow_mcp_tools": {
            "type": "boolean",
            "default": false
          },
          "enabled": {
            "type": "boolean"
          },
          "from": {
            "type": "string",
            "description": "客户端标签；平台为计费分配实际caller。"
          }
        },
        "required": [
          "model"
        ]
      },
      "Credential": {
        "type": "object",
        "properties": {
          "ws": {
            "type": "string"
          },
          "uri": {
            "type": "string"
          },
          "target": {
            "type": "string"
          },
          "auth_user": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "description": "短期凭据，不记录到日志。"
          },
          "expires_at": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          },
          "caller": {
            "type": "string"
          },
          "reserved_quota": {
            "type": "integer"
          }
        },
        "required": []
      },
      "Phone": {
        "type": "object",
        "properties": {
          "phone_id": {
            "type": "string",
            "description": "号码的稳定标识；配置与解绑使用此值。"
          },
          "line_id": {
            "type": "string",
            "description": "所属线路标识，同一线路可以有多个号码。"
          },
          "number": {
            "type": "string"
          },
          "bound": {
            "type": "boolean"
          },
          "model": {
            "type": "string"
          },
          "instructions": {
            "type": "string"
          },
          "greeting": {
            "type": "string"
          },
          "voice": {
            "type": "string"
          },
          "silence_duration_ms": {
            "type": "integer"
          },
          "idle_timeout_ms": {
            "type": "integer"
          },
          "allow_mcp_tools": {
            "type": "boolean"
          },
          "enabled": {
            "type": "boolean"
          },
          "outbound_enabled": {
            "type": "boolean",
            "description": "当前号码是否具备外呼能力；独立于enabled呼入接听设置。实际拨号仍需通过模型权限与余额校验。"
          },
          "updated_at": {
            "type": "string"
          }
        },
        "required": []
      },
      "OutboundRequest": {
        "type": "object",
        "properties": {
          "model": {
            "type": "string",
            "description": "公共预定义模型或已发布自定义模型 ID。",
            "maxLength": 128
          },
          "phone_id": {
            "type": "string",
            "description": "本账号已分配且具备外呼能力的号码 ID。"
          },
          "to": {
            "type": "string",
            "description": "被叫电话号码，3–15 位数字，可有前导 +。",
            "pattern": "^\\+?[0-9]{3,15}$"
          },
          "request_id": {
            "type": "string",
            "description": "本账号内唯一；相同参数重试返回原通话，不重新拨打；冲突返回409。",
            "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,63}$"
          },
          "greeting": {
            "type": "string",
            "description": "开场白，UTF-8 最多2000字节。"
          },
          "context": {
            "type": "string",
            "description": "本通话的业务上下文，UTF-8 最多8000字节。"
          },
          "allow_mcp_tools": {
            "type": "boolean",
            "default": false
          },
          "ring_timeout": {
            "type": "integer",
            "minimum": 5,
            "maximum": 120,
            "default": 40
          }
        },
        "required": [
          "model",
          "phone_id",
          "to",
          "request_id"
        ],
        "additionalProperties": false
      },
      "OutboundCall": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "phone_id": {
            "type": "string"
          },
          "from": {
            "type": "string"
          },
          "to": {
            "type": "string"
          },
          "status": {
            "enum": [
              "preparing",
              "dialing",
              "answered",
              "ended"
            ]
          },
          "hangup_reason": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "answer_at": {
            "type": "string"
          },
          "end_at": {
            "type": "string"
          }
        },
        "required": [],
        "description": "单通外呼记录；不提供任务编排或自动重拨。时间为RFC3339。结束原因是线路返回的粗分类，不保证精确判断被叫状态。"
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string"
          },
          "direction": {
            "type": "string"
          },
          "caller": {
            "type": "string"
          },
          "callee": {
            "type": "string"
          },
          "origin": {
            "type": "string"
          },
          "start_at": {
            "type": "string"
          },
          "answer_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "end_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "hangup_by": {
            "type": "string"
          },
          "hangup_reason": {
            "type": "string"
          },
          "transcript": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/TranscriptEntry"
            }
          },
          "recording": {
            "type": "object",
            "properties": {
              "state": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "expires_at": {
                "type": "string"
              }
            },
            "required": []
          },
          "session_id": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "cursor": {
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConversationItem"
            }
          }
        },
        "required": [],
        "description": "可选时间/转写/录音字段视通话状态返回；录音是临时签名URL。"
      },
      "CaptureTrack": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "direction": {
            "enum": [
              "input",
              "output"
            ]
          },
          "item_id": {
            "type": "string",
            "description": "输出 item ID"
          },
          "buffer_id": {
            "type": "string",
            "description": "输入录音分段的缓冲标识；不等同于转写 item_id，也不保证逐事件关联。"
          },
          "sample_rate": {
            "type": "integer"
          },
          "bytes": {
            "type": "integer"
          },
          "duration_ms": {
            "type": "integer"
          },
          "start_at": {
            "type": "string"
          },
          "state": {
            "enum": [
              "recording",
              "pending",
              "uploaded"
            ]
          },
          "url": {
            "type": "string",
            "description": "授权后签名URL；仅 uploaded 且签名成功时返回。"
          },
          "expires_at": {
            "type": "string"
          }
        },
        "required": [],
        "description": "独立单声道 PCM16 WAV 分段，输出仅表示生成，不代表客户端已播放。"
      },
      "CaptureStream": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "origin": {
            "type": "string"
          },
          "state": {
            "enum": [
              "collecting",
              "complete",
              "partial",
              "finalizing",
              "expired"
            ]
          },
          "reason": {
            "type": "string"
          },
          "started_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "ended": {
            "type": "boolean"
          },
          "audio_enabled": {
            "type": "boolean"
          },
          "retain_until": {
            "type": "string"
          },
          "tracks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CaptureTrack"
            }
          }
        },
        "required": [],
        "description": "来源内顺序；不同来源不保证全序。complete 指本版本采集范围正常封存，录音上传状态另看 tracks。"
      },
      "BillingSession": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "call_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "created_at": {
            "type": "integer"
          },
          "updated_at": {
            "type": "integer"
          },
          "expires_at": {
            "type": "integer"
          },
          "deadline": {
            "type": "integer"
          },
          "text_input": {
            "type": "integer"
          },
          "text_output": {
            "type": "integer"
          },
          "audio_input": {
            "type": "integer"
          },
          "audio_output": {
            "type": "integer"
          },
          "quota": {
            "type": "integer"
          },
          "reserved_quota": {
            "type": "integer"
          }
        },
        "required": [],
        "description": "时间为Unix秒；quota为平台额度单位，不直接等于人民币。停止请求返回不代表结算完成。"
      },
      "Audit": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string"
          },
          "key_id": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "latency_ms": {
            "type": "integer"
          },
          "at": {
            "type": "string"
          }
        },
        "required": []
      },
      "UsageRecord": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "response_id": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "time": {
            "type": "string"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "required": []
      },
      "Voice": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "gender": {
            "type": "string"
          }
        },
        "required": []
      },
      "VoiceModel": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "input_languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "output_languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "voices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "gender": {
                  "type": "string"
                },
                "languages": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "required": [],
              "description": "languages 省略或为空表示兼容该型号全部输出语言。"
            }
          },
          "default_voice": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/VoicePrice"
          }
        },
        "required": [],
        "description": "基础语音型号与可选语言、音色。空语言值使用模型默认；发布版本保留原调用 ID。"
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "agent_models": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "voice_models": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VoiceModel"
            }
          },
          "voices": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Voice"
            }
          },
          "default_voice": {
            "type": "string"
          },
          "prices": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "currency": {
                  "type": "string"
                },
                "text_input": {
                  "type": "number"
                },
                "text_output": {
                  "type": "number"
                },
                "audio_input": {
                  "type": "number"
                },
                "audio_output": {
                  "type": "number"
                }
              },
              "required": []
            }
          }
        },
        "required": [],
        "description": "价格为每百万计费token的基础价格，最终计费还受账户分组等配置影响。"
      },
      "TranscriptEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "timestamp": {},
          "time": {}
        },
        "required": [],
        "description": "按会话来源返回转写正文与时间字段；content/text、timestamp/time 可能仅返回其中一种，不包含系统提示词。工具调用详情见 items。"
      },
      "ConversationItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "response_id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "role": {
            "type": "string"
          },
          "content": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "call_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "arguments": {
            "type": "string"
          },
          "output": {
            "type": "string"
          },
          "approval_request_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "approve": {
            "type": "boolean"
          },
          "audio_end_ms": {
            "type": "integer"
          },
          "duration_ms": {
            "type": "integer"
          }
        },
        "required": [],
        "description": "正文与工具记录。incomplete为部分输出，truncated表示客户端截断；生成文本不代表已经播放。"
      },
      "ConversationEvent": {
        "type": "object",
        "properties": {
          "event_id": {
            "type": "string",
            "description": "Realtime沿用实时event_id；电话和网页使用稳定的来源与序号标识；旧记录可能省略。"
          },
          "stream_id": {
            "type": "string"
          },
          "sequence": {
            "type": "integer"
          },
          "time": {
            "type": "string",
            "description": "",
            "format": "date-time"
          },
          "direction": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "response_id": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "description": "Realtime为经过披露映射的完整服务端事件；电话和网页为原生事件允许公开的字段。"
          }
        },
        "required": []
      }
    }
  }
}
