The API for Physical AI™

Four contracts, one request shape

Physical AI does not fit one verb. A model that imagines the next second of video and a model that emits joint targets are different products, so they are different endpoints rather than one endpoint that returns whatever the backend happened to produce.

Your first call

Ask for a job, not a checkpoint. sidekick/auto:manipulation is a router alias: Sidekick picks whichever manipulation policy and pool fit, and the response tells you which one answered. This is a real exchange, and it is one where the first choice did not answer.

{
  "id": "req_29e72634fd584a87b801",
  "object": "world.action",
  "model": "physical-intelligence/pi-0",
  "action": {
    "space": "joint_pos_14",
    "steps": [
      [ 0.0614, -0.0042, -0.0120, -0.0567, ..., 0.5865],
      [ 0.0672, -0.0008, -0.0104, -0.0579, ..., 0.5878],
      ...
    ],
    "dt_ms": 66,
    "note": "4 steps, 14 joint targets each: 7 per arm"
  },
  "route": {
    "model": "physical-intelligence/pi-0",
    "region": "us-east",
    "precision": "bf16",
    "attempts": [
      { "model": "physical-intelligence/pi-0-5",
        "status": "error", "latency_ms": 30188,
        "reason": "upstream did not answer within 30s" },
      { "model": "physical-intelligence/pi-0",
        "status": "ok", "latency_ms": 684 }
    ],
    "fallback_used": true,
    "simulated": false
  },
  "usage": {
    "action_steps": 4, "gpu_seconds": 0.6844,
    "cost_usd": 0.005416
  }
}

The caller named a job, not a checkpoint. The router tried π0.5 first, that pool did not answer inside its 30-second budget, so it fell past to π0 and had an answer 684 ms later. The client retried nothing and knew neither model name in advance. route.attempts is the audit trail and it includes the failure rather than hiding it. simulated is the honesty flag: true means placeholder output rather than a model prediction, so you can never mistake one for the other. usage.cost_usd is what came off your balance, and it covers the call that succeeded.

Say what you care about, and how far you want to go

One field. You are not tuning a router, you are stating a priority, and the router turns that into an ordering over every model and pool that can serve your request.

{ "model": "sidekick/auto:manipulation", "preference": "fastest" }

The model field, and what outranks what

Three forms, and three places to state a priority. If you write more than one, the narrower one wins.

So {"model": "physical-intelligence/pi-0-5:turbo", "preference": "cheapest"} routes for latency: the suffix is attached to the model you named, so it outranks the preference you set for the request.

The whole request, and where each option sits

One call. The top level says what you want; the provider block says how to choose who serves it. Nothing here is required except model and observations.

POST /v1/act
Idempotency-Key: ep-8f21-step-014
{
  "model": "sidekick/auto:manipulation",
  "preference": "fastest",
  "instruction": "put the spoon on the towel",
  "action_space": "ee_delta_6d_grip",
  "horizon": 16,
  "observations": [{
    "frames": [{"camera": "primary", "url": "https://..."}],
    "proprio": [0, 0, 0, 0, 0, 0, 0]
  }],
  "provider": {
    "objective": {"latency": 0.7, "price": 0.3},
    "deadline_ms": 200,
    "max_cost_usd": 0.05,
    "min_uptime_30d": 0.995,
    "session_id": "ep-8f21",
    "hedge": {"after_ms": 80},
    "data_collection": "deny"
  }
}

Routing with the Sidekick API

Ordering is on measured latency, so a pool whose real traffic disagrees with its advertised p50 is demoted rather than believed. The terminal below runs this planner against live supply for free, and lists every field in full.

Three loops, three blocks worth copying

The same API, tuned to what is actually waiting on the answer.

"provider": {
  "objective": {"latency": .8, "reliability": .2},
  "deadline_ms": 150,
  "hedge": {"after_ms": 80},
  "session_id": "ep-8f21",
  "min_uptime_30d": 0.995
}

"provider": {
  "sort": "price",
  "max_cost_usd": 0.02,
  "allow_fallbacks": true
}

"provider": {
  "only": ["modal-sidekick-2"],
  "region": ["us-east"],
  "data_collection": "deny",
  "allow_fallbacks": false
}

Every field above is enforced by the router and previewable for free: the terminal below runs this exact planner against live supply and shows you the plan it would call, without calling anything. Full reference with worked examples in the API section.

Where the models are

Every entry by domain and by how far along it is toward being servable. The routable column is what a developer can call today. Counts include the policy and embodied reasoning models below, which are tracked here because they are what most developers reach for, and labelled because they are not world models: a policy has no generative video head, and a reasoner returns neither frames nor joint targets.

Task families

The source list's own taxonomy, preserved. Each family is addressable as a router alias (sidekick/auto:manipulation) so callers name a job rather than a checkpoint.

Providers

Who can serve these models, and at what cost and latency. Median price is across every offering that provider carries.

Authentication

One bearer token per key. Keys are scoped and can be limited to specific models, a workspace budget and a rate limit.

Authorization: Bearer sk-sidekick-...

Never put a key in browser JavaScript. Call Sidekick from your own server, or use the server-side proxy pattern in the SDK. A key in a client bundle is a key on someone else's machine.

Inference

Four contracts rather than one because the outputs are not interchangeable. A world model rolls video forward, a policy emits joint targets, a reasoner returns image coordinates. Collapsing them into one endpoint would let a caller execute pixel coordinates as joint targets, and nothing in the response would say so.

Choosing a model

The model field takes three things, and a provider block steers the choice within them.

"provider": {
  "order": ["modal", "baseten"],   // try these first, in this order
  "only":  ["modal"],              // or restrict to these entirely
  "ignore": ["fal"],               // never route here
  "sort": "price",                 // price | throughput | latency
  "max_latency_ms": 150,           // hard deadline; providers over it are skipped
  "allow_fallbacks": true,         // false means fail rather than substitute
  "data_collection": "deny",       // skip providers that retain your frames
  "require_parameters": true       // skip providers that would drop seed, etc.
}

GET /v1/routes lists every alias and variant. GET /v1/models is the whole registry as JSON, filterable by domain, contract, embodiment and action space.

Reliability and cost control

Account, billing and ops

Your account

Paste a Sidekick API key. It is held in this tab's memory only, never written to storage and never sent anywhere except this API, because a key in localStorage is readable by every script that ever runs on this origin.

No key yet? Accounts are provisioned by the Sidekick team while the API is in preview. Ask for one, then come back here to top up.

Credits

One balance covers every model and every provider. Prepaid rather than metered on purpose: a rollout that runs long is not fraud, and a prepaid balance means the gateway refuses work with a 402 before renting a GPU instead of sending you an invoice you did not expect.

Route preview

What this is: when you send a request, Sidekick does not call one fixed model. It builds a ranked plan of model-and-provider pairs that satisfy your constraints, calls the first, and falls to the next if that one errors or times out. This runs exactly that planner and shows you the list, without calling any model. Nothing is billed, so it doubles as a pricing calculator. Change the preference and watch the order change; the same planner answers your /v1/act calls.

Two prices, and the gap between them is the point. List is the published rate for the horizon you set. Now is what this call would actually cost at this moment, and it is higher only when the container is scaled to zero, because waking a GPU costs real money and so does the minute it stays warm afterwards. We charge that to the request that caused it rather than spreading it across everyone. A call inside a running control loop extends the warm window by its own duration and prices at list, so the two numbers are the same. Press the button twice in a row and watch the second one drop.