开放接口

ANet4D 对外提供两组 HTTP 接口与一个实时协议:

接口

前缀

监听

面向

沙盒 REST v1

/api/sandbox/v1

sandbox-api(本机 8002;公开实例经 nginx 按路径分流)

访客、脚本与外部智能体:创建并操作自己的沙盒

本机运行时接口

/api

api(本机 8000)

本机共享展示的操作员与运维:世界、机队、命令、剧本、运行与系统

实时协议 awr.rt.v1

WebSocket

两个 api 均提供

状态流、命令调用、速度设定点与事件

界面与接口同权:浏览器中的每个操作都对应同一套接口,经过相同的准入与安全检查。沙盒接口的 OpenAPI 3.1 文档由服务端在 /api/sandbox/v1/openapi.json 提供,公开实例在 /sandbox/api 页面渲染并附可复制的示例。Python 程序建议使用 Python SDK,它处理排队、工作量证明、续期、节能恢复与二进制帧解码。

鉴权

方式

适用

说明

公开

meta、worlds、templates、capacity、机型与传感器目录、challenge 等

无需凭据,可缓存

会话令牌

/sessions/{sid}/...

创建会话时签发,Authorization: Bearer v1.<payload>.<sig>,只对该 sid 有效;续期时换发

排队票

/queue/{ticket_id}...

进入排队时签发,Authorization: Bearer q1.<...>,只用于排队端点

请求体令牌

end-beacon、park-beacon

页面关闭时由浏览器以信标发送,令牌放在请求体中

管理令牌

本机运行时接口的受保护端点

每次运行生成于 runs/<run>/admin.token(0600),经 POST /api/auth/token 换取访问令牌

公开模式下,创建会话可能要求工作量证明: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"}

字段

含义

code、name

原因码与名称,例如 110 PARAM_OUT_OF_RANGE、506 SANDBOX_GONE、525 NEST_INCOMPATIBLE、581 NO_FEASIBLE_STATION、585 PLAN_INPUT_TOO_LARGE

message

面向人的说明

detail

结构化细节,例如 `{"field": "nest_id

remedy

建议的处理方式

retry_after_ms

限流时的精确等待(毫秒);同时提供 Retry-After 头(整秒)

request_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。

快照:AWR sandbox REST v1,契约 1.3.0,82 个操作。来源:packages/contracts/rest/sandbox.openapi.snapshot.json。路径前缀:/api/sandbox/v1。

会话、排队与生命周期

编号

方法

路径

说明

鉴权

优先级

SB-00

GET

/meta

接口版本、契约版本、访问模式、会话与队列概况

公开

P0

SB-01

GET

/worlds

七个世界的可用性与准入

公开

P0

SB-02

GET

/templates

场景模板

公开

P0

SB-03

GET

/challenge

领取工作量证明题目

公开

P0

SB-04

POST

/sessions

创建、排队或幂等返回

公开

P0

SB-05

GET

/queue/{ticket_id}

排队状态长轮询

排队票

P0

SB-06

POST

/queue/{ticket_id}/claim

领取空位

排队票

P0

SB-07

DELETE

/queue/{ticket_id}

离开队列

排队票

P0

SB-08

GET

/sessions/{sid}

会话对象(可长轮询到指定状态)

会话令牌

P0

SB-09

DELETE

/sessions/{sid}

结束会话

会话令牌

P0

SB-10

POST

/sessions/{sid}/keepalive

续期并换发 token

会话令牌

P0

SB-11

GET

/sessions/{sid}/snapshot

导出配置快照(结束后 10 min 内可用)

会话令牌

P0

SB-12

POST

/sessions/{sid}/restore

导入配置快照(同一世界)

会话令牌

P0

SB-13

POST

/sessions/{sid}/template

载入场景模板

会话令牌

P0

SB-14

POST

/sessions/{sid}/world

切换底图

会话令牌

P0

SB-15

POST

/sessions/{sid}/clock

播放、暂停、倍速(经治理器)、单步

会话令牌

P0

SB-16

GET

/sessions/{sid}/events

事件补拉

会话令牌

P0

SB-17

POST

/sessions/{sid}/end-beacon

关闭页面时结束会话(token 在请求体)

请求体令牌

P1

SB-18

POST

/sessions/{sid}/batch

批处理评估(本机与局域网;公开站 404)

会话令牌

P0

SB-19

GET

/sessions/{sid}/batch/{batch_id}

批处理进度与结果

会话令牌

P0

SB-69

POST

/sessions/{sid}/park

节能驻留(checkpoint 落盘、释放槽位)

会话令牌

P0

SB-70

POST

/sessions/{sid}/resume

从驻留恢复(满员时恢复票)

会话令牌

P0

SB-71

GET

/capacity

公开容量(载入期排队可见)

公开

P0

SB-72

POST

/sessions/{sid}/park-beacon

驻留信标(pagehide,token 在请求体)

请求体令牌

P0

SB-76

POST

/sessions/{sid}/pair-code

指挥器配对码(P1)

会话令牌

P1

SB-77

POST

/sessions/{sid}/pair

以配对码加入同一沙盒(P1)

公开

P1

接口文档与实时连接

编号

方法

路径

说明

鉴权

优先级

SB-20

GET

/openapi.json

沙盒 OpenAPI 3.1

公开

P0

SB-64

GET

/sessions/{sid}/rt

沙盒实时连接(WebSocket Upgrade,子协议 awr.rt.v1 + bearer.<token>)

会话令牌

P0

机型与传感器目录

编号

方法

路径

说明

鉴权

优先级

SB-21

GET

/catalog/models

机型目录(预置)

公开

P0

SB-22

GET

/catalog/models/{model_id}

机型完整参数、参数表与派生量

公开

P0

SB-23

GET

/catalog/sensors

传感器目录

公开

P0

SB-24

GET

/sessions/{sid}/models

本会话克隆机型

会话令牌

P0

SB-25

POST

/sessions/{sid}/models

克隆并编辑机型

会话令牌

P0

SB-26

PATCH

/sessions/{sid}/models/{model_id}

修改克隆机型

会话令牌

P0

SB-27

DELETE

/sessions/{sid}/models/{model_id}

删除克隆机型

会话令牌

P0

机队与命令

编号

方法

路径

说明

鉴权

优先级

SB-28

GET

/sessions/{sid}/vehicles

机队实例列表

会话令牌

P0

SB-29

POST

/sessions/{sid}/vehicles

添加无人机

会话令牌

P0

SB-30

GET

/sessions/{sid}/vehicles/{vid}

实例与状态快照

会话令牌

P0

SB-31

PATCH

/sessions/{sid}/vehicles/{vid}

修改标签、机巢、挂载、限速档

会话令牌

P0

SB-32

DELETE

/sessions/{sid}/vehicles/{vid}

移除

会话令牌

P0

SB-33

GET

/sessions/{sid}/vehicles/{vid}/state

全部状态

会话令牌

P0

SB-34

GET

/sessions/{sid}/vehicles/{vid}/sensors

挂载、规格、工作状态、云台与变焦

会话令牌

P0

SB-35

POST

/sessions/{sid}/vehicles/{vid}/commands

发起命令(同 WS call)

会话令牌

P0

SB-36

POST

/sessions/{sid}/vehicles/{vid}:acquire

申请租约

会话令牌

P0

SB-37

POST

/sessions/{sid}/vehicles/{vid}:release

释放租约

会话令牌

P0

识别物

编号

方法

路径

说明

鉴权

优先级

SB-40

GET

/sessions/{sid}/targets

识别物列表

会话令牌

P0

SB-41

POST

/sessions/{sid}/targets

新增识别物

会话令牌

P0

SB-42

GET

/sessions/{sid}/targets/{id}

识别物完整配置

会话令牌

P0

SB-43

PATCH

/sessions/{sid}/targets/{id}

修改识别物(JSON Merge Patch)

会话令牌

P0

SB-44

DELETE

/sessions/{sid}/targets/{id}

删除识别物

会话令牌

P0

SB-45

GET

/sessions/{sid}/targets/{id}/state

感知态、有效敏感体、计数、声源相位

会话令牌

P0

SB-46

GET

/sessions/{sid}/targets/{id}/suggested_radius

physical 模型的建议半径

会话令牌

P0

SB-65

GET

/target_classes

识别物类别模板

公开

P1

感知

编号

方法

路径

说明

鉴权

优先级

SB-38

GET

/sessions/{sid}/vehicles/{vid}/perception

当前感知结果

会话令牌

P0

SB-39

GET

/sessions/{sid}/detections

检测历史补拉

会话令牌

P0

SB-66

GET

/sessions/{sid}/tracks

识别物航迹(不外露真值)

会话令牌

P1

SB-67

POST

/sessions/{sid}/perception/feasibility

服务端可行窗口查询

会话令牌

P1

SB-73

GET

/sessions/{sid}/perception/quant

逐对感知量化读数

会话令牌

P0

SB-74

GET

/sessions/{sid}/perception/field/{kind}

辐射场剖面

会话令牌

P0

SB-75

GET

/sessions/{sid}/perception/volumes

识别物感知体表

会话令牌

P0

SB-78

POST

/sessions/{sid}/perception/field/{kind}/samples

场的显式采样点(对拍)

会话令牌

P1

任务、机巢与接力

编号

方法

路径

说明

鉴权

优先级

SB-47

GET

/sessions/{sid}/nests

机巢列表

会话令牌

P0

SB-48

POST

/sessions/{sid}/nests

新增机巢(可同时放入无人机)

会话令牌

P0

SB-49

GET

/sessions/{sid}/nests/{id}

机巢配置与状态

会话令牌

P0

SB-50

PATCH

/sessions/{sid}/nests/{id}

修改机巢

会话令牌

P0

SB-51

DELETE

/sessions/{sid}/nests/{id}

删除机巢

会话令牌

P0

SB-52

GET

/sessions/{sid}/tasks

任务列表

会话令牌

P0

SB-53

POST

/sessions/{sid}/tasks

创建任务或预览分配(dry-run)

会话令牌

P0

SB-54

GET

/sessions/{sid}/tasks/{tid}

任务、状态与计划几何

会话令牌

P0

SB-55.cancel

POST

/sessions/{sid}/tasks/{tid}:cancel

任务控制 cancel

会话令牌

P0

SB-55.pause

POST

/sessions/{sid}/tasks/{tid}:pause

任务控制 pause

会话令牌

P0

SB-55.resume

POST

/sessions/{sid}/tasks/{tid}:resume

任务控制 resume

会话令牌

P0

SB-55.start

POST

/sessions/{sid}/tasks/{tid}:start

任务控制 start

会话令牌

P0

SB-56

GET

/sessions/{sid}/tasks/{tid}/sustainability

7x24 可持续性评估

会话令牌

P0

SB-57

GET

/sessions/{sid}/tasking/snapshot

Allocator 快照

会话令牌

P0

SB-58

POST

/sessions/{sid}/tasking/plans

提交外部分配计划

会话令牌

P0

SB-59

GET

/sessions/{sid}/relay/{tid}/stats

接力统计

会话令牌

P0

SB-68

GET

/sessions/{sid}/tasks/previews/{preview_id}

dry-run 排队超时后的异步取回

会话令牌

P0

环境与日历

编号

方法

路径

说明

鉴权

优先级

SB-60

GET

/sessions/{sid}/env/state

EnvKeyframe(含日历、太阳、照度档)

会话令牌

P0

SB-61

POST

/sessions/{sid}/env/preset

天气预设(同 call env/preset)

会话令牌

P0

SB-62

POST

/sessions/{sid}/env/calendar

仿真日历(call env/calendar)

会话令牌

P0

SB-63

POST

/sessions/{sid}/env/query

环境场点查询

会话令牌

P0

本机运行时接口端点

下表由 packages/contracts/rest/openapi.snapshot.json 生成。这些端点服务于本机共享展示(回环访问),除健康、就绪与版本信息外均需要令牌;公开实例以只读方式提供其中与观看相关的部分。

快照:ANet4D World Runtime API v1,82 个操作。来源:packages/contracts/rest/openapi.snapshot.json。

系统与健康

方法

路径

说明

GET

/api/events

事件补拉

GET

/api/health

健康状态与构建信息(公开)

GET

/api/health/live

存活探针

GET

/api/health/ready

就绪探针(仿真、状态环与世界)

GET

/api/sys/audit

审计日志尾部(admin)

GET

/api/sys/config

生效配置(机密已掩码)

GET

/api/sys/info

版本、协议与访问模式

GET

/api/sys/perf

服务端性能窗口聚合

POST

/api/sys/perf-report

提交客户端性能报告

GET

/api/sys/perf-reports

性能报告列表

GET

/api/sys/perf-reports/{rid}

性能报告原文

GET

/api/sys/procs

进程状态

POST

/api/sys/restart

重启进程或复位熔断(admin)

鉴权与身份

方法

路径

说明

POST

/api/auth/confirm

签发一次性确认令牌(绑定操作与对象,10 s 有效)

POST

/api/auth/identity

内部身份验证(部署方口令,限流与锁定)

DELETE

/api/auth/identity

撤销内部身份令牌

POST

/api/auth/token

签发访问令牌

GET

/api/auth/whoami

当前主体与角色

世界

方法

路径

说明

POST

/api/world/{world_id}/query

几何查询(高度、净空、视线、射线求交、路径校验)

GET

/api/worlds

世界列表

GET

/api/worlds/{world_id}

世界详情

机队

方法

路径

说明

GET

/api/fleet/caps

机群能力与上限

GET

/api/fleet/profiles

机型参数档列表

GET

/api/fleet/profiles/{profile_id}

机型参数档详情

GET

/api/fleet/vehicles

无人机列表

POST

/api/fleet/vehicles

添加无人机

GET

/api/fleet/vehicles/{vid}

无人机详情

DELETE

/api/fleet/vehicles/{vid}

移除无人机

POST

/api/fleet/vehicles/{vid}/faults

注入故障

DELETE

/api/fleet/vehicles/{vid}/faults/{fault_id}

清除故障

命令

方法

路径

说明

GET

/api/commands

命令列表

POST

/api/commands

发起命令

GET

/api/commands/{cid}

命令状态

POST

/api/commands/{cid}/cancel

取消命令

剧本与任务

方法

路径

说明

GET

/api/missions

任务列表

POST

/api/missions

创建任务

POST

/api/missions/preview

任务预览

GET

/api/missions/preview/{preview_id}

取回任务预览

GET

/api/missions/{mid}

任务详情

POST

/api/missions/{mid}/{op}

任务控制(启动、暂停、继续、取消)

GET

/api/scenario

当前剧本的加载状态与结果

GET

/api/scenarios

剧本列表

GET

/api/scenarios/{sid}

剧本详情

环境

方法

路径

说明

POST

/api/env/preset

切换天气预设

GET

/api/env/presets

天气预设列表

POST

/api/env/query

环境场点查询

POST

/api/env/set

设置环境参数

GET

/api/env/state

环境状态

GET

/api/env/streamlines/{lib}/{name}

风场流线

运行、录制与书签

方法

路径

说明

GET

/api/runs

运行列表

GET

/api/runs/{run}

运行详情

DELETE

/api/runs/{run}

删除运行

GET

/api/runs/{run}/bookmarks

书签列表

POST

/api/runs/{run}/bookmarks

添加书签

PATCH

/api/runs/{run}/bookmarks/{bid}

修改书签

DELETE

/api/runs/{run}/bookmarks/{bid}

删除书签

GET

/api/runs/{run}/events

运行事件

POST

/api/runs/{run}/keep

保留运行(不参与配额回收)

GET

/api/runs/{run}/segments/{name}

录制分段文件

作业

方法

路径

说明

GET

/api/jobs

作业列表

GET

/api/jobs/{job_id}

作业详情

POST

/api/jobs/{job_id}/cancel

取消作业

GET

/api/jobs/{job_id}/log

作业日志

POST

/api/jobs/{job_id}/retry

重试作业

POST

/api/worlds/{world_id}/build

构建世界(作业)

重建

方法

路径

说明

GET

/api/recon/engines

重建引擎列表

POST

/api/recon/jobs

提交重建作业

智能体

方法

路径

说明

GET

/api/agent-tasks

智能体任务列表

POST

/api/agent-tasks

提交智能体任务

GET

/api/agent-tasks/{task_id}

智能体任务详情

POST

/api/agent-tasks/{task_id}/assign

指派任务

GET

/api/agent-tasks/{task_id}/board

任务的报价与竞标看板

POST

/api/agent-tasks/{task_id}/cancel

取消智能体任务

GET

/api/agent-tasks/{task_id}/evidence

任务证据与回执

GET

/api/agents

智能体列表

GET

/api/agents/{aid}/manifest

智能体能力清单

实时协议

方法

路径

说明

GET

/api/rt/inspect

实时连接检视

GET

/api/rt/topics

实时主题目录

会话

方法

路径

说明

GET

/api/sessions/current

当前会话

观看排队

方法

路径

说明

POST

/api/viewer/queue

领取观看排队票

GET

/api/viewer/queue/{ticket_id}

观看排队状态长轮询

DELETE

/api/viewer/queue/{ticket_id}

离开观看排队