heroshots 0.2.2__py3-none-any.whl

heroshots/__init__.py

@@ -0,0 +1,48 @@
+"""HeroShots SDK - high-level Python client for the StudioHero platform (JWT auth)."""
+
+from __future__ import annotations
+
+from .client import HeroShotsClient
+from .errors import (
+    ApiError,
+    AuthError,
+    ConflictError,
+    ForbiddenError,
+    HeroShotsError,
+    InternalError,
+    NotFoundError,
+    PayloadTooLargeError,
+    ProviderError,
+    QuotaExceededError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TokenExpiredError,
+    ValidationError,
+)
+from ._polling import TimeoutError as PollTimeoutError
+
+__version__ = "0.2.2"
+
+# Friendly alias.
+Client = HeroShotsClient
+
+__all__ = [
+    "Client",
+    "HeroShotsClient",
+    "HeroShotsError",
+    "ApiError",
+    "AuthError",
+    "TokenExpiredError",
+    "ValidationError",
+    "NotFoundError",
+    "ForbiddenError",
+    "ConflictError",
+    "QuotaExceededError",
+    "PayloadTooLargeError",
+    "ProviderError",
+    "ServiceUnavailableError",
+    "RateLimitError",
+    "InternalError",
+    "PollTimeoutError",
+    "__version__",
+]

heroshots/_polling.py

@@ -0,0 +1,66 @@
+"""Generic async-job polling helper.
+
+The backend has three async surfaces with **inconsistent** terminal-state names:
+
+* storyboard jobs and long-video jobs:  success = ``done``,       fail = ``failed``
+* single video / image status:          success = ``succeeded``,  fail = ``failed``
+
+Each resource passes the right state sets to :func:`wait`.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Iterable, Optional
+
+from .errors import ProviderError, HeroShotsError
+
+
+class TimeoutError(HeroShotsError):
+    """Polling exceeded the allotted timeout."""
+
+
+# Default terminal states, lower-cased for comparison.
+STORYBOARD_OK = ("done", "succeeded", "completed")
+STORYBOARD_FAIL = ("failed", "error", "cancelled", "canceled")
+MEDIA_OK = ("succeeded", "done", "completed")
+MEDIA_FAIL = ("failed", "error", "cancelled", "canceled")
+
+
+def wait(
+    get_fn: Callable[[], dict[str, Any]],
+    *,
+    terminal_ok: Iterable[str] = STORYBOARD_OK,
+    terminal_fail: Iterable[str] = STORYBOARD_FAIL,
+    status_key: str = "status",
+    interval: float = 3.0,
+    timeout: float = 600.0,
+    on_progress: Optional[Callable[[dict[str, Any]], None]] = None,
+) -> dict[str, Any]:
+    """Poll ``get_fn`` until the job reaches a terminal state.
+
+    Returns the final status payload on success. Raises :class:`ProviderError`
+    on a failed job and :class:`TimeoutError` if the deadline passes.
+    """
+    ok = {s.lower() for s in terminal_ok}
+    fail = {s.lower() for s in terminal_fail}
+    deadline = time.monotonic() + timeout
+    while True:
+        payload = get_fn()
+        if on_progress is not None:
+            on_progress(payload)
+        status = str(payload.get(status_key) or "").lower()
+        if status in ok:
+            return payload
+        if status in fail:
+            err = payload.get("error") or {}
+            if isinstance(err, dict):
+                raise ProviderError(
+                    err.get("message") or f"job {status}",
+                    code=err.get("code") or "provider_error",
+                    details=err if err else None,
+                )
+            raise ProviderError(str(err) or f"job {status}", code="provider_error")
+        if time.monotonic() >= deadline:
+            raise TimeoutError(f"job did not finish within {timeout:.0f}s (last status={status!r})")
+        time.sleep(interval)

heroshots/client.py

@@ -0,0 +1,205 @@
+"""HeroShots API client.
+
+Authenticates with a **portal JWT** (``Authorization: Bearer <token>``). The token
+is obtained from ``POST /api/auth/login`` (HS256, 7-day TTL, no refresh endpoint -
+re-login to renew). The client transparently handles the two response envelope
+styles used by the backend:
+
+* ``/api/v1/*``        -> ``{"success", "data", "meta"}`` -> unwrapped to ``data``
+* everything else      -> bare JSON, returned as-is
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, BinaryIO, Optional
+
+import requests
+
+from .errors import error_from_response, TokenExpiredError
+from .models import wrap
+from .resources.avatars import Avatars
+from .resources.images import Images
+from .resources.longvideo import LongVideo
+from .resources.stilllife import StillLife
+from .resources.storyboard import Storyboard
+from .resources.uploads import Uploads
+from .resources.videos import Videos
+
+DEFAULT_TIMEOUT = 120.0
+DEFAULT_BASE_URL = "https://app.heroshots.ai"
+
+
+class HeroShotsClient:
+    """Entry point for the HeroShots API.
+
+    Example::
+
+        client = HeroShotsClient.from_login("dev@partner.com", "...")
+        client.storyboard.brief_suggestions(product_image_url="https://.../p.jpg")
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        token: Optional[str] = None,
+        *,
+        email: Optional[str] = None,
+        password: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+        auto_relogin: bool = True,
+    ) -> None:
+        base_url = base_url or os.environ.get("HEROSHOTS_BASE_URL") or DEFAULT_BASE_URL
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self._email = email
+        self._password = password
+        self._auto_relogin = auto_relogin
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+        # Resource namespaces.
+        self.avatars = Avatars(self)
+        self.images = Images(self)
+        self.longvideo = LongVideo(self)
+        self.stilllife = StillLife(self)
+        self.storyboard = Storyboard(self)
+        self.uploads = Uploads(self)
+        self.videos = Videos(self)
+
+    # -- construction helpers -------------------------------------------------
+
+    @classmethod
+    def from_login(
+        cls,
+        email: str,
+        password: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        auto_relogin: bool = True,
+    ) -> "HeroShotsClient":
+        """Create a client and log in with email/password in one step.
+
+        ``base_url`` defaults to https://app.heroshots.ai.
+        """
+        client = cls(
+            base_url,
+            email=email,
+            password=password,
+            timeout=timeout,
+            auto_relogin=auto_relogin,
+        )
+        client.login(email, password)
+        return client
+
+    # -- auth -----------------------------------------------------------------
+
+    def login(self, email: str, password: str) -> dict[str, Any]:
+        """POST /api/auth/login -> stores and returns the JWT + profile."""
+        data = self.request(
+            "POST",
+            "/api/auth/login",
+            json={"email": email, "password": password},
+            auth=False,
+        )
+        self.token = data.get("token")
+        self._email, self._password = email, password
+        return data
+
+    def me(self) -> dict[str, Any]:
+        """GET /api/auth/me -> current authenticated profile."""
+        return self.request("GET", "/api/auth/me")
+
+    def balance(self) -> dict[str, Any]:
+        """GET /api/auth/stats -> account balance.
+
+        Includes ``hs_credits``, ``total_credits_used`` and ``plan.wallet_balance``.
+        """
+        return self.request("GET", "/api/auth/stats")
+
+    # -- transport ------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        files: Optional[dict[str, Any]] = None,
+        data: Optional[dict[str, Any]] = None,
+        auth: bool = True,
+        unwrap: Optional[bool] = None,
+        _retried: bool = False,
+    ) -> Any:
+        """Perform an HTTP request and return decoded JSON (or raise ``ApiError``).
+
+        ``unwrap`` controls envelope handling; when ``None`` it is inferred from the
+        path (``/api/v1/*`` responses are wrapped in ``{"success","data","meta"}``).
+        """
+        url = self.base_url + path
+        headers: dict[str, str] = {}
+        if auth and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        resp = self.session.request(
+            method.upper(),
+            url,
+            headers=headers,
+            json=json,
+            params=params,
+            files=files,
+            data=data,
+            timeout=self.timeout,
+        )
+
+        body: Any = None
+        if resp.content:
+            try:
+                body = resp.json()
+            except ValueError:
+                body = None
+
+        if not resp.ok:
+            err = error_from_response(resp.status_code, body)
+            # One automatic re-login attempt on an expired token.
+            if (
+                isinstance(err, TokenExpiredError)
+                and self._auto_relogin
+                and not _retried
+                and self._email
+                and self._password
+            ):
+                self.login(self._email, self._password)
+                return self.request(
+                    method,
+                    path,
+                    json=json,
+                    params=params,
+                    files=files,
+                    data=data,
+                    auth=auth,
+                    unwrap=unwrap,
+                    _retried=True,
+                )
+            raise err
+
+        if unwrap is None:
+            unwrap = path.startswith("/api/v1/")
+        if unwrap and isinstance(body, dict) and "data" in body:
+            data_part = body.get("data")
+            meta = body.get("meta")
+            if isinstance(data_part, dict) and meta is not None:
+                # Surface billing/credits metadata without losing the typed shape.
+                data_part.setdefault("_meta", meta)
+            return wrap(data_part)
+        return wrap(body)
+
+    @staticmethod
+    def _multipart_file(file: "str | BinaryIO", field: str = "file") -> dict[str, Any]:
+        """Build a ``files=`` dict for ``requests`` from a path or open file object."""
+        if isinstance(file, str):
+            return {field: open(file, "rb")}  # noqa: SIM115 - requests closes it
+        return {field: file}

heroshots/errors.py

@@ -0,0 +1,153 @@
+"""Exception hierarchy for the HeroShots SDK.
+
+Every structured API error returns ``{"success": false, "error": {"code", "message",
+"details"}}`` (see backend ``api_error_response.py``). :func:`error_from_response`
+maps the ``code`` to a specific exception class so callers can ``except`` precisely.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class HeroShotsError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class ApiError(HeroShotsError):
+    """An error returned by the HeroShots API.
+
+    Attributes:
+        code: machine-readable error code (e.g. ``"validation_error"``).
+        message: human-readable message.
+        status: HTTP status code.
+        details: optional structured details dict.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: Optional[str] = None,
+        status: Optional[int] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.details = details or {}
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        prefix = f"[{self.status} {self.code}] " if self.code else ""
+        return f"{prefix}{self.message}"
+
+
+class AuthError(ApiError):
+    """Missing/invalid bearer token or unknown user."""
+
+
+class TokenExpiredError(AuthError):
+    """The portal JWT expired. There is no refresh endpoint - re-login to renew."""
+
+
+class ValidationError(ApiError):
+    """The request payload failed validation."""
+
+
+class NotFoundError(ApiError):
+    """The requested resource does not exist (or a job expired)."""
+
+
+class ForbiddenError(ApiError):
+    """Authenticated but not allowed (plan/scope/tenant gating)."""
+
+
+class ConflictError(ApiError):
+    """Resource conflict (e.g. email already registered)."""
+
+
+class QuotaExceededError(ApiError):
+    """Credit/quota limit reached."""
+
+
+class PayloadTooLargeError(ApiError):
+    """Uploaded payload exceeded the size limit."""
+
+
+class ProviderError(ApiError):
+    """An upstream generation provider failed (also raised for failed jobs)."""
+
+
+class ServiceUnavailableError(ApiError):
+    """A backend dependency is not configured or temporarily unavailable."""
+
+
+class RateLimitError(ApiError):
+    """HTTP 429 - too many requests. Back off and retry."""
+
+
+class InternalError(ApiError):
+    """Unexpected server error (HTTP 5xx)."""
+
+
+# code -> exception class. Codes mirror backend api_error_response.py CODE_* values.
+_CODE_MAP: dict[str, type[ApiError]] = {
+    "missing_api_key": AuthError,
+    "missing_authorization": AuthError,
+    "missing_bearer_token": AuthError,
+    "invalid_api_key": AuthError,
+    "invalid_token": AuthError,
+    "invalid_or_expired_token": AuthError,
+    "unauthorized": AuthError,
+    "user_not_found": AuthError,
+    "token_expired": TokenExpiredError,
+    "validation_error": ValidationError,
+    "not_found": NotFoundError,
+    "resource_gone": NotFoundError,
+    "forbidden": ForbiddenError,
+    "plan_not_allowed": ForbiddenError,
+    "insufficient_scope": ForbiddenError,
+    "conflict": ConflictError,
+    "quota_exceeded": QuotaExceededError,
+    "payload_too_large": PayloadTooLargeError,
+    "provider_error": ProviderError,
+    "service_unavailable": ServiceUnavailableError,
+    "pricing_not_configured": ServiceUnavailableError,
+    "stripe_not_configured": ServiceUnavailableError,
+    "internal_error": InternalError,
+}
+
+
+def error_from_response(status: int, body: Any) -> ApiError:
+    """Build the most specific :class:`ApiError` for an HTTP error response."""
+    code = None
+    message = None
+    details = None
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict):
+            code = err.get("code")
+            message = err.get("message")
+            details = err.get("details")
+        elif isinstance(err, str):
+            message = err
+        message = message or body.get("message")
+    if status == 429:
+        cls: type[ApiError] = RateLimitError
+    elif code and code in _CODE_MAP:
+        cls = _CODE_MAP[code]
+    elif status and status >= 500:
+        cls = InternalError
+    elif status == 404:
+        cls = NotFoundError
+    elif status in (401, 403):
+        cls = AuthError
+    else:
+        cls = ApiError
+    return cls(
+        message or f"HTTP {status}",
+        code=code,
+        status=status,
+        details=details if isinstance(details, dict) else None,
+    )

heroshots/models.py

@@ -0,0 +1,34 @@
+"""Lightweight response wrapper.
+
+The API returns plain JSON. :class:`AttrDict` wraps dict responses so callers can
+use either ``result["video_url"]`` or ``result.video_url`` and still treat the
+object as an ordinary dict. ``/api/v1`` billing metadata is exposed under ``_meta``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class AttrDict(dict):
+    """A dict that also supports attribute access (recursively)."""
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError as exc:  # pragma: no cover - mirrors AttributeError contract
+            raise AttributeError(name) from exc
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self[name] = value
+
+
+def wrap(value: Any) -> Any:
+    """Recursively wrap dicts (and dicts inside lists) as :class:`AttrDict`."""
+    if isinstance(value, AttrDict):
+        return value
+    if isinstance(value, dict):
+        return AttrDict({k: wrap(v) for k, v in value.items()})
+    if isinstance(value, list):
+        return [wrap(v) for v in value]
+    return value

heroshots/resources/__init__.py

@@ -0,0 +1,46 @@
+"""Resource namespaces for the HeroShots client."""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ..client import HeroShotsClient
+
+
+class Resource:
+    """Base class holding a back-reference to the client."""
+
+    def __init__(self, client: "HeroShotsClient") -> None:
+        self._client = client
+
+    # Convenience proxies so resource code stays terse.
+    def _get(self, path: str, **kw: Any) -> Any:
+        return self._client.request("GET", path, **kw)
+
+    def _post(self, path: str, **kw: Any) -> Any:
+        return self._client.request("POST", path, **kw)
+
+    def _patch(self, path: str, **kw: Any) -> Any:
+        return self._client.request("PATCH", path, **kw)
+
+    def _put(self, path: str, **kw: Any) -> Any:
+        return self._client.request("PUT", path, **kw)
+
+    def _delete(self, path: str, **kw: Any) -> Any:
+        return self._client.request("DELETE", path, **kw)
+
+    def _resolve_image(self, value: Optional[str], folder: str = "references") -> Optional[str]:
+        """If ``value`` is a local file path, upload it and return the hosted URL.
+
+        Pass-through for ``None`` and existing http(s) URLs. Lets every generation
+        method accept local paths anywhere a ``*_image_url`` is expected.
+        """
+        if not value:
+            return value
+        if value.startswith("http://") or value.startswith("https://"):
+            return value
+        if os.path.exists(value):
+            return self._client.uploads.image(value, folder=folder)["public_url"]
+        return value

heroshots/resources/avatars.py

@@ -0,0 +1,25 @@
+"""Avatars (JWT-or-API-key, /api/v1/avatar).
+
+Read-only listing of your own + default avatars, plus on-demand generation.
+(Editing/deleting avatars is intentionally not exposed.)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import Resource
+
+
+class Avatars(Resource):
+    def list(self, **params: Any) -> dict[str, Any]:
+        """GET /api/v1/avatar/list -> your own and the default avatars."""
+        return self._get("/api/v1/avatar/list", params=params or None)
+
+    def get(self, avatar_id: int) -> dict[str, Any]:
+        """GET /api/v1/avatar/<id>."""
+        return self._get(f"/api/v1/avatar/{avatar_id}")
+
+    def generate(self, **payload: Any) -> dict[str, Any]:
+        """POST /api/v1/avatar/generate -> request a new avatar."""
+        return self._post("/api/v1/avatar/generate", json=payload)

heroshots/resources/images.py

@@ -0,0 +1,74 @@
+"""Image generation (JWT-or-API-key on /api/v1, portal candidates flow)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import Resource
+from .. import _polling
+
+
+class Images(Resource):
+    def generate(
+        self,
+        product_image_url: str,
+        subject_image_url: Optional[str] = None,
+        **payload: Any,
+    ) -> dict[str, Any]:
+        """POST /api/v1/image/generate (async) -> ``{generation_id, status, ...}``.
+
+        Local file paths are auto-uploaded. Provide ``subject_image_url``/``avatar_id``
+        unless ``still_life=True``.
+        """
+        body = {
+            "product_image_url": self._resolve_image(product_image_url, "products"),
+            **payload,
+        }
+        if subject_image_url is not None:
+            body["subject_image_url"] = self._resolve_image(subject_image_url, "subjects")
+        return self._post("/api/v1/image/generate", json=body)
+
+    def candidates(
+        self,
+        product_image_url: str,
+        subject_image_url: Optional[str] = None,
+        **payload: Any,
+    ) -> dict[str, Any]:
+        """POST /api/auth/image/generate/candidates -> persistent candidate batch."""
+        body = {
+            "product_image_url": self._resolve_image(product_image_url, "products"),
+            **payload,
+        }
+        if subject_image_url is not None:
+            body["subject_image_url"] = self._resolve_image(subject_image_url, "subjects")
+        return self._post("/api/auth/image/generate/candidates", json=body)
+
+    def select_candidate(self, token: str, **payload: Any) -> dict[str, Any]:
+        """POST /api/auth/image/generate/candidates/<token>/select."""
+        return self._post(f"/api/auth/image/generate/candidates/{token}/select", json=payload)
+
+    def status(self, generation_id: str) -> dict[str, Any]:
+        """GET /api/v1/image/status/<generation_id>."""
+        return self._get(f"/api/v1/image/status/{generation_id}")
+
+    def download(self, log_id: str) -> dict[str, Any]:
+        """GET /api/v1/image/<log_id>/download."""
+        return self._get(f"/api/v1/image/{log_id}/download")
+
+    def wait(
+        self,
+        generation_id: str,
+        *,
+        interval: float = 3.0,
+        timeout: float = 600.0,
+        on_progress: Optional[Callable[[dict[str, Any]], None]] = None,
+    ) -> dict[str, Any]:
+        """Poll image status until ``succeeded``/``failed``."""
+        return _polling.wait(
+            lambda: self.status(generation_id),
+            terminal_ok=_polling.MEDIA_OK,
+            terminal_fail=_polling.MEDIA_FAIL,
+            interval=interval,
+            timeout=timeout,
+            on_progress=on_progress,
+        )

heroshots/resources/longvideo.py

@@ -0,0 +1,61 @@
+"""Long / multi-segment video pipeline (portal JWT, /api/auth/long-video)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import Resource
+from .. import _polling
+
+
+class LongVideo(Resource):
+    def start(
+        self,
+        image_url: Optional[str] = None,
+        *,
+        custom_prompt: Optional[str] = None,
+        storyboard: Optional[dict] = None,
+        ratio: str = "16:9",
+        resolution: str = "1080p",
+        **payload: Any,
+    ) -> dict[str, Any]:
+        """POST /api/auth/long-video/start -> ``{job_id, status, segment_count, ...}``.
+
+        Provide ``image_url`` (local paths auto-upload) or ``image_generation_id`` /
+        ``product_image_url`` + ``subject_image_url``. Pass a ``storyboard`` produced
+        by ``client.storyboard`` to drive a planned multi-segment render.
+        """
+        body: dict[str, Any] = {"ratio": ratio, "resolution": resolution, **payload}
+        if image_url is not None:
+            body["image_url"] = self._resolve_image(image_url, "products")
+        if custom_prompt is not None:
+            body["custom_prompt"] = custom_prompt
+        if storyboard is not None:
+            body["storyboard"] = storyboard
+        return self._post("/api/auth/long-video/start", json=body)
+
+    def status(self, job_id: int) -> dict[str, Any]:
+        """GET /api/auth/long-video/status/<job_id>."""
+        return self._get(f"/api/auth/long-video/status/{job_id}")
+
+    def view(self, token: str) -> dict[str, Any]:
+        """GET /api/auth/long-video/view/<token>."""
+        return self._get(f"/api/auth/long-video/view/{token}")
+
+    def wait(
+        self,
+        job_id: int,
+        *,
+        interval: float = 5.0,
+        timeout: float = 1800.0,
+        on_progress: Optional[Callable[[dict[str, Any]], None]] = None,
+    ) -> dict[str, Any]:
+        """Poll until ``done``/``failed`` -> payload with ``final_video_url``."""
+        return _polling.wait(
+            lambda: self.status(job_id),
+            terminal_ok=_polling.STORYBOARD_OK,
+            terminal_fail=_polling.STORYBOARD_FAIL,
+            interval=interval,
+            timeout=timeout,
+            on_progress=on_progress,
+        )

heroshots/resources/stilllife.py

@@ -0,0 +1,71 @@
+"""Still-life product video (portal JWT, /api/auth/stilllife-video)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import Resource
+from .. import _polling
+
+
+class StillLife(Resource):
+    def start(
+        self,
+        product_url: str,
+        background_url: str,
+        *,
+        custom_prompt: Optional[str] = None,
+        ratio: str = "16:9",
+        resolution: str = "1080p",
+        duration_seconds: int = 5,
+        **payload: Any,
+    ) -> dict[str, Any]:
+        """POST /api/auth/stilllife-video/start -> ``{task_id, status, ...}``.
+
+        ``product_url`` and ``background_url`` are required (local paths auto-upload).
+        """
+        body: dict[str, Any] = {
+            "product_url": self._resolve_image(product_url, "products"),
+            "background_url": self._resolve_image(background_url, "background"),
+            "ratio": ratio,
+            "resolution": resolution,
+            "duration_seconds": duration_seconds,
+            **payload,
+        }
+        if custom_prompt is not None:
+            body["custom_prompt"] = custom_prompt
+        return self._post("/api/auth/stilllife-video/start", json=body)
+
+    def status(self, task_id: str) -> dict[str, Any]:
+        """GET /api/auth/stilllife-video/status/<task_id>."""
+        return self._get(f"/api/auth/stilllife-video/status/{task_id}")
+
+    def wait(
+        self,
+        task_id: str,
+        *,
+        interval: float = 5.0,
+        timeout: float = 900.0,
+        on_progress: Optional[Callable[[dict[str, Any]], None]] = None,
+    ) -> dict[str, Any]:
+        """Poll until terminal -> payload with the finished video URL."""
+        return _polling.wait(
+            lambda: self.status(task_id),
+            terminal_ok=_polling.MEDIA_OK,
+            terminal_fail=_polling.MEDIA_FAIL,
+            interval=interval,
+            timeout=timeout,
+            on_progress=on_progress,
+        )
+
+    def preview_background(self, task_id: str, **payload: Any) -> dict[str, Any]:
+        """POST /api/auth/stilllife-video/<task_id>/preview-background."""
+        return self._post(f"/api/auth/stilllife-video/{task_id}/preview-background", json=payload)
+
+    def change_background(self, task_id: str, **payload: Any) -> dict[str, Any]:
+        """POST /api/auth/stilllife-video/<task_id>/change-background."""
+        return self._post(f"/api/auth/stilllife-video/{task_id}/change-background", json=payload)
+
+    def change_background_status(self, task_id: str) -> dict[str, Any]:
+        """GET /api/auth/stilllife-video/<task_id>/change-background/status."""
+        return self._get(f"/api/auth/stilllife-video/{task_id}/change-background/status")

heroshots/resources/storyboard.py

@@ -0,0 +1,158 @@
+"""StudioHero storyboard intelligence (portal JWT only).
+
+This is the creative brain the web app uses: brief suggestions -> selectable
+candidates -> full storyboard (async) -> deferred 4K reference frames (async) ->
+optional revision. Feed the resulting storyboard into ``client.longvideo.start``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import Resource
+from .. import _polling
+
+# Valid durations accepted by the backend storyboard endpoints.
+DURATIONS = (6, 8, 12, 15, 30, 45, 60)
+
+
+class Storyboard(Resource):
+    def brief_suggestions(
+        self,
+        product_image_url: Optional[str] = None,
+        subject_image_url: Optional[str] = None,
+        **payload: Any,
+    ) -> list[str]:
+        """POST /video/storyboard/brief-suggestions -> list of short brief strings."""
+        body = self._image_body(product_image_url, subject_image_url, payload)
+        resp = self._post("/video/storyboard/brief-suggestions", json=body)
+        return resp.get("suggestions", resp) if isinstance(resp, dict) else resp
+
+    def candidates(
+        self,
+        custom_prompt: str,
+        duration_seconds: int,
+        product_image_url: Optional[str] = None,
+        subject_image_url: Optional[str] = None,
+        *,
+        async_storyboard: bool = False,
+        **payload: Any,
+    ) -> Any:
+        """POST /video/storyboard/candidates -> selectable concept candidates.
+
+        Set ``async_storyboard=True`` to get a ``{job_id}`` instead (poll with
+        :meth:`wait`); otherwise returns the candidates inline.
+        """
+        body = self._image_body(product_image_url, subject_image_url, payload)
+        body.update(custom_prompt=custom_prompt, duration_seconds=duration_seconds)
+        if async_storyboard:
+            body["async_storyboard"] = True
+        resp = self._post("/video/storyboard/candidates", json=body)
+        if isinstance(resp, dict) and "candidates" in resp:
+            return resp["candidates"]
+        return resp
+
+    def generate(
+        self,
+        custom_prompt: str,
+        duration_seconds: int,
+        selected_candidate: Optional[dict] = None,
+        product_image_url: Optional[str] = None,
+        subject_image_url: Optional[str] = None,
+        *,
+        async_storyboard: bool = True,
+        defer_reference_frames: bool = True,
+        **payload: Any,
+    ) -> dict[str, Any]:
+        """POST /video/storyboard -> storyboard (async by default -> ``{job_id}``)."""
+        body = self._image_body(product_image_url, subject_image_url, payload)
+        body.update(
+            custom_prompt=custom_prompt,
+            duration_seconds=duration_seconds,
+            async_storyboard=async_storyboard,
+            defer_reference_frames=defer_reference_frames,
+        )
+        if selected_candidate is not None:
+            body["selected_candidate"] = selected_candidate
+        return self._post("/video/storyboard", json=body)
+
+    def frames(
+        self,
+        storyboard: dict,
+        product_image_url: Optional[str] = None,
+        subject_image_url: Optional[str] = None,
+        *,
+        async_storyboard: bool = True,
+        **payload: Any,
+    ) -> dict[str, Any]:
+        """POST /video/storyboard/frames -> renders deferred 4K reference frames."""
+        body = self._image_body(product_image_url, subject_image_url, payload)
+        body.update(storyboard=storyboard, async_storyboard=async_storyboard)
+        return self._post("/video/storyboard/frames", json=body)
+
+    def revise(self, revision_request: str, custom_prompt: str, duration_seconds: int,
+               storyboard: dict, **payload: Any) -> dict[str, Any]:
+        """POST /video/storyboard/revise -> revised storyboard."""
+        body = {
+            "revision_request": revision_request,
+            "custom_prompt": custom_prompt,
+            "duration_seconds": duration_seconds,
+            "storyboard": storyboard,
+            **payload,
+        }
+        return self._post("/video/storyboard/revise", json=body)
+
+    def status(self, job_id: str) -> dict[str, Any]:
+        """GET /video/storyboard/status/<job_id>."""
+        return self._get(f"/video/storyboard/status/{job_id}")
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        interval: float = 3.0,
+        timeout: float = 300.0,
+        on_progress: Optional[Callable[[dict[str, Any]], None]] = None,
+    ) -> dict[str, Any]:
+        """Poll a storyboard/frames job until ``done``/``failed``.
+
+        ``on_progress`` receives each status payload (storyboard frame jobs expose
+        ``frames_partial`` for progressive rendering).
+        """
+        return _polling.wait(
+            lambda: self.status(job_id),
+            terminal_ok=_polling.STORYBOARD_OK,
+            terminal_fail=_polling.STORYBOARD_FAIL,
+            interval=interval,
+            timeout=timeout,
+            on_progress=on_progress,
+        )
+
+    # -- creative helpers -----------------------------------------------------
+    def subject_measurements(self, **payload: Any) -> dict[str, Any]:
+        """POST /subject/estimate-measurements."""
+        return self._post("/subject/estimate-measurements", json=payload)
+
+    def analyze_product(self, **payload: Any) -> dict[str, Any]:
+        """POST /product/analyze."""
+        return self._post("/product/analyze", json=payload)
+
+    def creativity(self, **payload: Any) -> dict[str, Any]:
+        """POST /creativity/generate."""
+        return self._post("/creativity/generate", json=payload)
+
+    # -- internal -------------------------------------------------------------
+    def _image_body(
+        self,
+        product_image_url: Optional[str],
+        subject_image_url: Optional[str],
+        payload: dict[str, Any],
+    ) -> dict[str, Any]:
+        body = dict(payload)
+        if product_image_url is not None:
+            body["product_image_url"] = self._resolve_image(product_image_url, "products")
+        if subject_image_url is not None:
+            body["subject_image_url"] = self._resolve_image(subject_image_url, "subjects")
+        if "image_url" in body:
+            body["image_url"] = self._resolve_image(body["image_url"], "references")
+        return body

heroshots/resources/uploads.py

@@ -0,0 +1,30 @@
+"""File uploads -> hosted public URLs (portal JWT)."""
+
+from __future__ import annotations
+
+from typing import Any, BinaryIO, Optional
+
+from . import Resource
+
+# Allowed upload folders (backend frontend_uploads.py).
+FOLDERS = (
+    "subjects",
+    "products",
+    "avatars",
+    "avatar-consents",
+    "references",
+    "background",
+    "body_posture",
+    "reference-videos",
+)
+
+
+class Uploads(Resource):
+    def image(self, file: "str | BinaryIO", folder: Optional[str] = None) -> dict[str, Any]:
+        """POST /upload/image (multipart ``file``) -> ``{public_url, filename, folder}``.
+
+        ``folder`` must be one of :data:`FOLDERS` (or omitted).
+        """
+        files = self._client._multipart_file(file)
+        data = {"folder": folder} if folder else None
+        return self._post("/upload/image", files=files, data=data)

heroshots/resources/videos.py

@@ -0,0 +1,42 @@
+"""Short video generation (JWT-or-API-key on /api/v1; portal status poll)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Optional
+
+from . import Resource
+from .. import _polling
+
+
+class Videos(Resource):
+    def generate(self, image_url: Optional[str] = None, **payload: Any) -> dict[str, Any]:
+        """POST /api/v1/video/generate -> ``{task_id, status, ...}``.
+
+        Local file paths in ``image_url`` are auto-uploaded.
+        """
+        body = dict(payload)
+        if image_url is not None:
+            body["image_url"] = self._resolve_image(image_url, "products")
+        return self._post("/api/v1/video/generate", json=body)
+
+    def status(self, task_id: str) -> dict[str, Any]:
+        """GET /video/status/<task_id> (portal JWT) -> ``{task_id, status, video_url}``."""
+        return self._get(f"/video/status/{task_id}")
+
+    def wait(
+        self,
+        task_id: str,
+        *,
+        interval: float = 5.0,
+        timeout: float = 900.0,
+        on_progress: Optional[Callable[[dict[str, Any]], None]] = None,
+    ) -> dict[str, Any]:
+        """Poll video status until ``succeeded``/``failed`` -> payload with ``video_url``."""
+        return _polling.wait(
+            lambda: self.status(task_id),
+            terminal_ok=_polling.MEDIA_OK,
+            terminal_fail=_polling.MEDIA_FAIL,
+            interval=interval,
+            timeout=timeout,
+            on_progress=on_progress,
+        )

heroshots-0.2.2.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: heroshots
+Version: 0.2.2
+Summary: Official Python SDK for the HeroShots / StudioHero platform (JWT auth).
+Author: HeroShots
+License-Expression: MIT
+Project-URL: Homepage, https://heroshots.ai
+Project-URL: Repository, https://github.com/JasonPriore/HeroShotsSDK-Python
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# heroshots (Python SDK)
+
+High-level Python client for the HeroShots / StudioHero platform, authenticated
+with a **portal JWT**. Covers the full JWT-reachable API surface.
+
+## Install
+
+```bash
+pip install heroshots          # from a registry
+pip install -e ".[dev]"        # local dev (runs the test suite)
+```
+
+Requires Python 3.9+. Only runtime dependency: `requests`.
+
+## Authenticate
+
+```python
+from heroshots import Client
+
+# Email/password login (recommended): stores the JWT, auto re-logins on expiry.
+# Base URL defaults to https://app.heroshots.ai.
+client = Client.from_login("dev@partner.com", "secret")
+
+# Or reuse an existing token.
+client = Client(token="eyJ...")
+```
+
+## Usage
+
+```python
+# Local file paths are auto-uploaded to hosted URLs.
+briefs = client.storyboard.brief_suggestions(
+    product_image_url="product.jpg", subject_image_url="model.jpg",
+    duration_seconds=30, language_code="it",
+)
+
+candidates = client.storyboard.candidates(
+    custom_prompt=briefs[0], duration_seconds=30,
+    product_image_url="product.jpg", subject_image_url="model.jpg",
+)
+
+job = client.storyboard.generate(
+    custom_prompt=briefs[0], duration_seconds=30, selected_candidate=candidates[0],
+    product_image_url="product.jpg", subject_image_url="model.jpg",
+)
+sb = client.storyboard.wait(job["job_id"])           # polls until done/failed
+
+vjob = client.longvideo.start(image_url="product.jpg", storyboard=sb["storyboard"])
+final = client.longvideo.wait(vjob["job_id"])
+print(final["final_video_url"])                       # also: final.final_video_url
+```
+
+Responses support both `result["key"]` and `result.key` access. `/api/v1`
+billing metadata is under `result["_meta"]`.
+
+## Resources
+
+`uploads` · `images` · `videos` · `longvideo` · `stilllife` · `storyboard` ·
+`avatars`
+
+Plus on the client: `login()`, `me()`, `balance()`.
+
+Every method maps 1:1 to an endpoint; pass extra backend fields as keyword
+arguments (they are forwarded verbatim).
+
+## Errors
+
+```python
+from heroshots import ValidationError, TokenExpiredError, RateLimitError
+
+try:
+    client.storyboard.candidates(custom_prompt="", duration_seconds=30,
+                                 product_image_url="p.jpg")
+except ValidationError as e:
+    print(e.code, e.message, e.details)
+```
+
+## Test
+
+```bash
+pytest          # offline, mocked HTTP
+```
+
+## Billing
+
+Generations cost credits. Check remaining credits with `client.balance()`
+(`hs_credits` + `plan.wallet_balance`). See `examples/full_storyboard_flow.py`.

heroshots-0.2.2.dist-info/RECORD

@@ -0,0 +1,18 @@
+heroshots/__init__.py,sha256=KIkIZOdOao0abY5T2aEdZCRjvwwvASlAPENfygDKLJg,1005
+heroshots/_polling.py,sha256=RFBo3aaEBfzWgnQjxaTUTs2GICMhCYA5dgM0r_VyRdU,2370
+heroshots/client.py,sha256=C8Sn7t27jxQ3bexFe5p4U_rWGrSRR7XKjs_jspbzF6g,6767
+heroshots/errors.py,sha256=HYvGyUGaRn5IXmYmwDmqLIB00lnahShV2boeLKkNj84,4524
+heroshots/models.py,sha256=1MKIIZweqwa4GzlBjU8iD13-ibxmHaw5IJS_6IGeWD8,1098
+heroshots/resources/__init__.py,sha256=GQ-_87vMPoyONcJMRYI34rouFJ5Ks0ybzlQrXHcOSV8,1621
+heroshots/resources/avatars.py,sha256=H002S1IkRZHqtUoABlRq8T_zBGqDakwkPThNqaHI6nw,836
+heroshots/resources/images.py,sha256=DuPLltDzb-blfdJV0bX0StnAz8JHqZM66MTz2ZsdBnQ,2702
+heroshots/resources/longvideo.py,sha256=s-IU6M53_OH0pguwAjW2XizNz3JFvt3lfZbiiAh8t8g,2216
+heroshots/resources/stilllife.py,sha256=H7TquATf4TfzYXk8vfASA3Ej5ye6H5eKFrraQwRLJ1I,2700
+heroshots/resources/storyboard.py,sha256=f6PT234u2RKUH3vQLfQHiwnjxpw98LNFEXS0QAkVetU,6209
+heroshots/resources/uploads.py,sha256=rcSqx4dwc0g1tzs7v2W8s14jfkcOl7x-c9dYxCZhJ9w,839
+heroshots/resources/videos.py,sha256=S-aJ_58BXcFMCgteWa358MP1G-UvYDJe6eG8cVmU4zo,1453
+heroshots-0.2.2.dist-info/licenses/LICENSE,sha256=ZW7TmjdKjIlHN4RDzJIerL-ik9dg0MvcUQ43keMA024,1069
+heroshots-0.2.2.dist-info/METADATA,sha256=VGhNS3tVF1HuZeXosuydsUqfuyKEoZbmiY0qEQr9VMs,3041
+heroshots-0.2.2.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+heroshots-0.2.2.dist-info/top_level.txt,sha256=bbmXrf-MXXJ0q7jUR8C0rWtUmC-KIBECToHCGSqNY3o,10
+heroshots-0.2.2.dist-info/RECORD,,

heroshots-0.2.2.dist-info/WHEEL

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

heroshots-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Priore
+
+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.

heroshots-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+heroshots