How the API works

Your Python client runs on a computer connected to your robot or simulator. Reactor runs the policy on cloud GPUs. Your client sends camera images, a task, and any required robot state; Reactor returns predicted actions. Your local controller validates and executes them. No local model weights or inference GPU are required.

Connection and data

Concept	Meaning
Model identifier	A name such as `reactor/cosmos-nano-policy-droid`. It selects the policy and its observation/action contract.
Session	A persistent connection to one hosted model. Keep it open across predictions; model history and counters can persist within it.
Camera track	A named stream of successive RGB images. For example, `wrist_view` identifies the wrist camera; it is not a filename or device ID.
Command	A named operation with a JSON payload, used to send tasks, state, or model controls.
Message	A model output delivered to your client, such as an action prediction. Commands and messages carry structured data separately from video.
Action chunk	A sequence of predicted actions. Rows are control steps; columns are the model’s joint, end-effector, gripper, or other control values.

Select a model and provide your API key. Register message handlers before connecting so early replies are retained.
Connect and wait for READY before publishing tracks or sending commands. Session setup can take time while model capacity and the network connection become ready.
Keep the required camera tracks publishing, and send the task and measured state. Capture related measurements together: video and commands arrive separately.
Receive and validate an action chunk. Your local controller decides which rows to execute and when. Follow the model’s protocol to obtain the next prediction.
Close the session when finished.

Action arrival is not the robot’s control clock. Account for capture, network, inference, and execution delay when deciding whether an action is still usable. A model reset does not reset or stop the robot. Each model’s integration guide defines its execution and recovery rules.

Python SDK and cookbook helpers

The quickstarts use the Python SDK and the reactor_robotics helper directory in Reactor’s public cookbook. These helpers provide camera publishing and message queues. Each quickstart includes installation; installing the SDK alone does not install the helpers. You can use the helpers or the SDK directly. At the SDK layer, on_message receives a dictionary with type and data. This abbreviated Cosmos reply shows the first row of a 32-row chunk:

{
  "type": "action_prediction",
  "data": {
    "step": 0,
    "action": [[0.0, -0.6, 0.0, -2.2, 0.0, 1.6, 0.8, 0.0]]
  }
}

For Cosmos, action is shaped (32, 8): seven joint targets in radians and one gripper value per row. step is its prediction counter. Other models have different fields, dimensions, and counter semantics; use the selected model’s reference. ReactorSession.next_message(...) returns the inner data dictionary. The examples convert its action values to NumPy arrays; model-specific helpers can return their own objects. See the helper reference for return values and the Python SDK reference for callbacks, commands, and errors. Neither the SDK nor the helpers execute actions on your robot.

If the first run fails

Where it fails	What to check
Importing `reactor_robotics`	Run from `robotics/sim/notebooks/` in the cookbook checkout with `uv run --frozen python ...`. The helpers are installed from that checkout.
Authentication or model access	Check the API key, endpoint, and model slug. If access is restricted, contact Reactor.
Session creation: `429` with `no available capacity`	The session could not be allocated. Retry with bounded backoff or contact Reactor. Other 429 reasons can indicate quota or rate limits; read the error text.
Connected, but no action reply	Check required tracks, state fields, and the model’s first-prediction trigger. An accepted command alone does not prove inference ran. Use the model’s troubleshooting page.

For support, retain the model slug, SDK/client versions, session ID if available, failure stage, and error text. Never include an API key. See billing for session costs and support for help. Choose a model and follow its quickstart.

Get started

Models

How the API works

Connection and data

Python SDK and cookbook helpers

If the first run fails

​Connection and data

​Python SDK and cookbook helpers

​If the first run fails

Connection and data

Python SDK and cookbook helpers

If the first run fails