BuildAI Python SDK

Python client for Build AI services.

Install

cd apps/buildai-sdk
uv pip install -e .

Quick Start

import buildai

client = buildai.Client(api_key="bai_...")

# Search
hits = client.search("person welding")
for h in hits.data:
    print(h.clip_id, h.score)

# Browse
factories = client.factories.list()
clip = client.clips.get("clip-uuid")
streams = client.sessions.streams("session-uuid")

datasets = client.datasets.list()

client.close()

If api_key= is omitted, the SDK first checks BUILDAI_TOKEN (or BUILDAI_API_KEY), then falls back to the CLI credential stored by buildai login in ~/.buildai/credentials.json.

Modes

The SDK has two modes:

• mode="public" is the default and targets the public /v1 contract
• mode="internal" unlocks internal-only resources when your credential is allowed to use them

Important:

• both modes use the same /v1 API prefix
• the distinction is authorization and exposed resource set, not a separate base URL

Dataset Surface

Use client.datasets for the canonical public dataset surface. For the underlying storage model, read ../../docs/data-model.md.

Package Layout

• buildai/client.py — Client entry point
• buildai/resources/v1/ — Resource namespaces
• buildai/models/v1/ — Response models
• buildai/ids.py — Deterministic UUID helpers