heroshots 0.2.2__tar.gz

heroshots-0.2.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,87 @@
+# 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/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "heroshots"
+version = "0.2.2"
+description = "Official Python SDK for the HeroShots / StudioHero platform (JWT auth)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "HeroShots" }]
+dependencies = ["requests>=2.28"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "responses>=0.23"]
+
+[project.urls]
+Homepage = "https://heroshots.ai"
+Repository = "https://github.com/JasonPriore/HeroShotsSDK-Python"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

heroshots-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heroshots-0.2.2/src/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-0.2.2/src/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-0.2.2/src/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}