第一次 API 调用
发送图片、机器人状态和任务指令，获取一段动作。
这段 Python 程序调用云端模型并打印动作结果。你只需要 API Key、一张相机图片和对应的机器人状态；运行示例不会驱动设备。
1. 准备环境
先在 开发者控制台 创建 API Key。安装 OpenAI Python SDK，并按 账户与 API Key 设置 PLATFORM_BASE_URL 和 PLATFORM_API_KEY。
python3 -m venv .venv
source .venv/bin/activate
python -m pip install openai查询当前密钥可调用的模型：
curl --fail-with-body "$PLATFORM_BASE_URL/models" \
-H "Authorization: Bearer $PLATFORM_API_KEY"从返回列表中复制要使用的 id，设置到 PLATFORM_MODEL。下面的值需要替换：
export PLATFORM_MODEL='<MODEL_ID>'2. 准备观测
将一张 RGB PNG 保存为 input.png，将拍摄时的八维机器人状态保存为 state.json。状态包含位置、旋转四元数与夹爪值；排列和坐标要求见 观测与动作。
使用与你的控制器适配一致的实际状态，图片与状态应来自同一次观测。示例中的任务指令可以替换为画面中的具体任务。
3. 请求动作
将下面代码保存为 first_action.py：
import base64
import json
import os
from pathlib import Path
from openai import OpenAI
image = base64.b64encode(Path("input.png").read_bytes()).decode("ascii")
state = json.loads(Path("state.json").read_text())
with OpenAI(
base_url=os.environ["PLATFORM_BASE_URL"],
api_key=os.environ["PLATFORM_API_KEY"],
timeout=60,
max_retries=0,
) as client:
response = client.chat.completions.create(
model=os.environ["PLATFORM_MODEL"],
messages=[{
"role": "user",
"content": [
{"type": "text", "text": json.dumps({
"instruction": "Unfold the blue shirt",
"state": state,
})},
{"type": "image_url", "image_url": {
"url": f"data:image/png;base64,{image}",
}},
],
}],
)
print("Request ID:", response._request_id)
calls = response.choices[0].message.tool_calls or []
action_call = next(
call for call in calls
if call.type == "function" and call.function.name == "execute_actions"
)
actions = json.loads(action_call.function.arguments)["output"]
print("Actions:", len(actions))
print("First action:", actions[0])python first_action.py成功时会打印请求编号、动作数量和第一行动作。response._request_id 读取响应头 X-Request-ID，可用于查询请求；不要使用 completion 的 id 代替。动作行数由模型决定；每行的含义见 观测与动作。
接入自己的控制循环
一次请求对应一次观测。你的程序需要执行以下循环：
- 读取当前相机画面与机器人状态。
- 连同任务指令请求模型。
- 检查动作格式，按控制器的坐标、速度与运动边界执行。
- 采集新的观测，继续下一次调用。
连续任务通过会话与执行回执关联每轮观测和动作。停止或通信异常后，丢弃未执行的旧动作，并重新确认机器人状态。不要仅根据网络重试结果重复执行上一段动作。
如果希望使用现成的设备采集与执行流程，继续 安装 RoboAPI。需要其他语言时查看 JavaScript 与 curl；参数和错误处理分别见 API 参考 与 调用错误。