Python SDK

alpha-sdk-client — sync + async REST clients with Pydantic models

alpha-sdk-client is the official Python client for the Alpha Camera REST API. It ships both sync (AlphaSDKClient) and async (AsyncAlphaSDKClient) variants and uses httpx for transport.

• PyPI: alpha-sdk-client
• Latest: 0.3.0
• Python: 3.8+
• Example app / notebook helper: alpha-sdk-python

---

Install

pip install alpha-sdk-client

You also need a running server on localhost:8080. The Python client does not ship a ServerManager class — start the server using the Node-based CLI from the server package, or spawn the binary as a subprocess from Python (recipe).

# One-time install of the server package (Node)
npm install -g @alpha-sdk/api
camera-server start

---

Initialize

from alpha_sdk_client import AlphaSDKClient

client = AlphaSDKClient(base_url="http://localhost:8080")

Constructor options

AlphaSDKClient(
    base_url="http://localhost:8080",   # base URL — defaults to localhost:8080
    environment=None,                   # alternative — pass an Environment
    headers={"X-Trace-Id": "abc123"},   # applied to every request
    timeout=30.0,                       # seconds
    httpx_client=None,                  # bring your own httpx.Client
    follow_redirects=True,
)

Async variant

import asyncio
from alpha_sdk_client import AsyncAlphaSDKClient

async def main():
    client = AsyncAlphaSDKClient(base_url="http://localhost:8080")
    cameras = await client.cameras.list()
    print(cameras)

asyncio.run(main())

The async client mirrors the sync API method-for-method — every call is await-able.

---

Common operations

List + connect a camera

res = client.cameras.list()
camera_id = res.cameras[0].id

client.cameras.connect(
    camera_id=camera_id,
    mode="remote-transfer",
    reconnecting="on",
)

# Required for the host PC to drive most settings:
client.properties.set_priority_key(
    camera_id=camera_id,
    setting="pc-remote",
)

Read a single property

aperture = client.properties.get(camera_id=camera_id, property_name="aperture")
print(aperture.data.value, aperture.data.formatted)

Read every property at once

res = client.properties.get_all(camera_id=camera_id)
print(res.data.properties["iso"].current_formatted)

Set a property

client.properties.set(
    camera_id=camera_id,
    property_name="shutter-speed",
    value="1/250",
)

Trigger the shutter

client.actions.shutter(camera_id=camera_id)
# In `remote` mode the server auto-transfers; poll SSE or check the save
# directory for the new file.
# In `remote-transfer` mode call client.sd_card.download(...) explicitly.

Pull a single live-view JPEG

from PIL import Image
from io import BytesIO

jpeg_bytes = b"".join(client.live_view.get_frame(camera_id=camera_id))
img = Image.open(BytesIO(jpeg_bytes))
img.show()

For OSD-overlaid frames after client.live_view.enable_osd(camera_id=...):

jpeg_bytes = client.live_view.get_osd_frame(camera_id=camera_id)

See the live-view polling recipe for a render loop.

Disconnect

client.cameras.disconnect(camera_id=camera_id)

---

Error handling

Every method raises a typed subclass of ApiError:

from alpha_sdk_client import (
    BadRequestError,
    NotFoundError,
    InternalServerError,
)
from alpha_sdk_client.core.api_error import ApiError

try:
    client.properties.set(
        camera_id=camera_id,
        property_name="aperture",
        value="F1.0",  # not a valid value on this lens
    )
except BadRequestError as e:
    print("server rejected the value:", e.body)
except NotFoundError:
    print("camera no longer connected")
except ApiError as e:
    print("server error", e.status_code, e.body)

Each error exposes status_code, body (parsed dict), and headers. Network failures and timeouts raise httpx.HTTPError subclasses (not ApiError).

---

Advanced

Custom request options per call

client.cameras.list(
    request_options={
        "additional_headers": {"X-Trace-Id": "request-42"},
        "timeout_in_seconds": 60,
    }
)

Bring your own httpx.Client

Useful for proxying, retries, or testing:

import httpx
from alpha_sdk_client import AlphaSDKClient

httpx_client = httpx.Client(
    proxies="http://corp-proxy:8080",
    transport=httpx.HTTPTransport(retries=3),
)
client = AlphaSDKClient(base_url="http://localhost:8080", httpx_client=httpx_client)

Pydantic models

Every response body is a Pydantic v2 model — use .model_dump() to serialize, .model_validate() to construct from a dict:

res = client.cameras.list()
print(res.model_dump_json(indent=2))

Use in a Jupyter notebook

The sync client works seamlessly in notebooks. For long-running async patterns inside Jupyter, use await at the top level (Jupyter supports it natively):

client = AsyncAlphaSDKClient(base_url="http://localhost:8080")
res = await client.cameras.list()

For a minimal notebook-oriented helper layer, see:

• alpha-sdk-python
• notebook_data_collection.py

---

What’s NOT in the client

By design, the following live in recipes rather than the generated SDK:

• SSE events — use httpx.stream() against /api/events and parse text/event-stream line-by-line.
• Discovery + reconnect orchestration — copy from the discovery + reconnect recipe.

---

Versioning

alpha-sdk-client follows SemVer. Every release is documented in the package CHANGELOG, available on PyPI.