观测与动作
准备一次推理所需的任务指令、相机图像和机器人状态。
一次观测由任务指令、相机图像和机器人状态组成。图像与状态应来自同一时刻，让模型能够判断机器人与物体的当前位置。
选择模型
使用 API Key 调用 GET /models，从返回的 data 数组中选择一个 id 作为请求的 model。模型的可用范围由账户权限决定，调用时使用接口返回的标识。请求方式见云端 API。
首次接入或更换模型时，读取 GET /models/{model_id}/schema，确认输入和输出约束：
| Schema 字段 | 准备输入时检查 |
|---|---|
inputs.properties.state | 数组长度与数值范围 |
image | 文件格式、RGB 色彩模式、像素数与宽高比上限 |
text | 非空要求与存在时的 max_chars 长度限制 |
output、session.output | 原始模型输出与会话交付动作的形状 |
任务指令
使用简洁、明确的自然语言描述目标，例如“把蓝色衣服展开”。为同一个任务持续采集新的观测时，保持指令一致。
将指令放入 instruction 字段，与 state 一起编码为消息的 JSON 文本：
const text = JSON.stringify({ instruction, state });相机图像
提供一张 RGB PNG 或 JPEG，将原始文件编码为 base64 data URL：
data:image/png;base64,<BASE64_IMAGE>JPEG 使用 data:image/jpeg;base64, 前缀。MIME 类型应与实际文件格式一致。
将 data URL 放入 image_url.url。图像像素数和宽高比不得超过 schema 中的 max_pixels、max_aspect_ratio；尺寸与预处理要求以该模型的 image 字段为准。相机视角和图像方向需要与模型的输入要求一致；使用本地控制台时，由已配置的相机提供图像。
机器人状态
state 是包含 8 个有限数值的数组。RoboAPI 的模型接口使用以下顺序：
[x, y, z, qx, qy, qz, qw, gripper]| 字段 | 含义 |
|---|---|
x, y, z | 控制点在模型任务坐标系中的位置，单位为米 |
qx, qy, qz, qw | 控制点姿态，四元数按 xyzw 顺序排列 |
gripper | 归一化夹爪开度，0 为闭合，1 为张开 |
使用当前采集的状态；四元数应归一化，所有数值均需有效。直接使用机器人厂商接口时，需要先转换坐标系、四元数顺序和夹爪开度。
RoboAPI 本地运行时使用法兰中心作为控制点，坐标标定建立机器人与模型坐标的映射。
模型接口的四元数顺序为 xyzw；机器人厂商和各个本地接口的位姿表示可能不同，应按对应接口定义转换。RoboAPI 运行程序负责所支持设备的适配。自行接入时，状态坐标系和工具方向仍需与所选模型匹配。
读取输出
模型返回的 output 由多行动作组成，每行采用同样的 8 维顺序。行数按模型 schema 和本次响应核验，不要固定在客户端中。
会话响应中的 metadata.action_shape 是 JSON 字符串，解析后用于核对本轮交付的动作；inference_usage.output_shape 记录原始模型输出，不能当作实际执行步数。执行前还需检查数值有效性、机器人工作空间和动作限制。连续任务的控制循环与回执见连续任务与会话，请求字段见云端 API。