videorouter-live 0.2.0__py3-none-any.whl

videorouter_live/__init__.py

@@ -0,0 +1,23 @@
+"""videorouter-live — Python SDK for videorouter.sh live video & world models (https://videorouter.sh/docs/live-video).
+
+The SDK is a client for the session BROKER: it opens a session, keeps it alive and settles it. It never carries media —
+`session.connect` holds the host's short-lived credentials, which you hand to the host's own SDK in the browser.
+"""
+
+from ._client import AsyncLiveVideo, DEFAULT_BASE_URL, LiveVideo
+from ._errors import (AuthenticationError, ConcurrencyLimitError, HostCapacityError, InsufficientCreditsError,
+                      InvalidRequestError, LiveVideoError, NotFoundError, PermissionDeniedError,
+                      PricingUnavailableError, RateLimitError, SessionStateError, TimeoutError, UpstreamError,
+                      VideoGenerationError)
+from ._session import AsyncLiveSession, LiveSession
+from ._types import Connect, Model, Status, Token
+from ._videos import AsyncVideoJob, AsyncVideos, VideoJob, Videos
+
+__version__ = "0.2.0"
+__all__ = [
+    "LiveVideo", "AsyncLiveVideo", "LiveSession", "AsyncLiveSession", "Model", "Token", "Status", "Connect",
+    "DEFAULT_BASE_URL", "LiveVideoError", "AuthenticationError", "PermissionDeniedError", "InvalidRequestError",
+    "InsufficientCreditsError", "PricingUnavailableError", "NotFoundError", "RateLimitError",
+    "ConcurrencyLimitError", "HostCapacityError", "UpstreamError", "SessionStateError", "TimeoutError",
+    "VideoGenerationError", "Videos", "AsyncVideos", "VideoJob", "AsyncVideoJob",
+]

videorouter_live/_client.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Any, Optional
+
+import httpx
+
+from ._errors import LiveVideoError, UpstreamError, error_from_response
+from ._session import AsyncLiveSession, LiveSession
+from ._types import Model, Status, Token
+from ._videos import AsyncVideos, Videos
+
+DEFAULT_BASE_URL = "https://videorouter.sh/api/v1"
+_RETRY_STATUSES = (502, 503, 504)
+
+
+def _resolve_auth(api_key: Optional[str], token: Optional[str]) -> str:
+    secret = token or api_key or os.environ.get("VIDEOROUTER_API_KEY")
+    if not secret:
+        raise ValueError("pass api_key=... (server) or token=... (browser-safe, from create_token), "
+                         "or set VIDEOROUTER_API_KEY")
+    return secret
+
+
+def _parse(resp: httpx.Response) -> Any:
+    try:
+        body = resp.json()
+    except ValueError:
+        body = resp.text
+    if resp.status_code >= 400:
+        raise error_from_response(resp.status_code, body, resp.headers)
+    return body
+
+
+def _session_body(model: str, max_duration_seconds: Optional[int], options: Optional[dict]) -> dict:
+    body: dict[str, Any] = {"model": model}
+    if max_duration_seconds is not None:
+        body["max_duration_seconds"] = max_duration_seconds
+    if options:
+        body["options"] = options
+    return body
+
+
+def _token_body(models, expires_in, max_sessions, max_session_duration_seconds) -> dict:
+    body: dict[str, Any] = {}
+    if models is not None:
+        body["models"] = list(models)
+    if expires_in is not None:
+        body["expires_in"] = expires_in
+    if max_sessions is not None:
+        body["max_sessions"] = max_sessions
+    if max_session_duration_seconds is not None:
+        body["max_session_duration_seconds"] = max_session_duration_seconds
+    return body
+
+
+class LiveVideo:
+    """Synchronous client.
+
+        lv = LiveVideo(api_key="llmr_sk_...")
+        with lv.session("fal/happy-oyster-adventure", max_duration_seconds=60,
+                        options={"world": {"prompt": "a rainy city", "perspective": "first_person"}}) as s:
+            hand_to_browser(s.connect)        # host credentials, returned once
+            ...                                # heartbeats run in the background
+        print(s.billed_seconds, s.cost_usd)   # settled on exit
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, token: Optional[str] = None, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0, max_retries: int = 2, http_client: Optional[httpx.Client] = None) -> None:
+        self._auth = _resolve_auth(api_key, token)
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._owns = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self.videos = Videos(self)   # the /v1/videos generation API: lv.videos.generate({...})
+
+    # ── transport ────────────────────────────────────────────────────────────────────────────────────────────
+    def _request(self, method: str, path: str, json: Any = None, retry: bool = False) -> Any:
+        attempts = (self.max_retries if retry else 0) + 1
+        last: Optional[LiveVideoError] = None
+        for i in range(attempts):
+            try:
+                resp = self._http.request(method, self.base_url + path, json=json,
+                                          headers={"Authorization": f"Bearer {self._auth}"})
+                if resp.status_code in _RETRY_STATUSES and i + 1 < attempts:
+                    time.sleep(min(0.5 * 2 ** i, 4))
+                    continue
+                return _parse(resp)
+            except httpx.TransportError as exc:
+                last = UpstreamError(f"network error: {exc}")
+                if i + 1 >= attempts:
+                    raise last from exc
+                time.sleep(min(0.5 * 2 ** i, 4))
+        raise last or UpstreamError("request failed")
+
+    # ── API ──────────────────────────────────────────────────────────────────────────────────────────────────
+    def models(self) -> list:
+        return [Model.from_dict(m) for m in self._request("GET", "/live-video/models", retry=True)["data"]]
+
+    def create_token(self, *, models: Optional[list] = None, expires_in: Optional[int] = None,
+                     max_sessions: Optional[int] = None, max_session_duration_seconds: Optional[int] = None) -> Token:
+        """Mint a short-lived, live-video-only credential for a browser. Call it from your server."""
+        return Token.from_dict(self._request("POST", "/live-video/tokens", json=_token_body(
+            models, expires_in, max_sessions, max_session_duration_seconds)))
+
+    def create_session(self, model: str, *, max_duration_seconds: Optional[int] = None,
+                       options: Optional[dict] = None) -> LiveSession:
+        return LiveSession(self, self._request("POST", "/live-video/sessions",
+                                               json=_session_body(model, max_duration_seconds, options)))
+
+    def get_session(self, session_id: str) -> LiveSession:
+        return LiveSession(self, self._request("GET", f"/live-video/sessions/{session_id}", retry=True))
+
+    def session(self, model: str, *, max_duration_seconds: Optional[int] = None, options: Optional[dict] = None,
+                wait_until_ready: bool = True, auto_heartbeat: bool = True, ready_timeout: float = 300.0,
+                poll_interval: float = 4.0, heartbeat_interval: Optional[float] = None) -> "_SessionContext":
+        """Context manager: opens the session, waits until it is ready, heartbeats in the background, and settles it on
+        exit (even on error) — the common case in one `with`."""
+        return _SessionContext(self, model, max_duration_seconds, options, wait_until_ready, auto_heartbeat,
+                               ready_timeout, heartbeat_interval, poll_interval)
+
+    def close(self) -> None:
+        if self._owns:
+            self._http.close()
+
+    def __enter__(self) -> "LiveVideo":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class _SessionContext:
+    def __init__(self, client: LiveVideo, model, max_duration_seconds, options, wait, beat, timeout, interval,
+                 poll) -> None:
+        self._a = (client, model, max_duration_seconds, options, wait, beat, timeout, interval, poll)
+        self._s: Optional[LiveSession] = None
+
+    def __enter__(self) -> LiveSession:
+        client, model, dur, options, wait, beat, timeout, interval, poll = self._a
+        s = client.create_session(model, max_duration_seconds=dur, options=options)
+        self._s = s
+        try:
+            if wait:
+                s.wait_until_ready(timeout=timeout, poll_interval=poll)
+            if beat:
+                s.start_heartbeat(interval)
+        except BaseException:
+            s.end()
+            raise
+        return s
+
+    def __exit__(self, *exc: Any) -> None:
+        if self._s is not None:
+            self._s.end()
+
+
+class AsyncLiveVideo:
+    """Asyncio client — same surface as `LiveVideo`, every network method is a coroutine.
+
+        async with AsyncLiveVideo(api_key="llmr_sk_...") as lv:
+            async with lv.session("decart/lucy-2.5", max_duration_seconds=120) as s:
+                hand_to_browser(s.connect)
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, token: Optional[str] = None, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0, max_retries: int = 2, http_client: Optional[httpx.AsyncClient] = None) -> None:
+        self._auth = _resolve_auth(api_key, token)
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self._owns = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self.videos = AsyncVideos(self)   # the /v1/videos generation API: await lv.videos.generate({...})
+
+    async def _request(self, method: str, path: str, json: Any = None, retry: bool = False) -> Any:
+        attempts = (self.max_retries if retry else 0) + 1
+        last: Optional[LiveVideoError] = None
+        for i in range(attempts):
+            try:
+                resp = await self._http.request(method, self.base_url + path, json=json,
+                                                headers={"Authorization": f"Bearer {self._auth}"})
+                if resp.status_code in _RETRY_STATUSES and i + 1 < attempts:
+                    await asyncio.sleep(min(0.5 * 2 ** i, 4))
+                    continue
+                return _parse(resp)
+            except httpx.TransportError as exc:
+                last = UpstreamError(f"network error: {exc}")
+                if i + 1 >= attempts:
+                    raise last from exc
+                await asyncio.sleep(min(0.5 * 2 ** i, 4))
+        raise last or UpstreamError("request failed")
+
+    async def models(self) -> list:
+        return [Model.from_dict(m) for m in (await self._request("GET", "/live-video/models", retry=True))["data"]]
+
+    async def create_token(self, *, models: Optional[list] = None, expires_in: Optional[int] = None,
+                           max_sessions: Optional[int] = None, max_session_duration_seconds: Optional[int] = None) -> Token:
+        return Token.from_dict(await self._request("POST", "/live-video/tokens", json=_token_body(
+            models, expires_in, max_sessions, max_session_duration_seconds)))
+
+    async def create_session(self, model: str, *, max_duration_seconds: Optional[int] = None,
+                             options: Optional[dict] = None) -> AsyncLiveSession:
+        return AsyncLiveSession(self, await self._request("POST", "/live-video/sessions",
+                                                          json=_session_body(model, max_duration_seconds, options)))
+
+    async def get_session(self, session_id: str) -> AsyncLiveSession:
+        return AsyncLiveSession(self, await self._request("GET", f"/live-video/sessions/{session_id}", retry=True))
+
+    def session(self, model: str, *, max_duration_seconds: Optional[int] = None, options: Optional[dict] = None,
+                wait_until_ready: bool = True, auto_heartbeat: bool = True, ready_timeout: float = 300.0,
+                poll_interval: float = 4.0, heartbeat_interval: Optional[float] = None) -> "_AsyncSessionContext":
+        return _AsyncSessionContext(self, model, max_duration_seconds, options, wait_until_ready, auto_heartbeat,
+                                    ready_timeout, heartbeat_interval, poll_interval)
+
+    async def aclose(self) -> None:
+        if self._owns:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncLiveVideo":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+class _AsyncSessionContext:
+    def __init__(self, client: AsyncLiveVideo, model, max_duration_seconds, options, wait, beat, timeout, interval,
+                 poll) -> None:
+        self._a = (client, model, max_duration_seconds, options, wait, beat, timeout, interval, poll)
+        self._s: Optional[AsyncLiveSession] = None
+
+    async def __aenter__(self) -> AsyncLiveSession:
+        client, model, dur, options, wait, beat, timeout, interval, poll = self._a
+        s = await client.create_session(model, max_duration_seconds=dur, options=options)
+        self._s = s
+        try:
+            if wait:
+                await s.wait_until_ready(timeout=timeout, poll_interval=poll)
+            if beat:
+                s.start_heartbeat(interval)
+        except BaseException:
+            await s.end()
+            raise
+        return s
+
+    async def __aexit__(self, *exc: Any) -> None:
+        if self._s is not None:
+            await self._s.end()

videorouter_live/_errors.py

@@ -0,0 +1,107 @@
+"""Typed errors. Every failed API call raises a `LiveVideoError` subclass carrying the HTTP `status`, the API's own
+error `code`/`type`/`message`, and `retry_after` when the server sent one — match on the class, not on strings."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional
+
+
+class LiveVideoError(Exception):
+    def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None,
+                 type: Optional[str] = None, retry_after: Optional[float] = None, body: Any = None):
+        super().__init__(message)
+        self.message, self.status, self.code, self.type = message, status, code, type
+        self.retry_after, self.body = retry_after, body
+
+    def __str__(self) -> str:
+        bits = [self.message]
+        if self.status is not None:
+            bits.append(f"(HTTP {self.status}{', ' + self.code if self.code else ''})")
+        return " ".join(bits)
+
+
+class AuthenticationError(LiveVideoError):
+    """401 — missing, invalid or expired key/token."""
+
+
+class PermissionDeniedError(LiveVideoError):
+    """403 — missing `live_video` scope, a model/token restriction, or a token used outside live-video."""
+
+
+class InvalidRequestError(LiveVideoError):
+    """400 — a bad parameter (unknown model, duration above the host cap, unsupported option...)."""
+
+
+class InsufficientCreditsError(LiveVideoError):
+    """402 — the credit hold for this session isn't covered (or a spend cap was hit)."""
+
+
+class PricingUnavailableError(LiveVideoError):
+    """502 `pricing_unavailable` — the model has no verified price yet and can't be booked."""
+
+
+class NotFoundError(LiveVideoError):
+    """404 — no such session, or it belongs to another organization."""
+
+
+class RateLimitError(LiveVideoError):
+    """429 — too many requests."""
+
+
+class ConcurrencyLimitError(RateLimitError):
+    """429 `concurrency_limit` / `token_session_limit` — too many sessions open. End one first."""
+
+
+class HostCapacityError(RateLimitError):
+    """429 `host_capacity` — the host has no free capacity right now. Retry shortly; sessions are never queued."""
+
+
+class UpstreamError(LiveVideoError):
+    """5xx — the host (or the gateway) failed."""
+
+
+class SessionStateError(LiveVideoError):
+    """Raised locally: an operation that needs a different session state (e.g. waiting on an ended session)."""
+
+
+class TimeoutError(LiveVideoError):  # noqa: A001 — deliberate: scoped to this package
+    """`wait_until_ready` ran out of time."""
+
+
+def error_from_response(status: int, body: Any, headers: Mapping[str, str]) -> LiveVideoError:
+    err = (body.get("error") if isinstance(body, dict) else None) or {}
+    message = err.get("message") if isinstance(err, dict) else None
+    message = message or (body if isinstance(body, str) else f"request failed with HTTP {status}")
+    code = err.get("code") if isinstance(err, dict) else None
+    etype = err.get("type") if isinstance(err, dict) else None
+    retry_after = None
+    ra = headers.get("retry-after") or headers.get("Retry-After")
+    if ra:
+        try:
+            retry_after = float(ra)
+        except ValueError:
+            pass
+    kw = dict(status=status, code=code, type=etype, retry_after=retry_after, body=body)
+    if status == 401:
+        return AuthenticationError(message, **kw)
+    if status == 403:
+        return PermissionDeniedError(message, **kw)
+    if status == 404:
+        return NotFoundError(message, **kw)
+    if status == 402:
+        return InsufficientCreditsError(message, **kw)
+    if status == 429:
+        if code in ("concurrency_limit", "token_session_limit"):
+            return ConcurrencyLimitError(message, **kw)
+        if code == "host_capacity":
+            return HostCapacityError(message, **kw)
+        return RateLimitError(message, **kw)
+    if code == "pricing_unavailable":
+        return PricingUnavailableError(message, **kw)
+    if 400 <= status < 500:
+        return InvalidRequestError(message, **kw)
+    return UpstreamError(message, **kw)
+
+
+class VideoGenerationError(LiveVideoError):
+    """Raised by `VideoJob.wait()` when a `/v1/videos` job ends in a failed state."""

videorouter_live/_session.py

@@ -0,0 +1,295 @@
+"""`LiveSession` (sync) and `AsyncLiveSession`: one live-video session. Mirrors the shape of Reactor's client
+(`status`, `session_id`, `on/off/once`, `last_error`) on top of videorouter's broker model — the SDK never touches
+media; `connect` is handed to the host's own SDK."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import threading
+import time
+from typing import Any, Callable, Optional
+
+from ._errors import AuthenticationError, LiveVideoError, NotFoundError, SessionStateError, TimeoutError
+from ._types import Connect, Status
+
+EVENTS = ("status_changed", "ended", "heartbeat", "error")
+
+
+class _Emitter:
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[tuple[Callable, bool]]] = {}
+
+    def on(self, event: str, handler: Callable) -> None:
+        self._add(event, handler, False)
+
+    def once(self, event: str, handler: Callable) -> None:
+        self._add(event, handler, True)
+
+    def off(self, event: str, handler: Callable) -> None:
+        self._handlers[event] = [(h, o) for h, o in self._handlers.get(event, []) if h is not handler]
+
+    def _add(self, event: str, handler: Callable, once: bool) -> None:
+        if event not in EVENTS:
+            raise ValueError(f"unknown event {event!r} (events: {', '.join(EVENTS)})")
+        self._handlers.setdefault(event, []).append((handler, once))
+
+    def _emit(self, event: str, *args: Any) -> None:
+        for handler, once in list(self._handlers.get(event, [])):
+            if once:
+                self.off(event, handler)
+            try:
+                result = handler(*args)
+                if inspect.isawaitable(result):
+                    try:
+                        asyncio.get_running_loop().create_task(result)  # type: ignore[arg-type]
+                    except RuntimeError:
+                        pass
+            except Exception:  # noqa: BLE001 — a user handler must never break the SDK's own loop
+                pass
+
+
+class _SessionBase(_Emitter):
+    """State + events shared by the sync and async session. `raw` is always the last server response."""
+
+    def __init__(self, client: Any, data: dict) -> None:
+        super().__init__()
+        self._client = client
+        self._connect: Optional[Connect] = None
+        self._last_error: Optional[LiveVideoError] = None
+        self._raw: dict = {}
+        self._status: Status = Status("waiting")
+        self._apply(data, emit=False)
+
+    # ── state (Reactor-style getters) ────────────────────────────────────────────────────────────────────────
+    @property
+    def id(self) -> str:
+        return self._raw["id"]
+
+    session_id = id
+
+    @property
+    def model(self) -> str:
+        return self._raw["model"]
+
+    @property
+    def status(self) -> Status:
+        return self._status
+
+    def get_status(self) -> Status:
+        return self._status
+
+    @property
+    def connect(self) -> Optional[Connect]:
+        """Host credentials. Returned by the server ONCE (on the response that minted them) and kept here for the life
+        of this object; `None` while `waiting` and for a session re-fetched with `get_session`."""
+        return self._connect
+
+    @property
+    def world_id(self) -> Optional[str]:
+        return self._raw.get("world_id")
+
+    @property
+    def billed_seconds(self) -> Optional[float]:
+        return self._raw.get("billed_seconds")
+
+    @property
+    def cost_usd(self) -> Optional[float]:
+        return self._raw.get("cost_usd")
+
+    @property
+    def end_reason(self) -> Optional[str]:
+        return self._raw.get("end_reason")
+
+    @property
+    def recording_url(self) -> Optional[str]:
+        return self._raw.get("recording_url")
+
+    @property
+    def expires_at(self) -> Optional[str]:
+        return self._raw.get("expires_at")
+
+    @property
+    def heartbeat_interval_seconds(self) -> float:
+        return float(self._raw.get("heartbeat_interval_seconds") or 5)
+
+    @property
+    def raw(self) -> dict:
+        return dict(self._raw)
+
+    @property
+    def last_error(self) -> Optional[LiveVideoError]:
+        return self._last_error
+
+    def get_last_error(self) -> Optional[LiveVideoError]:
+        return self._last_error
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self._raw.get('id')} {self.model} {self._status}>"
+
+    # ── internals ────────────────────────────────────────────────────────────────────────────────────────────
+    def _apply(self, data: dict, emit: bool = True) -> None:
+        previous = self._status
+        self._raw = {**self._raw, **{k: v for k, v in data.items() if k != "connect"}}
+        if data.get("connect"):
+            self._connect = data["connect"]
+        self._status = Status(self._raw.get("status", "waiting"))
+        if emit and self._status != previous:
+            self._emit("status_changed", self._status)
+            if self._status == Status.ENDED:
+                self._emit("ended", self)
+
+    def _fail(self, exc: LiveVideoError) -> None:
+        self._last_error = exc
+        self._emit("error", exc)
+
+    def _require_open(self, what: str) -> None:
+        if self._status == Status.ENDED:
+            raise SessionStateError(f"cannot {what}: session {self.id} has ended ({self.end_reason})")
+
+
+class LiveSession(_SessionBase):
+    """Synchronous session. Heartbeats run on a daemon thread."""
+
+    def __init__(self, client: Any, data: dict) -> None:
+        super().__init__(client, data)
+        self._hb_thread: Optional[threading.Thread] = None
+        self._hb_stop = threading.Event()
+
+    def refresh(self) -> "LiveSession":
+        """Re-read the session. For a `waiting` session this also advances it: the call that sees the world finish
+        building mints the host credentials and returns them (then available as `.connect`)."""
+        self._apply(self._client._request("GET", f"/live-video/sessions/{self.id}", retry=True))
+        return self
+
+    def wait_until_ready(self, timeout: float = 300.0, poll_interval: float = 4.0) -> "LiveSession":
+        deadline = time.monotonic() + timeout
+        while self._status == Status.WAITING:
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"session {self.id} was still waiting after {timeout:g}s")
+            time.sleep(poll_interval)
+            self.refresh()
+        if self._status == Status.ENDED:
+            raise SessionStateError(f"session {self.id} ended while waiting ({self.end_reason})")
+        return self
+
+    def heartbeat(self) -> "LiveSession":
+        self._require_open("heartbeat")
+        self._apply(self._client._request("POST", f"/live-video/sessions/{self.id}/heartbeat", retry=True))
+        self._emit("heartbeat", self)
+        return self
+
+    def start_heartbeat(self, interval: Optional[float] = None) -> None:
+        """Beat in the background every `interval` seconds (default: the server's `heartbeat_interval_seconds`, 5 s)."""
+        if self._hb_thread and self._hb_thread.is_alive():
+            return
+        every = interval or self.heartbeat_interval_seconds
+        self._hb_stop.clear()
+
+        def loop() -> None:
+            while not self._hb_stop.wait(every):
+                if self._status == Status.ENDED:
+                    return
+                try:
+                    self.heartbeat()
+                except (NotFoundError, AuthenticationError, SessionStateError) as exc:
+                    self._fail(exc)
+                    return
+                except LiveVideoError as exc:   # transient: keep beating, surface it
+                    self._fail(exc)
+
+        self._hb_thread = threading.Thread(target=loop, name=f"live-video-heartbeat-{self.id}", daemon=True)
+        self._hb_thread.start()
+
+    def stop_heartbeat(self) -> None:
+        self._hb_stop.set()
+        t = self._hb_thread
+        if t and t.is_alive() and t is not threading.current_thread():
+            t.join(timeout=2)
+        self._hb_thread = None
+
+    def end(self, host_travel_id: Optional[str] = None) -> "LiveSession":
+        """Settle the session now. Safe to call twice. `host_travel_id` (Happy Oyster) lets the server bill on the host's
+        authoritative duration and fetch the replay."""
+        self.stop_heartbeat()
+        if self._status != Status.ENDED:
+            body = {"host_travel_id": host_travel_id} if host_travel_id else None
+            self._apply(self._client._request("POST", f"/live-video/sessions/{self.id}/end", json=body, retry=True))
+        return self
+
+    def __enter__(self) -> "LiveSession":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.end()
+
+
+class AsyncLiveSession(_SessionBase):
+    """Asyncio session. Heartbeats run as a background task."""
+
+    def __init__(self, client: Any, data: dict) -> None:
+        super().__init__(client, data)
+        self._hb_task: Optional["asyncio.Task[None]"] = None
+
+    async def refresh(self) -> "AsyncLiveSession":
+        self._apply(await self._client._request("GET", f"/live-video/sessions/{self.id}", retry=True))
+        return self
+
+    async def wait_until_ready(self, timeout: float = 300.0, poll_interval: float = 4.0) -> "AsyncLiveSession":
+        deadline = time.monotonic() + timeout
+        while self._status == Status.WAITING:
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"session {self.id} was still waiting after {timeout:g}s")
+            await asyncio.sleep(poll_interval)
+            await self.refresh()
+        if self._status == Status.ENDED:
+            raise SessionStateError(f"session {self.id} ended while waiting ({self.end_reason})")
+        return self
+
+    async def heartbeat(self) -> "AsyncLiveSession":
+        self._require_open("heartbeat")
+        self._apply(await self._client._request("POST", f"/live-video/sessions/{self.id}/heartbeat", retry=True))
+        self._emit("heartbeat", self)
+        return self
+
+    def start_heartbeat(self, interval: Optional[float] = None) -> None:
+        if self._hb_task and not self._hb_task.done():
+            return
+        every = interval or self.heartbeat_interval_seconds
+
+        async def loop() -> None:
+            while self._status != Status.ENDED:
+                await asyncio.sleep(every)
+                if self._status == Status.ENDED:
+                    return
+                try:
+                    await self.heartbeat()
+                except (NotFoundError, AuthenticationError, SessionStateError) as exc:
+                    self._fail(exc)
+                    return
+                except LiveVideoError as exc:
+                    self._fail(exc)
+
+        self._hb_task = asyncio.get_running_loop().create_task(loop())
+
+    async def stop_heartbeat(self) -> None:
+        task, self._hb_task = self._hb_task, None
+        if task and not task.done() and task is not asyncio.current_task():
+            task.cancel()
+            try:
+                await task
+            except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                pass
+
+    async def end(self, host_travel_id: Optional[str] = None) -> "AsyncLiveSession":
+        await self.stop_heartbeat()
+        if self._status != Status.ENDED:
+            body = {"host_travel_id": host_travel_id} if host_travel_id else None
+            self._apply(await self._client._request("POST", f"/live-video/sessions/{self.id}/end", json=body, retry=True))
+        return self
+
+    async def __aenter__(self) -> "AsyncLiveSession":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.end()

videorouter_live/_types.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+class Status(str):
+    """Session status. A `str` subclass, so `session.status == "ready"` works."""
+
+    WAITING = "waiting"   # the host is building a world; nothing is metered yet
+    READY = "ready"       # credentials issued; the meter is running
+    ENDED = "ended"       # settled
+
+
+Status.WAITING, Status.READY, Status.ENDED = Status("waiting"), Status("ready"), Status("ended")
+
+
+@dataclass(frozen=True)
+class Model:
+    id: str
+    kind: str                      # generate | world | avatar | edit
+    control: str                   # stream | actions
+    max_session_sec: int
+    available: bool                # False until the model has a verified price
+    price_per_second_usd: Optional[float]
+    price_per_hour_usd: Optional[float]
+    resolutions: tuple = ()
+    description: str = ""
+    speeds: tuple = ()
+    fast_price_per_second_usd: Optional[float] = None
+    raw: dict = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Model":
+        return cls(id=d["id"], kind=d.get("kind", ""), control=d.get("control", ""),
+                   max_session_sec=int(d.get("max_session_sec") or 0), available=bool(d.get("available")),
+                   price_per_second_usd=d.get("price_per_second_usd"), price_per_hour_usd=d.get("price_per_hour_usd"),
+                   resolutions=tuple(d.get("resolutions") or ()), description=d.get("description", ""),
+                   speeds=tuple(d.get("speeds") or ()), fast_price_per_second_usd=d.get("fast_price_per_second_usd"),
+                   raw=d)
+
+
+@dataclass(frozen=True)
+class Token:
+    """A short-lived credential for a browser. Mint it on YOUR server and hand `token` to the client SDK."""
+    token: str
+    expires_at: str
+    models: Optional[list] = None
+    max_sessions: Optional[int] = None
+    max_session_duration_seconds: Optional[int] = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Token":
+        return cls(token=d["token"], expires_at=d["expires_at"], models=d.get("models"),
+                   max_sessions=d.get("max_sessions"),
+                   max_session_duration_seconds=d.get("max_session_duration_seconds"))
+
+
+# `connect` is host-specific and handed to the HOST's own SDK; its shape per model family:
+#   Happy Oyster : {"ticket", "token", "api_base_url"}
+#   Odyssey      : {"session_id", "signaling_url", "session_token", "expires_in", "capabilities"}
+#   Decart Lucy  : {"api_key", "token", "base_url", "model", "expires_at", "max_session_duration_seconds"}
+Connect = dict[str, Any]

videorouter_live/_videos.py

@@ -0,0 +1,135 @@
+"""`client.videos` — the `/v1/videos` generation API (needs an API key; browser tokens are live-video only).
+
+Params are the API's own fields, passed through unchanged: `model`, `prompt`, `duration_secs`, `resolution`,
+`aspect_ratio`, `start_image_url`, ... See https://videorouter.sh/docs/video-generation.
+
+    job = lv.videos.generate({"model": "heygen-video-1", "prompt": "A presenter says: Welcome!", "duration_secs": 5})
+    print(job.url)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Optional
+
+from ._errors import LiveVideoError, TimeoutError, VideoGenerationError
+
+_DONE = ("completed", "succeeded")
+_FAILED = ("failed", "error", "cancelled")
+
+
+class _JobBase:
+    def __init__(self, videos: Any, data: Optional[dict]) -> None:
+        self._videos = videos
+        self.raw: dict = dict(data or {})
+
+    @property
+    def id(self) -> Optional[str]:
+        return self.raw.get("id")
+
+    @property
+    def status(self) -> str:
+        """"queued" | "processing" | "completed" | "failed" (a host may also report `succeeded` / `cancelled`)."""
+        return self.raw.get("status") or "queued"
+
+    @property
+    def done(self) -> bool:
+        return self.status in _DONE
+
+    @property
+    def failed(self) -> bool:
+        return self.status in _FAILED
+
+    @property
+    def urls(self) -> list:
+        """Every output URL (usually one). Empty until the job completes."""
+        return [d["url"] for d in (self.raw.get("data") or []) if isinstance(d, dict) and d.get("url")]
+
+    @property
+    def url(self) -> Optional[str]:
+        urls = self.urls
+        return urls[0] if urls else None
+
+    @property
+    def error(self) -> Optional[dict]:
+        return self.raw.get("error")
+
+    def _failure(self) -> VideoGenerationError:
+        e = self.error or {}
+        return VideoGenerationError(e.get("message") or f"video {self.id} {self.status}", code=e.get("code"),
+                                    type=e.get("type"), body=self.raw)
+
+    def __repr__(self) -> str:
+        return f"<VideoJob {self.id} {self.status}>"
+
+
+class VideoJob(_JobBase):
+    def refresh(self) -> "VideoJob":
+        self.raw = self._videos._get(self.id)
+        return self
+
+    def wait(self, timeout: float = 600.0, poll_interval: float = 5.0) -> "VideoJob":
+        """Poll until the job completes. Raises `VideoGenerationError` if it fails, `TimeoutError` if it runs out of time."""
+        deadline = time.monotonic() + timeout
+        while not self.done:
+            if self.failed:
+                raise self._failure()
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"video {self.id} was still {self.status} after {timeout}s")
+            time.sleep(poll_interval)
+            self.refresh()
+        return self
+
+
+class AsyncVideoJob(_JobBase):
+    async def refresh(self) -> "AsyncVideoJob":
+        self.raw = await self._videos._get(self.id)
+        return self
+
+    async def wait(self, timeout: float = 600.0, poll_interval: float = 5.0) -> "AsyncVideoJob":
+        deadline = time.monotonic() + timeout
+        while not self.done:
+            if self.failed:
+                raise self._failure()
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"video {self.id} was still {self.status} after {timeout}s")
+            await asyncio.sleep(poll_interval)
+            await self.refresh()
+        return self
+
+
+class Videos:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def create(self, params: dict) -> VideoJob:
+        """Submit a job. Never retried: a retried create could be billed twice."""
+        return VideoJob(self, self._client._request("POST", "/videos", json=params))
+
+    def get(self, video_id: str) -> VideoJob:
+        return VideoJob(self, self._get(video_id))
+
+    def generate(self, params: dict, *, timeout: float = 600.0, poll_interval: float = 5.0) -> VideoJob:
+        """Create and wait; returns the finished job (`job.url`)."""
+        return self.create(params).wait(timeout=timeout, poll_interval=poll_interval)
+
+    def _get(self, video_id: str) -> dict:
+        return self._client._request("GET", f"/videos/{video_id}", retry=True)
+
+
+class AsyncVideos:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    async def create(self, params: dict) -> AsyncVideoJob:
+        return AsyncVideoJob(self, await self._client._request("POST", "/videos", json=params))
+
+    async def get(self, video_id: str) -> AsyncVideoJob:
+        return AsyncVideoJob(self, await self._get(video_id))
+
+    async def generate(self, params: dict, *, timeout: float = 600.0, poll_interval: float = 5.0) -> AsyncVideoJob:
+        return await (await self.create(params)).wait(timeout=timeout, poll_interval=poll_interval)
+
+    async def _get(self, video_id: str) -> dict:
+        return await self._client._request("GET", f"/videos/{video_id}", retry=True)

videorouter_live-0.2.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: videorouter-live
+Version: 0.2.0
+Summary: Python SDK for videorouter.sh: live video & world models (open, keep alive, settle a real-time session) and the /v1/videos generation API.
+License: MIT
+Project-URL: Homepage, https://videorouter.sh/docs/live-video
+Keywords: videorouter,video,world-model,real-time,live-video,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# videorouter-live (Python)
+
+Python SDK for [videorouter.sh live video & world models](https://videorouter.sh/docs/live-video): open a real-time
+session, keep it alive, settle it. Sync (`LiveVideo`) and asyncio (`AsyncLiveVideo`) clients; only dependency is `httpx`.
+
+The SDK talks to the session **broker**. It never carries media: `session.connect` holds the host's short-lived
+credentials, which you hand to the host's own SDK (Happy Oyster, Odyssey, Decart...) in the browser.
+
+```python
+from videorouter_live import LiveVideo
+
+lv = LiveVideo(api_key="llmr_sk_...")            # or set VIDEOROUTER_API_KEY
+
+with lv.session("fal/happy-oyster-adventure", max_duration_seconds=60,
+                options={"world": {"prompt": "a rainy cyberpunk city", "perspective": "first_person"}}) as s:
+    send_to_browser(s.connect)    # host credentials — returned once by the server
+    ...                           # heartbeats run in the background; the session is settled on exit
+print(s.billed_seconds, s.cost_usd, s.end_reason)
+```
+
+`lv.session(...)` creates the session, waits until it is `ready` (a world may need ~30–120 s to build; nothing is
+metered while `waiting`), starts the heartbeat and settles it on exit even if your code raised.
+
+## Browser tokens
+
+Never put your key in a browser. Mint a short-lived, live-video-only token on your server:
+
+```python
+token = lv.create_token(models=["fal/happy-oyster-adventure"], expires_in=300,
+                        max_sessions=1, max_session_duration_seconds=60)
+# hand token.token to the browser SDK:  new LiveVideo({ token })
+```
+
+A token can only call `/v1/live-video` session endpoints — not billable endpoints, and not `create_token`.
+
+## Generating videos
+
+Both clients also wrap `/v1/videos` (API key required; browser tokens are live-video only). Creating a job is never retried.
+
+```python
+lv = LiveVideo()                                   # reads VIDEOROUTER_API_KEY
+job = lv.videos.generate({"model": "heygen-video-1", "prompt": "A presenter says: Welcome!", "duration_secs": 5})
+print(job.url)
+
+queued = lv.videos.create({"model": "wan-3.0-prime", "prompt": "..."})
+queued.wait(timeout=600)                           # raises VideoGenerationError / TimeoutError
+```
+
+`job.status`, `.done`, `.failed`, `.url` / `.urls`, `.error`, `.raw`, `.refresh()`, `.wait(timeout, poll_interval)`;
+`AsyncLiveVideo` has the same surface as coroutines.
+
+## API
+
+| | |
+|---|---|
+| `LiveVideo(api_key=None, *, token=None, base_url=..., timeout=30, max_retries=2, http_client=None)` | `AsyncLiveVideo` has the same signature |
+| `lv.models()` | `list[Model]` — `available` is `False` until a model has a verified price |
+| `lv.create_token(*, models, expires_in, max_sessions, max_session_duration_seconds)` | `Token` |
+| `lv.create_session(model, *, max_duration_seconds, options)` | `LiveSession` |
+| `lv.get_session(id)` | `LiveSession` (never has `connect` — it is returned once) |
+| `lv.session(model, ..., wait_until_ready=True, auto_heartbeat=True)` | context manager |
+
+`LiveSession` (and `AsyncLiveSession`, where the network methods are coroutines), modelled on Reactor's client:
+
+| | |
+|---|---|
+| `.id` / `.session_id`, `.model`, `.status`, `.get_status()` | `Status` is a `str` subclass: `"waiting"`, `"ready"`, `"ended"` |
+| `.connect` | host credentials, or `None` |
+| `.billed_seconds`, `.cost_usd`, `.end_reason`, `.recording_url`, `.world_id`, `.raw` | |
+| `.refresh()` | re-read; advances a `waiting` session and returns `connect` when the world is ready |
+| `.wait_until_ready(timeout=300, poll_interval=4)` | raises `TimeoutError` / `SessionStateError` |
+| `.heartbeat()`, `.start_heartbeat(interval=None)`, `.stop_heartbeat()` | default interval is the server's 5 s |
+| `.end(host_travel_id=None)` | settle; safe to call twice |
+| `.on(event, fn)`, `.once(...)`, `.off(...)` | events: `status_changed`, `ended`, `heartbeat`, `error` |
+| `.last_error` / `.get_last_error()` | last background-heartbeat error |
+
+### Errors
+
+Every failure raises a `LiveVideoError` subclass carrying `status`, `code`, `type`, `retry_after`:
+`AuthenticationError` (401), `PermissionDeniedError` (403), `InvalidRequestError` (400),
+`InsufficientCreditsError` (402), `PricingUnavailableError` (502), `NotFoundError` (404),
+`RateLimitError` (429) → `ConcurrencyLimitError` / `HostCapacityError`, `UpstreamError` (5xx), plus
+`SessionStateError` and `TimeoutError` raised locally.
+
+### Retries
+
+GETs, heartbeats and `end` are retried on network errors and 502/503/504. **Creating a session or a token is never
+retried** — a retried create could open a second billed session.
+
+## Billing in one paragraph
+
+Opening a session holds `max_duration_seconds × price` against your credits; ending it debits the real cost
+(whole seconds, at least the host's own reported duration) and releases the rest. A session that never became ready
+costs nothing. If the heartbeat stops, the server settles the session itself — a forgotten tab costs at most the
+silence window.

videorouter_live-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+videorouter_live/__init__.py,sha256=vofWlyLlkxFXLf2zj8KHHTl6WEh9ODKLzIKzuwlfcjs,1498
+videorouter_live/_client.py,sha256=3iouDC6xtSySq7UQYd5bn_syHbkDBYUfwmN6kXeM0Bs,12089
+videorouter_live/_errors.py,sha256=k_p2zxGX_ExKBehVOT22ThnulYgtfvhaDzkJN117ZGQ,4160
+videorouter_live/_session.py,sha256=RYmGfKRWGpSNe6onSDardOuwsfaqBKfRjckChnSl7J8,11867
+videorouter_live/_types.py,sha256=WMPGQDU7f5B2FDrImViIjXl0vLYoc8t5f3lUfAXS8tE,2666
+videorouter_live/_videos.py,sha256=s84zMMtssrx6IJ3qwnI1rkjGCXvcDGBNDcR2vwkWgrs,4947
+videorouter_live/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+videorouter_live-0.2.0.dist-info/licenses/LICENSE,sha256=77GQ3aAhJiYTeh2sa0vlJANI_9CPVUigSvKG6eyngY8,1068
+videorouter_live-0.2.0.dist-info/METADATA,sha256=FiqUg6k_9AlUWTNXeDrBd_YBVANGGy2idoHTfo__2os,5627
+videorouter_live-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+videorouter_live-0.2.0.dist-info/top_level.txt,sha256=4RlIubOLiZNqiZ0Xb67SLpVZYReFHi-K-5t-LWiEOeI,17
+videorouter_live-0.2.0.dist-info/RECORD,,

videorouter_live-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

videorouter_live-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Synvia Corp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

videorouter_live-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+videorouter_live