快制作

主题

HTTP API 文档 ​

适用范围与认证 ​

本文介绍当前管理端、显示端及 cxserver 内置的内网服务 REST API。基础地址以该服务页面显示的地址为准，例如 http://192.168.1.10:9393。不要把接口路径追加到文档地址或 MCP 地址上；云端服务的登录、上传接口可能不同。

受保护接口支持 Authorization: ApiKey <内网 API Key>，或 Authorization: Bearer <内网登录 token>；同时兼容 X-Authorization 请求头。密钥或 token 必须属于当前内网服务，账号还需有目标实体的访问权限。

最小只读验证示例（POSIX Shell；替换地址，并在本机设置自己的密钥）：

sh
export LAN_ORIGIN="http://192.168.1.10:9393"
# 在本机私有环境中设置 MHT_API_KEY。
curl --fail-with-body "$LAN_ORIGIN/api/user" \
  -H "Authorization: ApiKey $MHT_API_KEY"

成功时返回当前用户 JSON。HTTP 401 表示凭据缺失或无效，403 表示没有相应权限；其他错误正文可能包含 errCode 和 errMsg。需要同时核对 HTTP 状态和具体接口返回值，不能只凭连接成功判断账号可用。

Agent 接入优先阅读 MCP 教程，其中也介绍了本地文件直传流程。

目录 ​

认证相关接口 ​

用户登录 ​

当前内网登录使用 passwordHash（客户端由密码计算的 MD5 登录摘要），不是明文 password 字段。脚本集成优先使用专用 API Key。

  • 方法: POST
  • 路径: /api/nauth/login
  • 参数:
    json
    {
  "username": "admin",
  "passwordHash": "密码的 MD5 登录摘要"
}
  • 成功响应:
    json
    {
  "token": "JWT令牌"
}
  • 失败响应: 401 Unauthorized

修改密码 ​

  • 方法: POST
  • 路径: /api/user/setPwd
  • 参数:
    json
    {
  "oldPwd": "原密码",
  "newPwd": "新密码"
}
  • 成功响应: 200 OK
  • 失败响应: 401 Unauthorized

获取用户信息 ​

  • 方法: GET
  • 路径: /api/user
  • 响应:
    json
    {
  "id": "用户ID",
  "email": "user@localhost",
  "authority": "TENANT_ADMIN",
  "tenantId": "租户ID",
  "customerId": "客户ID"
}

设备管理 ​

创建设备 ​

  • 方法: POST
  • 路径: /api/device
  • 参数: 设备JSON对象
  • 响应: 创建后的设备对象

删除设备 ​

  • 方法: DELETE
  • 路径: /api/device/{设备ID}
  • 响应: 200 OK

根据凭证获取设备 ​

  • 方法: GET
  • 路径: /api/device/cre/{设备凭证}
  • 响应: 设备对象

批量获取设备 ​

  • 方法: GET
  • 路径: /api/device/ids
  • 参数: ids=id1,id2,id3
  • 响应: 设备列表

设备RPC调用 ​

  • 方法: POST
  • 路径: /api/device/rpc/{设备ID}
  • 参数: RPC命令对象
  • 响应: RPC响应对象

获取设备属性 ​

  • 方法: GET
  • 路径: /api/device/attributes
  • 参数:
    • deviceId: 设备ID
    • scope: 属性作用域 (默认: CLIENT_SCOPE)
    • keys: 属性键列表 (逗号分隔)
  • 响应: 属性键值对

媒体资源管理 ​

批量获取媒体资源 ​

  • 方法: GET
  • 路径: /api/mhoss/ids
  • 参数: ids=id1,id2,id3
  • 响应: MHOss列表（包含局域网访问URL）

获取未使用的媒体资源 ​

  • 方法: GET
  • 路径: /api/mhoss/notUsed
  • 参数:
    • startTime: 起始时间戳
    • endTime: 结束时间戳
    • page: 页码
    • pageSize: 每页数量
    • textSearch: 搜索文本
  • 响应: 分页的MHOss列表（包含局域网访问URL）

删除媒体资源 ​

  • 方法: DELETE
  • 路径: /api/mhoss/ids
  • 参数: ids=id1,id2,id3
  • 响应: 删除结果

创建/更新媒体资源 ​

  • 方法: POST
  • 路径: /api/mhoss
  • 参数: MHOss对象
  • 响应: 创建/更新后的MHOss对象

节目管理 ​

获取节目详情 ​

  • 方法: GET
  • 路径: /api/nauth/mhcast/{节目ID}
  • 响应: MHCast对象（媒体资源包含局域网URL）

删除节目 ​

  • 方法: DELETE
  • 路径: /api/mhcast/{节目ID}
  • 响应: 200 OK

创建/更新节目 ​

  • 方法: POST
  • 路径: /api/mhcast
  • 参数: MHCast对象
  • 响应: 创建/更新后的MHCast对象

通知节目变化 ​

  • 方法: GET
  • 路径: /api/mhcast/notify/{节目ID}
  • 响应: 通知结果

获取节目关系列表 ​

  • 方法: GET
  • 路径: /api/mhcast/castRelations
  • 参数: deviceId=设备ID
  • 响应: 节目关系列表

实体查询 ​

查询实体 ​

  • 方法: POST
  • 路径: /api/entitiesQuery/find
  • 参数: EntityDataQuery对象
  • 响应: 分页的实体数据结果

关系管理 ​

创建关系 ​

  • 方法: POST
  • 路径: /api/relation
  • 参数: EntityRelation对象
  • 响应: 创建的关系对象

批量创建关系 ​

  • 方法: POST
  • 路径: /api/relation/list
  • 参数: 关系对象列表
  • 响应: 200 OK

删除关系 ​

  • 方法: DELETE
  • 路径: /api/relation
  • 参数: EntityRelation对象
  • 响应: 200 OK

批量删除关系 ​

  • 方法: DELETE
  • 路径: /api/relation/ids
  • 参数:
    json
    {
  "direction": "FROM|TO",
  "relationType": "关系类型",
  "relationTypeGroup": "关系组",
  "entityIdList": ["实体ID1", "实体ID2"]
}
  • 响应: 删除数量

查询关系列表 ​

  • 方法: GET
  • 路径: /api/relations
  • 参数:
    • 方式1: fromId=来源ID&fromType=来源类型
    • 方式2: toId=目标ID&toType=目标类型
  • 响应: 关系列表

文件上传 ​

当前内网服务使用上传会话流程，不再使用旧的 /upload 表单接口：

方法路径作用
POST/api/objectUpload/init选择存储并初始化直传或分片会话
POST/api/objectUpload/part获取分片上传地址
POST/api/objectUpload/complete完成上传会话
POST/api/objectUpload/abort终止未完成的会话

按初始化返回的地址和全部请求头传输文件字节，不要自行拼接对象存储地址，也不要在直传地址上附加 API Key。LOCAL 存储可能返回内网服务上的 /upload/object/... 地址，其他存储可能返回对象存储地址。

上传完成不等于素材已入库，还需根据完成结果通过 /api/mhoss 创建 MHOss 素材记录。Agent 场景可直接按 MCP 直传流程完成初始化、上传及入库；会话字段和分片大小应以运行中的服务返回值为准。

其他接口 ​

获取当前时间戳 ​

  • 方法: GET
  • 路径: /api/nauth/realts
  • 响应: 当前时间戳字符串

设备Hello检测 ​

  • 方法: GET
  • 路径: /api/nauth/hello
  • 参数:
    • deviceCre: 设备凭证 (可选)
    • port: 端口号 (可选)
  • 响应:
    json
    {
  "update": "是否更新了局域网地址",
  "deviceCre": "服务器设备凭证(当请求未提供时)"
}

生成动态设备码(DDC) ​

  • 方法: POST
  • 路径: /api/nauth/getDdc
  • 响应:
    json
    {
  "ddc": "动态设备码",
  "expireInMin": 10,
  "checkInSec": 5
}

检查DDC状态 ​

  • 方法: GET
  • 路径: /api/nauth/checkDdc
  • 参数: ddc=动态设备码
  • 响应:
    json
    {
  "verifiedTs": "验证时间戳(0表示未验证)"
}

输入DDC验证码 ​

  • 方法: POST
  • 路径: /api/device/inputDdc
  • 参数:
    • Query: ddc=动态设备码
    • Body: 验证码字符串 或 JSON {"code": "验证码"}
  • 响应: 验证结果