GRID Docs | General Robotics

The grid-cortex-client Python package provides a unified interface to all AI models hosted on GRID Cortex.

Installation

Inside a GRID session workspace the client is already installed — skip this step. On your own machine, install it with pip:

pip install grid-cortex-client

It is recommended that you use Python 3.10+

Authentication & Endpoint

Set up your API key (and endpoint, if needed):

During onboarding General Robotics will give you a personal CORTEX API key.
Export it so the client can pick it up automatically:
export GRID_CORTEX_API_KEY="<YOUR_KEY>"
If you run Cortex on-prem or on a managed cloud deployment, point the client at the Cortex API URL supplied with your deployment — the dedicated grid-… API hostname, not the admin-… portal hostname:
export GRID_CORTEX_BASE_URL="https://<your-cortex-api-host>/cortex"

You can also pass the key directly when constructing the client:

from grid_cortex_client import CortexClient
client = CortexClient(api_key="<YOUR_KEY>")

Quick Start (2 lines)

Get started with just two lines of code:

from grid_cortex_client import CortexClient
result = CortexClient().run(model_id="zoedepth", image_input="demo.jpg")

The result type depends on the model — see the individual model pages for details.

Unified API

Every model is called through the same function:

CortexClient.run(model_id: str, **kwargs) -> Any

model_id — the model identifier (e.g. "zoedepth", "gsam2", "pi05")
**kwargs — model-specific inputs (image_input, prompt, left_image, etc.)

from grid_cortex_client import CortexClient

client = CortexClient()
depth = client.run(model_id="zoedepth", image_input="scene.jpg")
mask  = client.run(model_id="gsam2", image_input="scene.jpg", prompt="a robot arm")

Discovery

List all available models and get per-model documentation at runtime:

from grid_cortex_client import CortexClient

client = CortexClient()

# List all deployed model IDs
print(client.available_models())
# ['da3metric', 'zoedepth', 'owlv2', 'gsam2', 'sam3', ...]

# Get detailed documentation for a specific model
print(client.help("sam3"))

You can also use the ModelType enum for IDE autocompletion:

from grid_cortex_client import CortexClient, ModelType

client = CortexClient()
depth = client.run(ModelType.ZOEDEPTH, image_input="demo.jpg")

Async & WebSocket Clients

AsyncCortexClient

For asyncio-based applications, use AsyncCortexClient — same API as CortexClient but with await:

from grid_cortex_client import AsyncCortexClient

async def main():
    client = AsyncCortexClient()
    depth = await client.run(model_id="zoedepth", image_input="demo.jpg")
    print(depth.shape)
    await client.close()

CortexHubClient (WebSocket)

For high-throughput pipelines, CortexHubClient provides a persistent WebSocket connection. It supports two patterns: Request-response (simple)

from grid_cortex_client import CortexHubClient, ModelType

async with CortexHubClient() as hub:
    depth = await hub.run(ModelType.ZOEDEPTH, image_input=img)

Pub/Sub (concurrent, non-blocking)

from grid_cortex_client import CortexHubClient, ModelType

async with CortexHubClient() as hub:
    await hub.publish(ModelType.ZOEDEPTH, request_id="depth1", image_input=img)
    await hub.publish(ModelType.GSAM2, request_id="mask1", image_input=img, prompt="cat")

    async for result in hub.subscribe():
        print(f"{result.request_id}: ok={result.ok}")
        process(result.data)

Each HubResult contains request_id, model, data, ok, and optional error.

Troubleshooting

401 Unauthorized – Check that your shell actually has GRID_CORTEX_API_KEY exported and that the key is correct. Timeout / connection errors – If you are on-prem/managed cloud, confirm GRID_CORTEX_BASE_URL points to your instance. You can also adjust the default 30 s timeout:

client = CortexClient(timeout=60)

Overview

Cortex Models

GRID Cortex Client

Installation

Authentication & Endpoint

Quick Start (2 lines)

Unified API

Discovery

Async & WebSocket Clients

AsyncCortexClient

CortexHubClient (WebSocket)

Troubleshooting

Installation

Authentication & Endpoint

Quick Start (2 lines)

​Unified API

​Discovery

​Async & WebSocket Clients

​AsyncCortexClient

​CortexHubClient (WebSocket)

​Troubleshooting

Unified API

Discovery

Async & WebSocket Clients

AsyncCortexClient

CortexHubClient (WebSocket)

Troubleshooting