开放接口
ANet4D 对外提供两组 HTTP 接口与一个实时协议:
接口 |
前缀 |
监听 |
面向 |
|---|---|---|---|
沙盒 REST v1 |
|
sandbox-api(本机 8002;公开实例经 nginx 按路径分流) |
访客、脚本与外部智能体:创建并操作自己的沙盒 |
本机运行时接口 |
|
api(本机 8000) |
本机共享展示的操作员与运维:世界、机队、命令、剧本、运行与系统 |
实时协议 |
WebSocket |
两个 api 均提供 |
状态流、命令调用、速度设定点与事件 |
界面与接口同权:浏览器中的每个操作都对应同一套接口,经过相同的准入与安全检查。沙盒接口的 OpenAPI 3.1 文档由服务端在
/api/sandbox/v1/openapi.json 提供,公开实例在 /sandbox/api 页面渲染并附可复制的示例。Python 程序建议使用 Python SDK,它处理排队、工作量证明、续期、节能恢复与二进制帧解码。
鉴权
方式 |
适用 |
说明 |
|---|---|---|
公开 |
|
无需凭据,可缓存 |
会话令牌 |
|
创建会话时签发, |
排队票 |
|
进入排队时签发, |
请求体令牌 |
|
页面关闭时由浏览器以信标发送,令牌放在请求体中 |
管理令牌 |
本机运行时接口的受保护端点 |
每次运行生成于 |
公开模式下,创建会话可能要求工作量证明:GET /challenge 取题,求解后随创建请求提交;需要时服务端以原因码 509 返回题目。
错误格式
错误以 application/problem+json 返回,code 为项目原因码(packages/contracts/rt/reasons.json);沙盒专用原因码在 500 至 599 段,与 HTTP 5xx 无关。以下为本机共享展示对未带令牌请求 GET /api/worlds 的真实响应:
{"type":"urn:awr:reason:301","title":"AUTH_REQUIRED","status":401,"code":301,"name":"AUTH_REQUIRED","reason":"AUTH_REQUIRED","message":"缺少 token","detail":null,"remedy":"先签发 token","request_id":"01a135ae-3540-7d01-88af-813820ac3b51"}
字段 |
含义 |
|---|---|
|
原因码与名称,例如 110 |
|
面向人的说明 |
|
结构化细节,例如 `{"field": "nest_id |
|
建议的处理方式 |
|
限流时的精确等待(毫秒);同时提供 |
|
请求编号,报告问题时请附上 |
幂等与限流
创建类请求(会话、无人机、识别物、机巢、任务)接受 Idempotency-Key 头,同一键的重试返回同一结果;SDK 自动生成。公开模式下各类请求按会话使用令牌桶限流:
类别 |
速率 |
突发 |
|---|---|---|
一般 REST |
10 次/s |
30 |
命令调用 |
20 次/s |
40 |
时钟 |
2 次/s |
— |
实体增删改 |
5 次/s |
— |
任务 |
1 次/s |
— |
速度设定点 |
50 Hz |
— |
超限返回 429 与原因码 111,SDK 按 retry_after_ms 自动重试。任务的输入规模另有配额,见 沙盒。
实时协议
沙盒的实时连接为 GET /api/sandbox/v1/sessions/{sid}/rt 上的 WebSocket,子协议为 awr.rt.v1 与 bearer.<token>。连接后客户端订阅主题(例如会话状态 sandbox/session、机群状态与单机感知),服务端按每个客户端的兴趣集与配额发送:机群以 32 字节的 Lite32 记录、焦点无人机以
64 字节的 Full64 记录批量下发,结构化消息以 msgpack 编码。命令以 call 发起,依次返回受理、执行中与结果;速度控制在 call 之后经客户端数据通道以至多 50 Hz 发送设定点。字节布局见设计文档
docs/17 接口与实时协议规范。
会话结束时连接以关闭码 4410 关闭;节能驻留时以关闭码 4430 断开,客户端恢复会话后重新订阅;切换底图时以 1012 断开,客户端按新世界重连。
沙盒 REST v1 端点
下表由 packages/contracts/rest/sandbox.openapi.snapshot.json 在构建文档时生成。路径相对于前缀 /api/sandbox/v1;"优先级"中 P1 为可选能力,未部署的端点返回 404。
会话、排队与生命周期
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-00 |
|
|
接口版本、契约版本、访问模式、会话与队列概况 |
公开 |
P0 |
SB-01 |
|
|
七个世界的可用性与准入 |
公开 |
P0 |
SB-02 |
|
|
场景模板 |
公开 |
P0 |
SB-03 |
|
|
领取工作量证明题目 |
公开 |
P0 |
SB-04 |
|
|
创建、排队或幂等返回 |
公开 |
P0 |
SB-05 |
|
|
排队状态长轮询 |
排队票 |
P0 |
SB-06 |
|
|
领取空位 |
排队票 |
P0 |
SB-07 |
|
|
离开队列 |
排队票 |
P0 |
SB-08 |
|
|
会话对象(可长轮询到指定状态) |
会话令牌 |
P0 |
SB-09 |
|
|
结束会话 |
会话令牌 |
P0 |
SB-10 |
|
|
续期并换发 token |
会话令牌 |
P0 |
SB-11 |
|
|
导出配置快照(结束后 10 min 内可用) |
会话令牌 |
P0 |
SB-12 |
|
|
导入配置快照(同一世界) |
会话令牌 |
P0 |
SB-13 |
|
|
载入场景模板 |
会话令牌 |
P0 |
SB-14 |
|
|
切换底图 |
会话令牌 |
P0 |
SB-15 |
|
|
播放、暂停、倍速(经治理器)、单步 |
会话令牌 |
P0 |
SB-16 |
|
|
事件补拉 |
会话令牌 |
P0 |
SB-17 |
|
|
关闭页面时结束会话(token 在请求体) |
请求体令牌 |
P1 |
SB-18 |
|
|
批处理评估(本机与局域网;公开站 404) |
会话令牌 |
P0 |
SB-19 |
|
|
批处理进度与结果 |
会话令牌 |
P0 |
SB-69 |
|
|
节能驻留(checkpoint 落盘、释放槽位) |
会话令牌 |
P0 |
SB-70 |
|
|
从驻留恢复(满员时恢复票) |
会话令牌 |
P0 |
SB-71 |
|
|
公开容量(载入期排队可见) |
公开 |
P0 |
SB-72 |
|
|
驻留信标(pagehide,token 在请求体) |
请求体令牌 |
P0 |
SB-76 |
|
|
指挥器配对码(P1) |
会话令牌 |
P1 |
SB-77 |
|
|
以配对码加入同一沙盒(P1) |
公开 |
P1 |
接口文档与实时连接
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-20 |
|
|
沙盒 OpenAPI 3.1 |
公开 |
P0 |
SB-64 |
|
|
沙盒实时连接(WebSocket Upgrade,子协议 awr.rt.v1 + bearer.<token>) |
会话令牌 |
P0 |
机型与传感器目录
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-21 |
|
|
机型目录(预置) |
公开 |
P0 |
SB-22 |
|
|
机型完整参数、参数表与派生量 |
公开 |
P0 |
SB-23 |
|
|
传感器目录 |
公开 |
P0 |
SB-24 |
|
|
本会话克隆机型 |
会话令牌 |
P0 |
SB-25 |
|
|
克隆并编辑机型 |
会话令牌 |
P0 |
SB-26 |
|
|
修改克隆机型 |
会话令牌 |
P0 |
SB-27 |
|
|
删除克隆机型 |
会话令牌 |
P0 |
机队与命令
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-28 |
|
|
机队实例列表 |
会话令牌 |
P0 |
SB-29 |
|
|
添加无人机 |
会话令牌 |
P0 |
SB-30 |
|
|
实例与状态快照 |
会话令牌 |
P0 |
SB-31 |
|
|
修改标签、机巢、挂载、限速档 |
会话令牌 |
P0 |
SB-32 |
|
|
移除 |
会话令牌 |
P0 |
SB-33 |
|
|
全部状态 |
会话令牌 |
P0 |
SB-34 |
|
|
挂载、规格、工作状态、云台与变焦 |
会话令牌 |
P0 |
SB-35 |
|
|
发起命令(同 WS call) |
会话令牌 |
P0 |
SB-36 |
|
|
申请租约 |
会话令牌 |
P0 |
SB-37 |
|
|
释放租约 |
会话令牌 |
P0 |
识别物
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-40 |
|
|
识别物列表 |
会话令牌 |
P0 |
SB-41 |
|
|
新增识别物 |
会话令牌 |
P0 |
SB-42 |
|
|
识别物完整配置 |
会话令牌 |
P0 |
SB-43 |
|
|
修改识别物(JSON Merge Patch) |
会话令牌 |
P0 |
SB-44 |
|
|
删除识别物 |
会话令牌 |
P0 |
SB-45 |
|
|
感知态、有效敏感体、计数、声源相位 |
会话令牌 |
P0 |
SB-46 |
|
|
physical 模型的建议半径 |
会话令牌 |
P0 |
SB-65 |
|
|
识别物类别模板 |
公开 |
P1 |
感知
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-38 |
|
|
当前感知结果 |
会话令牌 |
P0 |
SB-39 |
|
|
检测历史补拉 |
会话令牌 |
P0 |
SB-66 |
|
|
识别物航迹(不外露真值) |
会话令牌 |
P1 |
SB-67 |
|
|
服务端可行窗口查询 |
会话令牌 |
P1 |
SB-73 |
|
|
逐对感知量化读数 |
会话令牌 |
P0 |
SB-74 |
|
|
辐射场剖面 |
会话令牌 |
P0 |
SB-75 |
|
|
识别物感知体表 |
会话令牌 |
P0 |
SB-78 |
|
|
场的显式采样点(对拍) |
会话令牌 |
P1 |
任务、机巢与接力
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-47 |
|
|
机巢列表 |
会话令牌 |
P0 |
SB-48 |
|
|
新增机巢(可同时放入无人机) |
会话令牌 |
P0 |
SB-49 |
|
|
机巢配置与状态 |
会话令牌 |
P0 |
SB-50 |
|
|
修改机巢 |
会话令牌 |
P0 |
SB-51 |
|
|
删除机巢 |
会话令牌 |
P0 |
SB-52 |
|
|
任务列表 |
会话令牌 |
P0 |
SB-53 |
|
|
创建任务或预览分配(dry-run) |
会话令牌 |
P0 |
SB-54 |
|
|
任务、状态与计划几何 |
会话令牌 |
P0 |
SB-55.cancel |
|
|
任务控制 cancel |
会话令牌 |
P0 |
SB-55.pause |
|
|
任务控制 pause |
会话令牌 |
P0 |
SB-55.resume |
|
|
任务控制 resume |
会话令牌 |
P0 |
SB-55.start |
|
|
任务控制 start |
会话令牌 |
P0 |
SB-56 |
|
|
7x24 可持续性评估 |
会话令牌 |
P0 |
SB-57 |
|
|
Allocator 快照 |
会话令牌 |
P0 |
SB-58 |
|
|
提交外部分配计划 |
会话令牌 |
P0 |
SB-59 |
|
|
接力统计 |
会话令牌 |
P0 |
SB-68 |
|
|
dry-run 排队超时后的异步取回 |
会话令牌 |
P0 |
环境与日历
编号 |
方法 |
路径 |
说明 |
鉴权 |
优先级 |
|---|---|---|---|---|---|
SB-60 |
|
|
EnvKeyframe(含日历、太阳、照度档) |
会话令牌 |
P0 |
SB-61 |
|
|
天气预设(同 call env/preset) |
会话令牌 |
P0 |
SB-62 |
|
|
仿真日历(call env/calendar) |
会话令牌 |
P0 |
SB-63 |
|
|
环境场点查询 |
会话令牌 |
P0 |
本机运行时接口端点
下表由 packages/contracts/rest/openapi.snapshot.json 生成。这些端点服务于本机共享展示(回环访问),除健康、就绪与版本信息外均需要令牌;公开实例以只读方式提供其中与观看相关的部分。
系统与健康
方法 |
路径 |
说明 |
|---|---|---|
|
|
事件补拉 |
|
|
健康状态与构建信息(公开) |
|
|
存活探针 |
|
|
就绪探针(仿真、状态环与世界) |
|
|
审计日志尾部(admin) |
|
|
生效配置(机密已掩码) |
|
|
版本、协议与访问模式 |
|
|
服务端性能窗口聚合 |
|
|
提交客户端性能报告 |
|
|
性能报告列表 |
|
|
性能报告原文 |
|
|
进程状态 |
|
|
重启进程或复位熔断(admin) |
鉴权与身份
方法 |
路径 |
说明 |
|---|---|---|
|
|
签发一次性确认令牌(绑定操作与对象,10 s 有效) |
|
|
内部身份验证(部署方口令,限流与锁定) |
|
|
撤销内部身份令牌 |
|
|
签发访问令牌 |
|
|
当前主体与角色 |
世界
方法 |
路径 |
说明 |
|---|---|---|
|
|
几何查询(高度、净空、视线、射线求交、路径校验) |
|
|
世界列表 |
|
|
世界详情 |
机队
方法 |
路径 |
说明 |
|---|---|---|
|
|
机群能力与上限 |
|
|
机型参数档列表 |
|
|
机型参数档详情 |
|
|
无人机列表 |
|
|
添加无人机 |
|
|
无人机详情 |
|
|
移除无人机 |
|
|
注入故障 |
|
|
清除故障 |
命令
方法 |
路径 |
说明 |
|---|---|---|
|
|
命令列表 |
|
|
发起命令 |
|
|
命令状态 |
|
|
取消命令 |
剧本与任务
方法 |
路径 |
说明 |
|---|---|---|
|
|
任务列表 |
|
|
创建任务 |
|
|
任务预览 |
|
|
取回任务预览 |
|
|
任务详情 |
|
|
任务控制(启动、暂停、继续、取消) |
|
|
当前剧本的加载状态与结果 |
|
|
剧本列表 |
|
|
剧本详情 |
环境
方法 |
路径 |
说明 |
|---|---|---|
|
|
切换天气预设 |
|
|
天气预设列表 |
|
|
环境场点查询 |
|
|
设置环境参数 |
|
|
环境状态 |
|
|
风场流线 |
运行、录制与书签
方法 |
路径 |
说明 |
|---|---|---|
|
|
运行列表 |
|
|
运行详情 |
|
|
删除运行 |
|
|
书签列表 |
|
|
添加书签 |
|
|
修改书签 |
|
|
删除书签 |
|
|
运行事件 |
|
|
保留运行(不参与配额回收) |
|
|
录制分段文件 |
作业
方法 |
路径 |
说明 |
|---|---|---|
|
|
作业列表 |
|
|
作业详情 |
|
|
取消作业 |
|
|
作业日志 |
|
|
重试作业 |
|
|
构建世界(作业) |
重建
方法 |
路径 |
说明 |
|---|---|---|
|
|
重建引擎列表 |
|
|
提交重建作业 |
智能体
方法 |
路径 |
说明 |
|---|---|---|
|
|
智能体任务列表 |
|
|
提交智能体任务 |
|
|
智能体任务详情 |
|
|
指派任务 |
|
|
任务的报价与竞标看板 |
|
|
取消智能体任务 |
|
|
任务证据与回执 |
|
|
智能体列表 |
|
|
智能体能力清单 |
实时协议
方法 |
路径 |
说明 |
|---|---|---|
|
|
实时连接检视 |
|
|
实时主题目录 |
会话
方法 |
路径 |
说明 |
|---|---|---|
|
|
当前会话 |
观看排队
方法 |
路径 |
说明 |
|---|---|---|
|
|
领取观看排队票 |
|
|
观看排队状态长轮询 |
|
|
离开观看排队 |