请求约定

查询字符串

列表接口仅允许 keyword、page、pageSize 和 status。查询键不能重复或为空，空格编码为 %20，解析一次后按 RFC 3986 重新编码并排序。

请求体

• GET 请求不得携带 Body、Content-Type 或 Content-Encoding。
• 实时播放 POST 使用零字节 Body，不需要 Content-Type。
• PTZ 写操作使用 application/json，拒绝未知字段和重复 JSON 字段。
• 禁止 Chunked Transfer-Encoding 和压缩请求体。

幂等

PTZ 写操作必须携带 Idempotency-Key，并将它放入 Canonical Request 第 10 行。

• 相同 Key 和相同命令返回同一个操作结果。
• 相同 Key 和不同命令返回 409 CONFLICT。
• 超时后是否重试由调用方决定，不能自动更换业务命令。

传输协议

平台不会在应用层强制 HTTPS。HTTP 或 HTTPS 由部署环境决定；生产环境应依据网络边界和反向代理策略配置传输安全。