云端 API

云端模型 API 接收当前观测，返回一段机器人动作。正式 Base URL 为 https://api.pokebot.com/v1。按账户与 API Key设置 PLATFORM_BASE_URL 和 PLATFORM_API_KEY。

所有请求使用 Authorization: Bearer <API_KEY>。以下路径均相对于 Base URL，凭据应保存在服务端或本地控制程序中。

接口概览复制标题链接

第一次调用可从快速开始入手。连续执行任务的轮次和回执流程见连续任务与会话。

获取模型复制标题链接

GET /models

返回当前 API Key 可调用的模型。从响应的 data 数组读取 id，将选中的值用于后续请求的 model 字段。

curl --fail-with-body "$PLATFORM_BASE_URL/models" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

模型 ID 是调用标识。直接使用返回的值，无需根据产品名称推导。

查看模型约束复制标题链接

GET /models/{model_id}/schema

选定模型后，使用它的 ID 查询 schema。下面的 PLATFORM_MODEL 是从模型列表中选择的值。

curl --fail-with-body "$PLATFORM_BASE_URL/models/$PLATFORM_MODEL/schema" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

更换模型时重新读取 schema，按所选模型的约束准备观测与动作。

生成动作复制标题链接

POST /chat/completions

请求使用 JSON，包含模型 ID 和一条描述当前观测的 user 消息。

文本部分包含 instruction 和 state，并通过 JSON.stringify() 编码为字符串。图像部分使用 base64 data URL。

const request = {
  model: process.env.PLATFORM_MODEL,
  messages: [{
    role: "user",
    content: [
      {
        type: "text",
        text: JSON.stringify({ instruction, state })
      },
      {
        type: "image_url",
        image_url: { url: imageDataUrl }
      }
    ]
  }]
};

instruction 是任务指令，state 是采集到的机器人状态，imageDataUrl 是对应时刻的相机图像。格式见观测与动作；完整调用见 Python 或 JavaScript 与 curl。

读取动作复制标题链接

响应通过 execute_actions 工具调用返回动作。找到 choices[0].message.tool_calls 中对应的条目，将 function.arguments 解析为 JSON，读取其中的 output。

const call = result.choices?.[0]?.message?.tool_calls?.find(
  (item) => item.function?.name === "execute_actions"
);
if (!call) throw new Error("Missing execute_actions result");
const { output } = JSON.parse(call.function.arguments);

output 是动作序列：每行包含 8 个数值，行数以本次结果为准。数据顺序和坐标要求见观测与动作。

会话响应中的 metadata.action_shape 是 JSON 字符串，解析后表示本轮交付的动作形状；inference_usage.output_shape 描述原始模型输出，两者可能不同。控制程序应核对本轮交付形状，再执行动作并采集下一次观测。RoboAPI 本地运行程序负责这一循环和执行回执；自行接入时按连续任务与会话实现。

查询请求与用量复制标题链接

GET /requests/{request_id}

使用推理响应头 X-Request-ID 查询本次请求；查询会话轮次时，也可读取该轮的 request_id。completion 响应体的 id（如 chatcmpl-…）是另一种标识，不能用于这个接口。

Python 示例通过 response._request_id 读取请求编号，JavaScript 通过 response.headers.get("x-request-id") 读取。将实际编号填入 REQUEST_ID：

REQUEST_ID="<X_REQUEST_ID>"
curl --fail-with-body "$PLATFORM_BASE_URL/requests/$REQUEST_ID" \
  -H "Authorization: Bearer $PLATFORM_API_KEY"

查询结果包含 status、code、started_at、finished_at、timings 和 inference_usage。succeeded 表示推理完成，机器人是否执行动作由控制程序的回执确认。若会话请求中断且未收到请求 ID，可用会话 ID 和轮次查询已保存的响应，避免盲目重新执行。

usage 可能为 null。推理用量用于了解一次调用的计算结果；账户额度和账单以开发者控制台为准。

处理错误复制标题链接

先检查 HTTP 状态，再解析响应。认证、权限、输入格式和服务繁忙的处理方式见云端调用错误。

首次接入可从云端快速开始完成一次调用。连接自有机器人后，可通过本地 HTTP API操作本地运行程序。