renderly-ai 0.2.0__tar.gz

renderly_ai-0.2.0/LICENSE

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

renderly_ai-0.2.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: renderly-ai
+Version: 0.2.0
+Summary: Official client for the Renderly AI API: search models, price, create and download image, video, audio and language results with one key and one credit wallet.
+Author: Renderly
+License: MIT
+Project-URL: Homepage, https://renderly-web-production.up.railway.app/
+Project-URL: Documentation, https://renderly-web-production.up.railway.app/docs.html
+Project-URL: API reference (OpenAPI), https://renderly-web-production.up.railway.app/openapi.json
+Keywords: renderly,renderly-ai,ai,api,sdk,image-generation,video-generation,text-to-image,audio,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# renderly-ai for Python
+
+Official client for the [Renderly](https://renderly-web-production.up.railway.app/) API:
+one key and one credit wallet (1 credit = $0.01) for image, video, audio, 3D and
+language models. Standard library only; Python 3.8+. Keep your API key on a server.
+
+```sh
+pip install renderly-ai
+export RENDERLY_API_KEY="rly_…"   # Settings → API access
+```
+
+```python
+from renderly_ai import Renderly
+
+renderly = Renderly()  # reads RENDERLY_API_KEY (and RENDERLY_BASE_URL if set)
+
+result = renderly.run(
+    model_id="model-…",            # from renderly.search_models("…")
+    operation="text-to-image",
+    input={"prompt": "A glass fox in morning light"},
+    max_credits=50,                # refuse anything pricier, before any charge
+)
+
+for artifact in result["job"]["artifacts"]:
+    data = renderly.download_artifact(artifact["id"])
+```
+
+`run()` quotes, checks `max_credits`, creates the job with a server-side wait of
+up to 60 seconds and then long-polls until the job is `completed` or `refunded`.
+
+## Step by step
+
+```python
+models = renderly.search_models("portrait", kind="image", available=True)["models"]
+model = renderly.model(models[0]["id"])            # creation fields + inputSchema
+quote = renderly.quote(model_id=model["id"], operation=model["operation"], sku=model["sku"], input=input)  # free
+job = renderly.create_job(quote_id=quote["quoteId"], input=input, webhook_url="https://example.com/hooks/renderly", wait=30)["job"]
+done = renderly.wait_for_job(job["id"], on_update=lambda j: print(j["status"]))
+link = renderly.artifact(done["artifacts"][0]["id"])  # {"url", "expiresIn"}: 15 minutes
+```
+
+| Area | Methods |
+| --- | --- |
+| Models (public) | `models(...)`, `search_models(q, ...)`, `iter_models(...)`, `model(id)`, `catalog()`, `catalog_details(ids)`, `catalog_prices(ids)` |
+| Account | `account()`, `wallet()` (incl. `reserved`), `ledger(...)`, `iter_ledger(...)`, `usage(from_=, to=, group_by=)` |
+| Jobs | `quote()`, `create_job(..., wait=)`, `get_job(id, wait=)`, `list_jobs(status=, model_id=, from_=, to=, key_id=)`, `iter_jobs()`, `wait_for_job()`, `cancel_job(id)`, `run()` |
+| Files | `upload(data, kind=)`, `upload_from_url(url, kind=)`, `artifact(id)`, `artifact_url(id)`, `download_artifact(id)` |
+| Service | `status()` |
+
+- **Inputs:** `file = renderly.upload(data, kind="image")` or
+  `renderly.upload_from_url("https://…/photo.png", kind="image")`, then pass
+  `{"inputAssetId": file["id"]}` in the model's input field.
+- **Retries:** GETs and job creation retry network errors, 5xx and 429 (honouring
+  `Retry-After` up to 60 s); job creation reuses one request ID, so a retry never
+  starts a second job. Quotes retry at most once; uploads and cancellation retry
+  only after 429.
+- **Rate limits:** `renderly.last_rate_limit` holds `limit`, `remaining`, `reset`
+  and `retry_after`; `renderly.last_request_id` the latest `X-Request-Id`.
+- **Errors:** failures raise `RenderlyError` with `code`, `status`, `request_id`
+  and, for 429, `retry_after`.
+
+## Webhooks
+
+```python
+from renderly_ai import verify_webhook
+
+# Use the raw request body exactly as received.
+event = verify_webhook(raw_body, headers["Renderly-Signature"], os.environ["RENDERLY_WEBHOOK_SECRET"])
+if event["type"] == "job.completed":
+    artifacts = event["data"]["job"]["artifacts"]
+elif event["type"] == "balance.low":
+    balance = event["data"]["balance"]
+```
+
+Full guide: <https://renderly-web-production.up.railway.app/docs.html> ·
+OpenAPI: <https://renderly-web-production.up.railway.app/openapi.json>

renderly_ai-0.2.0/README.md

@@ -0,0 +1,76 @@
+# renderly-ai for Python
+
+Official client for the [Renderly](https://renderly-web-production.up.railway.app/) API:
+one key and one credit wallet (1 credit = $0.01) for image, video, audio, 3D and
+language models. Standard library only; Python 3.8+. Keep your API key on a server.
+
+```sh
+pip install renderly-ai
+export RENDERLY_API_KEY="rly_…"   # Settings → API access
+```
+
+```python
+from renderly_ai import Renderly
+
+renderly = Renderly()  # reads RENDERLY_API_KEY (and RENDERLY_BASE_URL if set)
+
+result = renderly.run(
+    model_id="model-…",            # from renderly.search_models("…")
+    operation="text-to-image",
+    input={"prompt": "A glass fox in morning light"},
+    max_credits=50,                # refuse anything pricier, before any charge
+)
+
+for artifact in result["job"]["artifacts"]:
+    data = renderly.download_artifact(artifact["id"])
+```
+
+`run()` quotes, checks `max_credits`, creates the job with a server-side wait of
+up to 60 seconds and then long-polls until the job is `completed` or `refunded`.
+
+## Step by step
+
+```python
+models = renderly.search_models("portrait", kind="image", available=True)["models"]
+model = renderly.model(models[0]["id"])            # creation fields + inputSchema
+quote = renderly.quote(model_id=model["id"], operation=model["operation"], sku=model["sku"], input=input)  # free
+job = renderly.create_job(quote_id=quote["quoteId"], input=input, webhook_url="https://example.com/hooks/renderly", wait=30)["job"]
+done = renderly.wait_for_job(job["id"], on_update=lambda j: print(j["status"]))
+link = renderly.artifact(done["artifacts"][0]["id"])  # {"url", "expiresIn"}: 15 minutes
+```
+
+| Area | Methods |
+| --- | --- |
+| Models (public) | `models(...)`, `search_models(q, ...)`, `iter_models(...)`, `model(id)`, `catalog()`, `catalog_details(ids)`, `catalog_prices(ids)` |
+| Account | `account()`, `wallet()` (incl. `reserved`), `ledger(...)`, `iter_ledger(...)`, `usage(from_=, to=, group_by=)` |
+| Jobs | `quote()`, `create_job(..., wait=)`, `get_job(id, wait=)`, `list_jobs(status=, model_id=, from_=, to=, key_id=)`, `iter_jobs()`, `wait_for_job()`, `cancel_job(id)`, `run()` |
+| Files | `upload(data, kind=)`, `upload_from_url(url, kind=)`, `artifact(id)`, `artifact_url(id)`, `download_artifact(id)` |
+| Service | `status()` |
+
+- **Inputs:** `file = renderly.upload(data, kind="image")` or
+  `renderly.upload_from_url("https://…/photo.png", kind="image")`, then pass
+  `{"inputAssetId": file["id"]}` in the model's input field.
+- **Retries:** GETs and job creation retry network errors, 5xx and 429 (honouring
+  `Retry-After` up to 60 s); job creation reuses one request ID, so a retry never
+  starts a second job. Quotes retry at most once; uploads and cancellation retry
+  only after 429.
+- **Rate limits:** `renderly.last_rate_limit` holds `limit`, `remaining`, `reset`
+  and `retry_after`; `renderly.last_request_id` the latest `X-Request-Id`.
+- **Errors:** failures raise `RenderlyError` with `code`, `status`, `request_id`
+  and, for 429, `retry_after`.
+
+## Webhooks
+
+```python
+from renderly_ai import verify_webhook
+
+# Use the raw request body exactly as received.
+event = verify_webhook(raw_body, headers["Renderly-Signature"], os.environ["RENDERLY_WEBHOOK_SECRET"])
+if event["type"] == "job.completed":
+    artifacts = event["data"]["job"]["artifacts"]
+elif event["type"] == "balance.low":
+    balance = event["data"]["balance"]
+```
+
+Full guide: <https://renderly-web-production.up.railway.app/docs.html> ·
+OpenAPI: <https://renderly-web-production.up.railway.app/openapi.json>

renderly_ai-0.2.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "renderly-ai"
+version = "0.2.0"
+description = "Official client for the Renderly AI API: search models, price, create and download image, video, audio and language results with one key and one credit wallet."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Renderly" }]
+keywords = ["renderly", "renderly-ai", "ai", "api", "sdk", "image-generation", "video-generation", "text-to-image", "audio", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://renderly-web-production.up.railway.app/"
+Documentation = "https://renderly-web-production.up.railway.app/docs.html"
+"API reference (OpenAPI)" = "https://renderly-web-production.up.railway.app/openapi.json"
+
+[tool.setuptools]
+packages = ["renderly_ai"]
+license-files = ["LICENSE"]
+
+[tool.setuptools.package-data]
+renderly_ai = ["py.typed"]

renderly_ai-0.2.0/renderly_ai/__init__.py

@@ -0,0 +1,402 @@
+"""Official client for the Renderly AI API.
+
+Standard library only. Keep API keys on servers, never in browser code.
+
+    from renderly_ai import Renderly
+    client = Renderly()  # reads RENDERLY_API_KEY (and RENDERLY_BASE_URL if set)
+    result = client.run(model_id="model-…", operation="text-to-image",
+                        input={"prompt": "a glass fox"}, max_credits=50)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable, Dict, Iterable, Iterator, List, Optional, Union
+
+__all__ = ["Renderly", "RenderlyError", "new_request_id", "verify_webhook", "parse_rate_limit", "DEFAULT_BASE_URL", "TERMINAL_STATUSES"]
+__version__ = "0.2.0"
+
+DEFAULT_BASE_URL = "https://woovhhwoevjoipwltiwy.supabase.co/functions/v1/core-api"
+TERMINAL_STATUSES = ("completed", "refunded")
+TERMINAL = set(TERMINAL_STATUSES)
+UPLOAD_KINDS = {"image", "video", "audio"}
+MAX_RETRY_AFTER = 60.0
+_REQUEST_ID = re.compile(r"^[A-Za-z0-9_-]{8,100}$")
+# Retry policies: "all" (GETs and job creation, whose request ID makes a replay
+# return the original job), "once" (quotes: at most one retry), "rate" (only
+# 429, which the API answers before doing work: uploads, cancellation), None.
+_RETRY = {"all": (True, True, None), "once": (True, True, 1), "rate": (False, False, None)}
+
+
+class RenderlyError(Exception):
+    """An API, network or validation error with a stable ``code``.
+
+    ``request_id`` is the X-Request-Id to quote to support; ``retry_after`` is
+    the Retry-After of a 429 in seconds; ``rate_limit`` holds the rate headers.
+    """
+
+    def __init__(self, message: str, code: str = "unknown_error", status: int = 0, request_id: Optional[str] = None,
+                 retry_after: Optional[float] = None, rate_limit: Optional[Dict[str, Optional[float]]] = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.rate_limit = rate_limit
+
+
+def _number(headers: Any, name: str) -> Optional[float]:
+    if headers is None:
+        return None
+    value = headers.get(name)
+    if value is None or value == "":
+        return None
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return int(number) if number.is_integer() else number
+
+
+def parse_rate_limit(headers: Any) -> Optional[Dict[str, Optional[float]]]:
+    """Rate-limit headers as {limit, remaining, reset, retry_after}, or None when absent."""
+    info = {"limit": _number(headers, "X-RateLimit-Limit"), "remaining": _number(headers, "X-RateLimit-Remaining"),
+            "reset": _number(headers, "X-RateLimit-Reset"), "retry_after": _number(headers, "Retry-After")}
+    return info if any(value is not None for value in info.values()) else None
+
+
+def verify_webhook(payload, header: Optional[str], secret: str, tolerance: int = 300, now: Optional[float] = None) -> Dict[str, Any]:
+    """Verify a webhook's Renderly-Signature header against the raw body; returns the event."""
+    import hashlib
+    import hmac
+
+    body = payload.decode("utf-8") if isinstance(payload, (bytes, bytearray)) else str(payload)
+    fields = dict(part.strip().split("=", 1) for part in (header or "").split(",") if "=" in part)
+    try:
+        timestamp = int(fields.get("t", ""))
+    except ValueError:
+        raise RenderlyError("Missing or malformed Renderly-Signature header.", "invalid_signature") from None
+    signature = fields.get("v1", "")
+    if not re.fullmatch(r"[a-f0-9]{64}", signature):
+        raise RenderlyError("Missing or malformed Renderly-Signature header.", "invalid_signature")
+    if abs((time.time() if now is None else now) - timestamp) > tolerance:
+        raise RenderlyError("The webhook timestamp is outside the allowed window.", "stale_signature")
+    expected = hmac.new(secret.encode("utf-8"), f"{timestamp}.{body}".encode("utf-8"), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        raise RenderlyError("The webhook signature does not match.", "invalid_signature")
+    return json.loads(body)
+
+
+def new_request_id() -> str:
+    """A request ID valid for job creation: 8–100 letters, digits, "_" or "-"."""
+    return "req_" + uuid.uuid4().hex
+
+
+def _wait_seconds(value: Optional[float]) -> Optional[int]:
+    if value is None or value is False:
+        return None
+    seconds = int(value)
+    if seconds < 0:
+        raise RenderlyError("wait must be between 0 and 60 seconds.", "invalid_request")
+    return min(seconds, 60) or None
+
+
+def _join(value: Union[None, str, Iterable[str]]) -> Optional[str]:
+    if value is None or isinstance(value, str):
+        return value
+    return ",".join(value)
+
+
+def _boolean(value: Optional[bool]) -> Optional[str]:
+    return None if value is None else ("true" if value else "false")
+
+
+Transport = Callable[[urllib.request.Request, float], Any]
+
+
+def _default_transport(request: urllib.request.Request, timeout: float):
+    return urllib.request.urlopen(request, timeout=timeout)
+
+
+class Renderly:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        transport: Optional[Transport] = None,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.api_key = api_key if api_key is not None else os.environ.get("RENDERLY_API_KEY")
+        self.base_url = (base_url or os.environ.get("RENDERLY_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._transport = transport or _default_transport
+        self._sleep = sleep
+        #: Rate-limit headers of the most recent response that carried them.
+        self.last_rate_limit: Optional[Dict[str, Optional[float]]] = None
+        #: X-Request-Id of the most recent API response.
+        self.last_request_id: Optional[str] = None
+        self.server_wait: Optional[bool] = None  # False once the API rejected ?wait on GET /jobs/{id}
+
+    # -- transport -----------------------------------------------------------
+    def _request(self, method: str, path: str, *, body: Any = None, query: Optional[Dict[str, Any]] = None,
+                 auth: bool = True, raw: bool = False, retry: Optional[str] = "default", timeout: Optional[float] = None) -> Any:
+        if auth and not self.api_key:
+            raise RenderlyError("Set api_key or the RENDERLY_API_KEY environment variable.", "auth_required", 401)
+        if retry == "default":
+            retry = "all" if method == "GET" else None
+        network, server, cap = _RETRY.get(retry, (False, False, 0)) if retry else (False, False, 0)
+        limit = self.max_retries if cap is None else min(self.max_retries, cap)
+        url = self.base_url + path
+        params = {k: v for k, v in (query or {}).items() if v is not None and v != ""}
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        headers = {"Accept": "application/json", "User-Agent": f"renderly-python/{__version__}"}
+        if auth:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        data = None
+        if raw:
+            data, headers["Content-Type"] = body, "application/octet-stream"
+        elif body is not None:
+            data, headers["Content-Type"] = json.dumps(body).encode("utf-8"), "application/json"
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, method=method, headers=headers)
+            response_headers = None
+            try:
+                with self._transport(request, timeout or self.timeout) as response:
+                    status, text = response.status, response.read().decode("utf-8")
+                    response_headers = getattr(response, "headers", None)
+            except urllib.error.HTTPError as error:
+                status, text, response_headers = error.code, error.read().decode("utf-8", "replace"), error.headers
+            except (urllib.error.URLError, TimeoutError, OSError) as error:
+                if network and attempt < limit:
+                    self._sleep(0.5 * 2 ** attempt)
+                    attempt += 1
+                    continue
+                code = "timeout" if isinstance(error, TimeoutError) or "timed out" in str(error) else "network_error"
+                raise RenderlyError("The request timed out." if code == "timeout" else "The Renderly API could not be reached.", code) from error
+            request_id = response_headers.get("X-Request-Id") if response_headers is not None else None
+            rate_limit = parse_rate_limit(response_headers)
+            if request_id:
+                self.last_request_id = request_id
+            if rate_limit:
+                self.last_rate_limit = rate_limit
+            retry_after = rate_limit["retry_after"] if rate_limit else None
+            retryable = (bool(retry) and (retry_after is None or retry_after <= MAX_RETRY_AFTER)) if status == 429 else (status >= 500 and server)
+            if retryable and attempt < limit:
+                self._sleep(retry_after if retry_after is not None and retry_after >= 0 else 2 ** attempt)
+                attempt += 1
+                continue
+            try:
+                payload = json.loads(text) if text else None
+            except ValueError:
+                payload = None
+            if status >= 400:
+                error = (payload or {}).get("error") or {} if isinstance(payload, dict) else {}
+                raise RenderlyError(error.get("message") or f"Request failed with status {status}.", error.get("code") or "http_error", status,
+                                    request_id=request_id, retry_after=retry_after, rate_limit=rate_limit)
+            if payload is None:
+                raise RenderlyError("The Renderly API returned an unexpected response.", "invalid_response", status, request_id=request_id)
+            return payload
+
+    def _timeout_for(self, wait: Optional[int]) -> Optional[float]:
+        return max(self.timeout, wait + 15.0) if wait else None
+
+    # -- catalogue (public, no API key) --------------------------------------
+    def catalog(self) -> Dict[str, Any]:
+        """Full public model catalogue."""
+        return self._request("GET", "/catalog", auth=False)
+
+    def catalog_details(self, ids: List[str]) -> Dict[str, Any]:
+        """Full creation settings for up to 100 models."""
+        if not ids or len(ids) > 100:
+            raise RenderlyError("Pass between 1 and 100 model IDs.", "invalid_request")
+        return self._request("GET", "/catalog/details", auth=False, query={"ids": ",".join(ids)})
+
+    def catalog_prices(self, ids: List[str]) -> Dict[str, Any]:
+        """Display prices for up to 12 models."""
+        if not ids or len(ids) > 12:
+            raise RenderlyError("Pass between 1 and 12 model IDs.", "invalid_request")
+        return self._request("GET", "/catalog/prices", auth=False, query={"ids": ",".join(ids)})
+
+    def models(self, *, q: Optional[str] = None, kind: Optional[str] = None, operation: Optional[str] = None, maker: Optional[str] = None,
+               available: Optional[bool] = None, limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        """One page of compact model entries: {models, nextCursor, total}."""
+        return self._request("GET", "/models", auth=False, query={"q": q, "kind": kind, "operation": operation, "maker": maker,
+                                                                    "available": _boolean(available), "limit": limit, "cursor": cursor})
+
+    def search_models(self, q: str, **filters: Any) -> Dict[str, Any]:
+        """Search models by text; same filters as models()."""
+        return self.models(q=q, **filters)
+
+    def iter_models(self, **filters: Any) -> Iterator[Dict[str, Any]]:
+        """Every matching model, following nextCursor."""
+        cursor = filters.pop("cursor", None)
+        while True:
+            page = self.models(cursor=cursor, **filters)
+            yield from page.get("models", [])
+            cursor = page.get("nextCursor")
+            if not cursor:
+                return
+
+    def model(self, model_id: str) -> Dict[str, Any]:
+        """One model with full creation settings and inputSchema (JSON Schema of the quote input)."""
+        data = self._request("GET", "/models/" + urllib.parse.quote(model_id, safe=""), auth=False)
+        return data.get("model", data)
+
+    def status(self) -> Dict[str, Any]:
+        """Public service status: components, daily outcomes and incidents."""
+        return self._request("GET", "/status", auth=False)
+
+    # -- account -------------------------------------------------------------
+    def account(self) -> Dict[str, Any]:
+        """The account, its tier and limits, and the calling key."""
+        return self._request("GET", "/account")
+
+    def wallet(self) -> Dict[str, Any]:
+        """Balance, reserved credits and lowBalanceCredits."""
+        return self._request("GET", "/wallet")
+
+    def ledger(self, *, limit: Optional[int] = None, before: Optional[str] = None, kind: Optional[str] = None,
+               from_: Optional[str] = None, to: Optional[str] = None) -> Dict[str, Any]:
+        """A page of ledger entries, newest first: {entries, nextBefore}."""
+        return self._request("GET", "/ledger", query={"limit": limit, "before": before, "kind": kind, "from": from_, "to": to})
+
+    def iter_ledger(self, *, page_size: int = 200, **filters: Any) -> Iterator[Dict[str, Any]]:
+        before = filters.pop("before", None)
+        while True:
+            page = self.ledger(limit=page_size, before=before, **filters)
+            yield from page.get("entries", [])
+            before = page.get("nextBefore")
+            if not before:
+                return
+
+    def usage(self, *, from_: Optional[str] = None, to: Optional[str] = None, group_by: Optional[str] = None) -> Dict[str, Any]:
+        """Usage totals and rows grouped by "day", "model" or "key"."""
+        return self._request("GET", "/usage", query={"from": from_, "to": to, "groupBy": group_by})
+
+    # -- creation ------------------------------------------------------------
+    def quote(self, *, model_id: str, operation: str, input: Dict[str, Any], sku: str = "selected-settings-v1") -> Dict[str, Any]:
+        """Price a request without charging. Returns quoteId, credits, maxCredits and expiresAt."""
+        return self._request("POST", "/quotes", body={"modelId": model_id, "operation": operation, "sku": sku, "input": input}, retry="once")
+
+    def create_job(self, *, quote_id: str, input: Dict[str, Any], request_id: Optional[str] = None, webhook_url: Optional[str] = None,
+                   wait: Optional[float] = None) -> Dict[str, Any]:
+        """Accept a quote and start the job. Retrying with the same request_id returns the original job.
+
+        ``wait`` (0–60 s) asks the API to hold the response until the job finishes.
+        """
+        request_id = request_id or new_request_id()
+        if not _REQUEST_ID.match(request_id):
+            raise RenderlyError('request_id must be 8–100 letters, digits, "_" or "-".', "invalid_request")
+        seconds = _wait_seconds(wait)
+        body = {"quoteId": quote_id, "requestId": request_id, "input": input}
+        if webhook_url:
+            body["webhookUrl"] = webhook_url
+        return self._request("POST", "/jobs", body=body, query={"wait": seconds}, retry="all", timeout=self._timeout_for(seconds))
+
+    def get_job(self, job_id: str, *, wait: Optional[float] = None) -> Dict[str, Any]:
+        """One job. With ``wait`` (0–60 s) the API answers as soon as it finishes or the wait ends."""
+        seconds = _wait_seconds(wait)
+        return self._request("GET", "/jobs/" + urllib.parse.quote(job_id, safe=""), query={"wait": seconds}, timeout=self._timeout_for(seconds))["job"]
+
+    def list_jobs(self, *, limit: Optional[int] = None, before: Optional[str] = None, status: Union[None, str, Iterable[str]] = None,
+                  model_id: Optional[str] = None, from_: Optional[str] = None, to: Optional[str] = None, key_id: Optional[str] = None) -> Dict[str, Any]:
+        """A page of owned jobs, newest first. Pass the returned nextBefore to continue."""
+        return self._request("GET", "/jobs", query={"limit": limit, "before": before, "status": _join(status), "modelId": model_id,
+                                                     "from": from_, "to": to, "keyId": key_id})
+
+    def iter_jobs(self, *, page_size: int = 50, **filters: Any) -> Iterator[Dict[str, Any]]:
+        before = filters.pop("before", None)
+        while True:
+            page = self.list_jobs(limit=page_size, before=before, **filters)
+            yield from page.get("jobs", [])
+            before = page.get("nextBefore")
+            if not before:
+                return
+
+    def cancel_job(self, job_id: str) -> Dict[str, Any]:
+        """Cancel a job not yet sent for generation; returns {job, balance, cancelled}."""
+        return self._request("POST", "/jobs/" + urllib.parse.quote(job_id, safe="") + "/cancel", body={}, retry="rate")
+
+    def wait_for_job(self, job_id: str, *, interval: float = 3.0, timeout: float = 900.0, long_poll: bool = True,
+                     on_update: Optional[Callable[[Dict[str, Any]], None]] = None) -> Dict[str, Any]:
+        """Wait until the job is completed or refunded, long-polling when the API supports it."""
+        deadline = time.monotonic() + timeout
+        while True:
+            remaining, started, job = int(deadline - time.monotonic()), time.monotonic(), None
+            if long_poll and self.server_wait is not False and remaining >= 1:
+                try:
+                    job = self.get_job(job_id, wait=min(60, remaining))
+                    self.server_wait = True
+                except RenderlyError as error:
+                    if error.status != 400 or self.server_wait is not None:
+                        raise
+                    self.server_wait = False
+            if job is None:
+                job = self.get_job(job_id)
+            if on_update:
+                on_update(job)
+            if job.get("status") in TERMINAL:
+                return job
+            if time.monotonic() + (0 if self.server_wait else interval) > deadline:
+                raise RenderlyError("The job did not finish before the wait timeout. It may still complete; check it again later.", "wait_timeout")
+            if not self.server_wait or time.monotonic() - started < 1:
+                self._sleep(interval)
+
+    # -- files ---------------------------------------------------------------
+    def artifact(self, artifact_id: str) -> Dict[str, Any]:
+        """{url, expiresIn}: a signed download link for a completed artifact (15 minutes)."""
+        return self._request("GET", "/artifacts/" + urllib.parse.quote(artifact_id, safe=""))
+
+    def artifact_url(self, artifact_id: str) -> str:
+        return self.artifact(artifact_id)["url"]
+
+    def download_artifact(self, artifact_id: str) -> bytes:
+        """Download an artifact's bytes. The API key is never sent to storage."""
+        url = self.artifact_url(artifact_id)
+        try:
+            with self._transport(urllib.request.Request(url, method="GET"), self.timeout) as response:
+                return response.read()
+        except urllib.error.HTTPError as error:
+            raise RenderlyError(f"Artifact download failed with status {error.code}.", "download_failed", error.code) from error
+
+    def upload(self, data: bytes, *, kind: str) -> Dict[str, Any]:
+        """Upload an image, MP4 video or audio input; use {"inputAssetId": result["id"]} in the model input."""
+        if kind not in UPLOAD_KINDS:
+            raise RenderlyError('kind must be "image", "video" or "audio".', "invalid_request")
+        return self._request("POST", "/uploads", query={"kind": kind}, body=data, raw=True, retry="rate")
+
+    def upload_from_url(self, url: str, *, kind: str) -> Dict[str, Any]:
+        """Import a public HTTPS file as an input (same checks and 24 MiB limit as upload)."""
+        if kind not in UPLOAD_KINDS:
+            raise RenderlyError('kind must be "image", "video" or "audio".', "invalid_request")
+        if not str(url).lower().startswith("https://"):
+            raise RenderlyError("url must be a public HTTPS address.", "invalid_upload_url")
+        return self._request("POST", "/uploads", query={"kind": kind}, body={"url": str(url)}, retry="rate")
+
+    def run(self, *, model_id: str, operation: str, input: Dict[str, Any], sku: str = "selected-settings-v1",
+            max_credits: Optional[float] = None, request_id: Optional[str] = None, webhook_url: Optional[str] = None,
+            server_wait: float = 60, interval: float = 3.0, timeout: float = 900.0,
+            on_update: Optional[Callable[[Dict[str, Any]], None]] = None) -> Dict[str, Any]:
+        """Quote, create and wait in one call. max_credits refuses an over-budget quote before any charge."""
+        quote = self.quote(model_id=model_id, operation=operation, input=input, sku=sku)
+        ceiling = quote.get("maxCredits", quote.get("credits"))
+        if max_credits is not None and float(ceiling) > max_credits:
+            raise RenderlyError(f"The quote ({ceiling} credits) is above max_credits ({max_credits}). Nothing was charged.", "over_budget")
+        created = self.create_job(quote_id=quote["quoteId"], input=input, request_id=request_id, webhook_url=webhook_url, wait=server_wait or None)
+        if on_update:
+            on_update(created["job"])
+        job = created["job"] if created["job"].get("status") in TERMINAL else self.wait_for_job(
+            created["job"]["id"], interval=interval, timeout=timeout, on_update=on_update)
+        return {"quote": quote, "job": job, "balance": created.get("balance")}

renderly_ai-0.2.0/renderly_ai.egg-info/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: renderly-ai
+Version: 0.2.0
+Summary: Official client for the Renderly AI API: search models, price, create and download image, video, audio and language results with one key and one credit wallet.
+Author: Renderly
+License: MIT
+Project-URL: Homepage, https://renderly-web-production.up.railway.app/
+Project-URL: Documentation, https://renderly-web-production.up.railway.app/docs.html
+Project-URL: API reference (OpenAPI), https://renderly-web-production.up.railway.app/openapi.json
+Keywords: renderly,renderly-ai,ai,api,sdk,image-generation,video-generation,text-to-image,audio,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# renderly-ai for Python
+
+Official client for the [Renderly](https://renderly-web-production.up.railway.app/) API:
+one key and one credit wallet (1 credit = $0.01) for image, video, audio, 3D and
+language models. Standard library only; Python 3.8+. Keep your API key on a server.
+
+```sh
+pip install renderly-ai
+export RENDERLY_API_KEY="rly_…"   # Settings → API access
+```
+
+```python
+from renderly_ai import Renderly
+
+renderly = Renderly()  # reads RENDERLY_API_KEY (and RENDERLY_BASE_URL if set)
+
+result = renderly.run(
+    model_id="model-…",            # from renderly.search_models("…")
+    operation="text-to-image",
+    input={"prompt": "A glass fox in morning light"},
+    max_credits=50,                # refuse anything pricier, before any charge
+)
+
+for artifact in result["job"]["artifacts"]:
+    data = renderly.download_artifact(artifact["id"])
+```
+
+`run()` quotes, checks `max_credits`, creates the job with a server-side wait of
+up to 60 seconds and then long-polls until the job is `completed` or `refunded`.
+
+## Step by step
+
+```python
+models = renderly.search_models("portrait", kind="image", available=True)["models"]
+model = renderly.model(models[0]["id"])            # creation fields + inputSchema
+quote = renderly.quote(model_id=model["id"], operation=model["operation"], sku=model["sku"], input=input)  # free
+job = renderly.create_job(quote_id=quote["quoteId"], input=input, webhook_url="https://example.com/hooks/renderly", wait=30)["job"]
+done = renderly.wait_for_job(job["id"], on_update=lambda j: print(j["status"]))
+link = renderly.artifact(done["artifacts"][0]["id"])  # {"url", "expiresIn"}: 15 minutes
+```
+
+| Area | Methods |
+| --- | --- |
+| Models (public) | `models(...)`, `search_models(q, ...)`, `iter_models(...)`, `model(id)`, `catalog()`, `catalog_details(ids)`, `catalog_prices(ids)` |
+| Account | `account()`, `wallet()` (incl. `reserved`), `ledger(...)`, `iter_ledger(...)`, `usage(from_=, to=, group_by=)` |
+| Jobs | `quote()`, `create_job(..., wait=)`, `get_job(id, wait=)`, `list_jobs(status=, model_id=, from_=, to=, key_id=)`, `iter_jobs()`, `wait_for_job()`, `cancel_job(id)`, `run()` |
+| Files | `upload(data, kind=)`, `upload_from_url(url, kind=)`, `artifact(id)`, `artifact_url(id)`, `download_artifact(id)` |
+| Service | `status()` |
+
+- **Inputs:** `file = renderly.upload(data, kind="image")` or
+  `renderly.upload_from_url("https://…/photo.png", kind="image")`, then pass
+  `{"inputAssetId": file["id"]}` in the model's input field.
+- **Retries:** GETs and job creation retry network errors, 5xx and 429 (honouring
+  `Retry-After` up to 60 s); job creation reuses one request ID, so a retry never
+  starts a second job. Quotes retry at most once; uploads and cancellation retry
+  only after 429.
+- **Rate limits:** `renderly.last_rate_limit` holds `limit`, `remaining`, `reset`
+  and `retry_after`; `renderly.last_request_id` the latest `X-Request-Id`.
+- **Errors:** failures raise `RenderlyError` with `code`, `status`, `request_id`
+  and, for 429, `retry_after`.
+
+## Webhooks
+
+```python
+from renderly_ai import verify_webhook
+
+# Use the raw request body exactly as received.
+event = verify_webhook(raw_body, headers["Renderly-Signature"], os.environ["RENDERLY_WEBHOOK_SECRET"])
+if event["type"] == "job.completed":
+    artifacts = event["data"]["job"]["artifacts"]
+elif event["type"] == "balance.low":
+    balance = event["data"]["balance"]
+```
+
+Full guide: <https://renderly-web-production.up.railway.app/docs.html> ·
+OpenAPI: <https://renderly-web-production.up.railway.app/openapi.json>

renderly_ai-0.2.0/renderly_ai.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+renderly_ai/__init__.py
+renderly_ai/py.typed
+renderly_ai.egg-info/PKG-INFO
+renderly_ai.egg-info/SOURCES.txt
+renderly_ai.egg-info/dependency_links.txt
+renderly_ai.egg-info/top_level.txt
+tests/test_client.py

renderly_ai-0.2.0/renderly_ai.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

renderly_ai-0.2.0/renderly_ai.egg-info/top_level.txt

@@ -0,0 +1 @@
+renderly_ai

renderly_ai-0.2.0/setup.cfg

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

renderly_ai-0.2.0/tests/test_client.py

@@ -0,0 +1,313 @@
+import io
+import json
+import os
+import unittest
+import urllib.error
+import urllib.parse
+from email.message import Message
+
+from renderly_ai import Renderly, RenderlyError, new_request_id, verify_webhook, parse_rate_limit, DEFAULT_BASE_URL
+
+
+def headers_of(values):
+    message = Message()
+    for key, value in (values or {}).items():
+        message[key] = value
+    return message
+
+
+class FakeResponse:
+    def __init__(self, status, body, headers=None):
+        self.status = status
+        self._body = body if isinstance(body, bytes) else json.dumps(body).encode()
+        self.headers = headers_of(headers)
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def http_error(url, status, body, headers=None):
+    return urllib.error.HTTPError(url, status, "error", headers_of(headers), io.BytesIO(json.dumps(body).encode()))
+
+
+class Transport:
+    def __init__(self, handler):
+        self.handler, self.calls = handler, []
+
+    def __call__(self, request, timeout):
+        self.calls.append(request)
+        result = self.handler(request, len(self.calls))
+        if isinstance(result, Exception):
+            raise result
+        return result
+
+
+def client(handler, **kwargs):
+    transport = Transport(handler)
+    return Renderly(api_key=kwargs.pop("api_key", "rk_test"), transport=transport, sleep=lambda s: None, **kwargs), transport
+
+
+def body(request):
+    return json.loads(request.data.decode())
+
+
+def path_of(request):
+    return urllib.parse.urlsplit(request.full_url).path.split("/core-api", 1)[-1]
+
+
+def query_of(request):
+    return dict(urllib.parse.parse_qsl(urllib.parse.urlsplit(request.full_url).query))
+
+
+class ClientTests(unittest.TestCase):
+    def test_bearer_key_on_account_calls_only(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"balance": 125} if r.full_url.endswith("/wallet") else {"models": []}))
+        self.assertEqual(c.wallet(), {"balance": 125})
+        c.catalog()
+        self.assertEqual(t.calls[0].full_url, DEFAULT_BASE_URL + "/wallet")
+        self.assertEqual(t.calls[0].get_header("Authorization"), "Bearer rk_test")
+        self.assertIsNone(t.calls[1].get_header("Authorization"))
+
+    def test_missing_key_fails_before_request(self):
+        c, t = client(lambda r, n: FakeResponse(200, {}), api_key="")
+        with self.assertRaises(RenderlyError) as caught:
+            c.wallet()
+        self.assertEqual(caught.exception.code, "auth_required")
+        self.assertEqual(t.calls, [])
+
+    def test_api_error_fields(self):
+        c, _ = client(lambda r, n: http_error(r.full_url, 409, {"error": {"code": "insufficient_balance", "message": "Your credit balance is too low."}}))
+        with self.assertRaises(RenderlyError) as caught:
+            c.create_job(quote_id="q", input={})
+        self.assertEqual((caught.exception.code, caught.exception.status), ("insufficient_balance", 409))
+
+    def test_job_retry_keeps_request_id(self):
+        def handler(r, n):
+            if n == 1:
+                return http_error(r.full_url, 503, {"error": {"code": "service_unavailable", "message": "x"}}, {"Retry-After": "0"})
+            return FakeResponse(200, {"job": {"id": "job-1", "status": "queued"}, "balance": 90, "reused": True})
+        c, t = client(handler, max_retries=1)
+        self.assertTrue(c.create_job(quote_id="quote-1", input={"prompt": "a fox"})["reused"])
+        self.assertEqual(len(t.calls), 2)
+        self.assertEqual(body(t.calls[0])["requestId"], body(t.calls[1])["requestId"])
+
+    def test_upload_not_retried_after_server_error_and_kind_validated(self):
+        c, t = client(lambda r, n: http_error(r.full_url, 503, {"error": {"code": "service_unavailable", "message": "x"}}), max_retries=3)
+        with self.assertRaises(RenderlyError):
+            c.upload(b"\x01\x02", kind="image")
+        self.assertEqual(len(t.calls), 1)
+        self.assertEqual(t.calls[0].full_url, DEFAULT_BASE_URL + "/uploads?kind=image")
+        with self.assertRaises(RenderlyError):
+            c.upload(b"\x01", kind="pdf")
+
+    def test_wait_for_job_until_terminal(self):
+        statuses = ["queued", "processing", "completed"]
+        c, _ = client(lambda r, n: FakeResponse(200, {"job": {"id": "job-1", "status": statuses[n - 1]}}))
+        seen = []
+        self.assertEqual(c.wait_for_job("job-1", interval=0, on_update=lambda j: seen.append(j["status"]))["status"], "completed")
+        self.assertEqual(seen, statuses)
+
+    def test_run_refuses_over_budget_quote(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"quoteId": "quote-1", "credits": 40, "maxCredits": 55}))
+        with self.assertRaises(RenderlyError) as caught:
+            c.run(model_id="m", operation="text-to-image", input={"prompt": "x"}, max_credits=50)
+        self.assertEqual(caught.exception.code, "over_budget")
+        self.assertEqual(len(t.calls), 1)
+
+    def test_run_end_to_end(self):
+        def handler(r, n):
+            if r.full_url.endswith("/quotes"):
+                return FakeResponse(200, {"quoteId": "quote-1", "credits": 12})
+            if path_of(r) == "/jobs":
+                return FakeResponse(200, {"job": {"id": "job-1", "status": "queued"}, "balance": 88})
+            return FakeResponse(200, {"job": {"id": "job-1", "status": "completed", "artifacts": [{"id": "art-1"}]}})
+        c, t = client(handler)
+        result = c.run(model_id="m", operation="text-to-image", input={"prompt": "x"}, max_credits=20, interval=0)
+        self.assertEqual((result["job"]["status"], result["balance"]), ("completed", 88))
+        self.assertEqual(body(t.calls[0]), {"modelId": "m", "operation": "text-to-image", "sku": "selected-settings-v1", "input": {"prompt": "x"}})
+        self.assertEqual(query_of(t.calls[1]), {"wait": "60"})
+
+    def test_iter_jobs_pages(self):
+        pages = [{"jobs": [{"id": "a"}, {"id": "b"}], "nextBefore": "2026-10-01T00:00:00Z"}, {"jobs": [{"id": "c"}], "nextBefore": None}]
+        c, t = client(lambda r, n: FakeResponse(200, pages[n - 1]))
+        self.assertEqual([j["id"] for j in c.iter_jobs(page_size=2)], ["a", "b", "c"])
+        self.assertIn("before=2026-10-01T00%3A00%3A00Z", t.calls[1].full_url)
+
+    def test_download_does_not_send_key_to_storage(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"url": "https://storage.example/f.png?sig=1"}) if "/artifacts/" in r.full_url else FakeResponse(200, b"\x07\x08"))
+        self.assertEqual(c.download_artifact("art-1"), b"\x07\x08")
+        self.assertIsNone(t.calls[1].get_header("Authorization"))
+
+    def test_request_id_format(self):
+        import re
+        for _ in range(20):
+            self.assertRegex(new_request_id(), re.compile(r"^[A-Za-z0-9_-]{8,100}$"))
+
+    def test_verify_webhook_matches_server_signature(self):
+        secret = "whsec_" + "c" * 64
+        body = '{"id":"evt_9","type":"job.completed","createdAt":"2026-10-23T08:01:01Z","attempt":1,"data":{"job":{"id":"job-9","status":"completed"}}}'
+        header = "t=1800000000,v1=f0030f62fd11da782b19cfe354c64bcc8934a29b80a22e816bd0f06c427abc09"
+        self.assertEqual(verify_webhook(body.encode(), header, secret, now=1800000010)["data"]["job"]["id"], "job-9")
+        for bad_body, bad_header, now, code in [(body + " ", header, 1800000010, "invalid_signature"), (body, header, 1800000400, "stale_signature"), (body, "t=1,v1=zz", 1, "invalid_signature")]:
+            with self.assertRaises(RenderlyError) as caught:
+                verify_webhook(bad_body, bad_header, secret, now=now)
+            self.assertEqual(caught.exception.code, code)
+
+
+    def test_base_url_env_override(self):
+        saved = os.environ.get("RENDERLY_BASE_URL")
+        os.environ["RENDERLY_BASE_URL"] = "https://api.example.test/v1/"
+        try:
+            c, t = client(lambda r, n: FakeResponse(200, {"balance": 1}))
+            c.wallet()
+            self.assertEqual(t.calls[0].full_url, "https://api.example.test/v1/wallet")
+        finally:
+            if saved is None:
+                del os.environ["RENDERLY_BASE_URL"]
+            else:
+                os.environ["RENDERLY_BASE_URL"] = saved
+
+    def test_rate_limit_and_request_id_exposed(self):
+        headers = {"X-Request-Id": "req_1", "X-RateLimit-Limit": "600", "X-RateLimit-Remaining": "599", "X-RateLimit-Reset": "1800000060"}
+        c, _ = client(lambda r, n: FakeResponse(200, {"balance": 5}, headers))
+        c.wallet()
+        self.assertEqual(c.last_rate_limit, {"limit": 600, "remaining": 599, "reset": 1800000060, "retry_after": None})
+        self.assertEqual(c.last_request_id, "req_1")
+        self.assertIsNone(parse_rate_limit(headers_of({})))
+
+    def test_error_carries_request_id_and_retry_after(self):
+        def handler(r, n):
+            return http_error(r.full_url, 429, {"error": {"code": "rate_limited", "message": "Wait."}}, {"Retry-After": "120", "X-Request-Id": "req_2"})
+        c, t = client(handler)
+        with self.assertRaises(RenderlyError) as caught:
+            c.wallet()
+        self.assertEqual((caught.exception.code, caught.exception.retry_after, caught.exception.request_id), ("rate_limited", 120, "req_2"))
+        self.assertEqual(len(t.calls), 1)  # Retry-After above 60 s is reported, not slept through
+
+    def test_429_retried_for_gets_and_job_creation(self):
+        slept = []
+
+        def handler(r, n):
+            if n % 2:
+                return http_error(r.full_url, 429, {"error": {"code": "rate_limited", "message": "x"}}, {"Retry-After": "2"})
+            return FakeResponse(200, {"jobs": [], "nextBefore": None} if r.get_method() == "GET" else {"job": {"id": "j", "status": "queued"}, "balance": 1})
+        transport = Transport(handler)
+        c = Renderly(api_key="k", transport=transport, sleep=slept.append)
+        c.list_jobs()
+        c.create_job(quote_id="q", input={})
+        self.assertEqual(len(transport.calls), 4)
+        self.assertEqual(slept, [2, 2])
+
+    def test_quotes_retried_at_most_once(self):
+        c, t = client(lambda r, n: http_error(r.full_url, 503, {"error": {"code": "service_unavailable", "message": "x"}}, {"Retry-After": "0"}), max_retries=5)
+        with self.assertRaises(RenderlyError):
+            c.quote(model_id="m", operation="o", input={})
+        self.assertEqual(len(t.calls), 2)
+
+    def test_upload_retried_after_429(self):
+        def handler(r, n):
+            if n == 1:
+                return http_error(r.full_url, 429, {"error": {"code": "rate_limited", "message": "x"}}, {"Retry-After": "0"})
+            return FakeResponse(200, {"id": "up-1"})
+        c, t = client(handler)
+        self.assertEqual(c.upload(b"\x01", kind="image")["id"], "up-1")
+        self.assertEqual(len(t.calls), 2)
+
+    def test_upload_from_url(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"id": "up-2", "kind": "video"}))
+        self.assertEqual(c.upload_from_url("https://cdn.example.com/clip.mp4", kind="video")["id"], "up-2")
+        self.assertEqual(body(t.calls[0]), {"url": "https://cdn.example.com/clip.mp4"})
+        self.assertEqual(query_of(t.calls[0]), {"kind": "video"})
+        self.assertEqual(t.calls[0].get_header("Content-type"), "application/json")
+        with self.assertRaises(RenderlyError) as caught:
+            c.upload_from_url("http://cdn.example.com/a.png", kind="image")
+        self.assertEqual(caught.exception.code, "invalid_upload_url")
+
+    def test_account_usage_status(self):
+        routes = {"/account": {"account": {"tier": "scale"}, "key": None}, "/usage": {"groupBy": "key", "rows": []}, "/status": {"components": [], "daily": [], "incidents": []}}
+        c, t = client(lambda r, n: FakeResponse(200, routes[path_of(r)]))
+        self.assertEqual(c.account()["account"]["tier"], "scale")
+        self.assertEqual(c.usage(group_by="key", from_="2026-10-01T00:00:00Z")["groupBy"], "key")
+        self.assertEqual(query_of(t.calls[1]), {"groupBy": "key", "from": "2026-10-01T00:00:00Z"})
+        self.assertEqual(c.status()["incidents"], [])
+        self.assertIsNone(t.calls[2].get_header("Authorization"))
+
+    def test_iter_ledger_pages(self):
+        pages = [{"entries": [{"id": "l1"}, {"id": "l2"}], "nextBefore": "l2"}, {"entries": [{"id": "l3"}], "nextBefore": None}]
+        c, t = client(lambda r, n: FakeResponse(200, pages[n - 1]))
+        self.assertEqual([e["id"] for e in c.iter_ledger(page_size=2, kind="charge")], ["l1", "l2", "l3"])
+        self.assertEqual(query_of(t.calls[1]), {"limit": "2", "before": "l2", "kind": "charge"})
+
+    def test_list_jobs_filters(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"jobs": [], "nextBefore": None}))
+        c.list_jobs(status=["completed", "refunded"], model_id="m1", key_id="k1")
+        self.assertEqual(query_of(t.calls[0]), {"status": "completed,refunded", "modelId": "m1", "keyId": "k1"})
+
+    def test_models_search_iteration_and_schema(self):
+        def handler(r, n):
+            if path_of(r) == "/models/model-1":
+                return FakeResponse(200, {"model": {"id": "model-1", "inputSchema": {"type": "object"}}})
+            return FakeResponse(200, {"models": [{"id": "a"}], "nextCursor": "c2"} if n == 1 else {"models": [{"id": "b"}], "nextCursor": None})
+        c, t = client(handler)
+        self.assertEqual([m["id"] for m in c.iter_models(q="flux", available=True)], ["a", "b"])
+        self.assertEqual(query_of(t.calls[0]), {"q": "flux", "available": "true"})
+        self.assertEqual(query_of(t.calls[1])["cursor"], "c2")
+        self.assertIsNone(t.calls[0].get_header("Authorization"))
+        self.assertEqual(c.model("model-1")["inputSchema"], {"type": "object"})
+        c.search_models("portrait", limit=5)
+        self.assertEqual(query_of(t.calls[3]), {"q": "portrait", "limit": "5"})
+
+    def test_cancel_job(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"job": {"id": "job-1", "cancelled": True}, "balance": 100, "cancelled": True}))
+        self.assertTrue(c.cancel_job("job-1")["cancelled"])
+        self.assertEqual((t.calls[0].get_method(), path_of(t.calls[0]), t.calls[0].data), ("POST", "/jobs/job-1/cancel", b"{}"))
+
+    def test_create_job_webhook_and_wait(self):
+        c, t = client(lambda r, n: FakeResponse(200, {"job": {"id": "j", "status": "completed"}, "balance": 1}))
+        c.create_job(quote_id="q", input={}, webhook_url="https://hooks.example.com/r", wait=30)
+        self.assertEqual(query_of(t.calls[0]), {"wait": "30"})
+        self.assertEqual(body(t.calls[0])["webhookUrl"], "https://hooks.example.com/r")
+        c.create_job(quote_id="q", input={})
+        self.assertEqual(query_of(t.calls[1]), {})
+        self.assertNotIn("webhookUrl", body(t.calls[1]))
+
+    def test_wait_for_job_long_polls(self):
+        statuses = ["processing", "completed"]
+        c, t = client(lambda r, n: FakeResponse(200, {"job": {"id": "job-1", "status": statuses[n - 1]}}))
+        self.assertEqual(c.wait_for_job("job-1", interval=0)["status"], "completed")
+        self.assertEqual(query_of(t.calls[0]), {"wait": "60"})
+
+    def test_wait_for_job_falls_back_without_server_wait(self):
+        def handler(r, n):
+            if "wait" in query_of(r):
+                return http_error(r.full_url, 400, {"error": {"code": "invalid_request", "message": "x"}})
+            return FakeResponse(200, {"job": {"id": "job-1", "status": "completed" if n > 2 else "queued"}})
+        c, t = client(handler)
+        self.assertEqual(c.wait_for_job("job-1", interval=0)["status"], "completed")
+        self.assertIs(c.server_wait, False)
+        self.assertEqual(sum("wait" in query_of(call) for call in t.calls), 1)
+
+    def test_wait_for_job_timeout(self):
+        c, _ = client(lambda r, n: FakeResponse(200, {"job": {"id": "job-1", "status": "processing"}}))
+        with self.assertRaises(RenderlyError) as caught:
+            c.wait_for_job("job-1", interval=0.001, timeout=0.01)
+        self.assertEqual(caught.exception.code, "wait_timeout")
+
+    def test_run_completes_inside_server_wait(self):
+        def handler(r, n):
+            if path_of(r) == "/quotes":
+                return FakeResponse(200, {"quoteId": "quote-1", "credits": 12})
+            return FakeResponse(200, {"job": {"id": "job-1", "status": "completed"}, "balance": 88})
+        c, t = client(handler)
+        self.assertEqual(c.run(model_id="m", operation="o", input={}, max_credits=20)["job"]["status"], "completed")
+        self.assertEqual(len(t.calls), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()