protoface-sdk

Official Python SDK for the Protoface API.

Install protoface-sdk and import protoface_sdk.

Installation

pip install protoface-sdk

Or with uv:

uv add protoface-sdk

Requires Python 3.10+ and a Protoface API key.

Quickstart

import os

from protoface_sdk import ProtofaceClient

with ProtofaceClient(api_key=os.environ["PROTOFACE_API_KEY"]) as client:
    status = client.get_status()
    avatars = client.avatars.list(limit=10)

    print(status.status.value)
    print([avatar.id for avatar in avatars.data])

Resources

client.sessions.create(session_request, idempotency_key=...)
client.sessions.create_livekit(avatar_id=..., url=..., room_name=..., worker_token=...)
client.sessions.get(session_id)
client.sessions.list(status=["running"], avatar_id=..., limit=...)  # -> Page[Session]
client.sessions.end(session_id)

client.avatars.list(scope="platform", q="stock", limit=...)    # -> Page[Avatar]
client.avatars.get(avatar_id)
client.avatars.create(image=..., name=...)                     # multipart upload
client.avatars.delete(avatar_id)

client.pipecat.sessions.create(avatar_id=...)                  # Pipecat relay bootstrap

client.usage.summary(period="current_month")                   # or period_start/period_end

client.list_billing_plans()
client.get_status()

Page objects expose .data, .has_more, and .next_cursor. Pass .next_cursor back as starting_after to fetch the next page.

LiveKit sessions

client.sessions.create_livekit(...) starts the backend worker for a customer-owned LiveKit room. Your application still owns the room and mints a short-lived worker token with its own LiveKit API key and secret.

session = client.sessions.create_livekit(
    avatar_id="av_stock_001",
    url=livekit_url,
    room_name="demo-room",
    worker_token=worker_token,
)

session = session.wait_until_running(timeout=10)
print(session.id, session.status)

For framework-level realtime integrations, use the dedicated packages:

• livekit-plugins-protoface for LiveKit Agents.
• pipecat-protoface for Pipecat.

Errors

Every non-2xx response raises a typed ProtofaceError subclass (AuthenticationError, RateLimitError, QuotaExceededError, etc.). Switch on the stable error.code, never on error.message:

from protoface_sdk import ProtofaceError, QuotaExceededError, RateLimitError

try:
    client.sessions.create(session_request)
except RateLimitError as err:
    print("rate limited:", err.code, err.retry_after_seconds)
except QuotaExceededError as err:
    print("quota:", err.code)
except ProtofaceError as err:
    print(err.code, err.request_id, err.status)

The client retries 429, 503, and transient network failures for safe requests, and for writes that include an Idempotency-Key.

License

Apache-2.0 - see LICENSE.