本地 HTTP API

地址与请求格式复制标题链接

本地 HTTP API 与控制台共用设备和配置。运行 roboapi http 后，使用 http://127.0.0.1:8080。直接请求云端模型请使用 云端 API。

POST 请求使用 Content-Type: application/json，请求体为 JSON 对象，无参数时传 {}。普通请求上限 16 KiB，预设与批量存储清理上限 128 KiB。本地接口没有账户鉴权；远程访问使用 SSH 转发，浏览器写操作需同源。

状态与视频复制标题链接

curl --fail-with-body http://127.0.0.1:8080/api/status

mode 为 idle、running 或 paused。开始任务前检查 control_ready、设备与模型连接；arm_connected 只表示机械臂的连接状态。视频流断开后，客户端应重新请求流地址。

任务与运行控制复制标题链接

指令去首尾空白后须为 1–1000 字符。HTTP 启动的运行使用 run_source: "web"；更新指令、暂停和恢复要求来源一致。Agent 运行时须先停止，再通过 HTTP 开始。

new_task 可选，默认 false：指令与当前本地任务相同则继续该任务，追加时长和录像；不同指令创建新任务。传 true 始终创建新的本地任务，即使指令相同。每次 start 都开始一次运行，不应把本地任务 ID 当作云端会话 ID。

start 接受请求不代表后台首轮推理成功；任务会持续到停止或故障。/api/instruction 不截断当前动作块。要复现网页中途发送新任务的行为，依次 stop、确认 mode: "idle"、start 并传 new_task: true。

模型设置与预设复制标题链接

获取可用模型复制标题链接

调用 POST /api/policy/models，通过本地运行时查询模型服务：

{"url": "https://api.pokebot.com/v1"}

url 必填，api_key 可选。省略 Key 时使用本地已保存的凭据；使用新的 Key 时传入 api_key，不要传空字符串。成功返回当前 Key 可用的实际模型 ID：

{"models": ["MODEL_ID"]}

此请求只查询列表，不保存地址或凭据，不创建任务会话。修改地址或 Key 后重新获取列表；列表为空或连接失败时返回 502，已保存设置保持不变。MODEL_ID 是示意值，后续配置使用实际返回的 ID。

保存连接与运行参数复制标题链接

空闲时调用 POST /api/policy/config。url、model、inter_chunk_pause_s 必填，api_key 可选。省略 Key 保留旧凭据，不要传空字符串。配置经过 /models 检查后保存，失败保留原值。

{
  "url": "https://api.pokebot.com/v1",
  "model": "MODEL_ID",
  "inter_chunk_pause_s": 0.5
}

Base URL 使用正式服务地址 https://api.pokebot.com/v1，MODEL_ID 替换为该服务 /models 返回的模型 ID。inter_chunk_pause_s 为非负秒数，控制动作块结束后、下一次观测前的等待。服务须符合 本地运行协议。

保存预设复制标题链接

POST /api/presets 保存预设，不运行任务：

{"instructions": ["Pick up the block", "Place it in the tray"]}

最多 20 条，每条 1–1000 字符。

标定动作复制标题链接

路径均为 POST /api/calibration/{action}。按 坐标标定 完成现场准备，再调用以下动作。

HTTP 的 confirm_plane_c 不代替后续 save 与 enable_control。确认字段须反映现场操作人的实际确认。关闭网页不取消示教；需要放弃时使用 /api/devices/release。

方向试动复制标题链接

POST /api/calibration/check 请求体只有一个字段：

{"direction":"forward"}

direction 可选 forward、left、up、home。前三者从 Home 平移 5 cm、旋转 30° 后返回，home 仅返回，均保持夹爪开度。具体轴向见 方向试动。接口在动作结束后返回；/api/stop 可打断，且会取消剩余返回轨迹。

活动范围复制标题链接

POST /api/workspace/config 接受完整配置。位置均为模型坐标中的绝对值，单位米；与页面中“距初始位置 / cm”的输入不同。

{
  "enabled": true,
  "min_xyz_m": [-0.73, -1.06, -0.11],
  "max_xyz_m": [0.47, 0.14, 1.09]
}

这是默认的 Home ±0.60 m。每个数组必须包含三个有限数值，每轴最小值小于最大值，范围须包含 Home [-0.13,-0.46,0.49]。空闲、结束示教后才能保存；保存不移动机器人。

启用后，超范围的法兰中心目标被收敛到边界，任务继续执行；旋转不受限制。开始、恢复或手动运动要求当前测量位置在范围内，显式返回 Home 可从范围外执行。该边界不约束整个机械臂、外力、柔顺运动或跟踪误差，也不用于避障。

任务、录像与存储复制标题链接

recording 为 off、recording、saving、ready 或 error。录像正在保存时等待其完成，再下载或清理。

cleanup 的 kind 为 recordings（只删录像，保留指令和反馈）或 tasks（删除整条记录）。省略 task_ids 处理全部任务；传空数组不处理任何任务。批量清理跳过运行中或正在保存录像的任务，单项删除这些任务返回 409。

失败响应复制标题链接

失败通常返回 {"error":"可读原因"}，控制前置条件不满足时可附 "kind":"control_not_ready"。

网络超时后先读取 /api/status 确认结果，不盲目重复启动、Home 或标定动作。详见 本地运行错误。