diffusr 0.1.0__tar.gz

diffusr-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+.DS_Store
+node_modules/
+.next/
+.turbo/
+dist/
+.env
+.env.*
+!.env.example
+*.tsbuildinfo
+
+# Trigger.dev CLI local state (builds, locks, watchdog)
+.trigger/
+pw-*.png
+.vercel
+
+# trigger.dev CLI (>=4.5.14) regenerates agent-skill scaffolding on every dev start
+packages/jobs/.agents/
+packages/jobs/.claude/
+packages/jobs/.cursor/
+packages/jobs/AGENTS.md
+packages/jobs/CLAUDE.md
+
+# Herdr foreman briefs handed to workspace agents — never committed
+.brief-*.md
+
+# Director scenario runner output (transcripts per run)
+scripts/director-scenarios/runs/
+
+# Format-refs PNGs live on R2 (scripts/upload-format-refs.ts → refs-manifest.json)
+docs/format-refs/format-templates-export/formats/*/refs/*.png
+docs/format-refs/format-templates-export/formats/*/refs/*.jpg
+
+# Machine notes for Jose's dev boxes (symlinked into worktrees by post-checkout)
+CLAUDE.local.md*

diffusr-0.1.0/LICENSE

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

diffusr-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.5
+Name: diffusr
+Version: 0.1.0
+Summary: The diffusr API client: make videos, images and music from code. Free price checks, idempotent starts, wait_for, signed callbacks.
+Project-URL: Homepage, https://diffusr.ai
+Project-URL: Documentation, https://diffusr.ai/docs
+License: MIT
+License-File: LICENSE
+Keywords: ai,api,diffusr,image,video
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# diffusr
+
+The diffusr API client for Python 3.9+. Make videos, images and music from
+code. Standard library only. Bodies and answers are the API's own snake_case
+JSON (plain dicts).
+
+```sh
+pip install diffusr
+```
+
+## Quickstart
+
+Use a **test key** (`dfsr_test_…`) while you build: prices are quoted exactly,
+nothing is charged, no model runs, and the result is a placeholder file a few
+seconds later. Swap in a live key (`dfsr_live_…`) when you are ready to spend.
+Mint keys on the Developers page in the app.
+
+```python
+from diffusr import Diffusr
+
+diffusr = Diffusr()  # reads DIFFUSR_KEY
+
+# 1. Ask the price. Free: nothing is made, nothing is spent.
+quote = diffusr.make_video(
+    prompt="A can of sparkling water on a wet street, slow push-in, rain",
+    duration_sec=5,
+    dry_run=True,
+)
+print(quote["price"])  # {'credits': 63, 'usd': '0.6300', ...}
+
+# 2. Make it. An Idempotency-Key is added for you and reused on retries,
+#    so a dropped connection never pays twice.
+job = diffusr.make_video(
+    prompt="A can of sparkling water on a wet street, slow push-in, rain",
+    duration_sec=5,
+)
+
+# 3. Wait for it (polls with backoff; raises WAIT_TIMEOUT if it takes too long).
+result = diffusr.wait_for(job["id"], timeout=600)
+if result["status"] == "SUCCEEDED":
+    print(result["output"]["url"])
+else:
+    print(result["status"], result.get("error"))
+print(result["charge"])  # quoted_credits, charged_credits, final
+```
+
+### Callbacks instead of polling
+
+Pass `callback_url` (https, public) and we POST one signed event when the job
+ends. Verify it with your signing secret (`diffusr.get_callback_secret()["secret"]`):
+
+```python
+from diffusr import Diffusr
+
+# Flask: use the RAW body, not the parsed one.
+@app.post("/diffusr")
+def hook():
+    raw = request.get_data(as_text=True)
+    if not Diffusr.verify_callback(raw, request.headers, os.environ["DIFFUSR_WHSEC"]):
+        return "", 400
+    event = json.loads(raw)  # {id, type: "result.finished", data: <result>}
+    return "", 200  # any 2xx; drop repeats of event["id"]
+```
+
+`verify_callback` implements [Standard Webhooks](https://www.standardwebhooks.com):
+constant-time compare, two signatures after a secret rotation, a 5-minute
+timestamp window, `whsec_` prefix handled.
+
+## Methods
+
+| Method | REST |
+|---|---|
+| `make_video`, `make_image`, `edit_image`, `recast`, `make_music`, `creator_video`, `run_template` `(**body)` | `POST /{tool}` |
+| `get_result(id)`, `list_results(limit=)`, `cancel(id)` (stops queued work; a step already generating may finish and be charged: check `result["charge"]`) | `GET /results/{id}`, `GET /results`, `POST /results/{id}/cancel` |
+| `wait_for(id, timeout=, interval=, on_poll=)` | polls `GET /results/{id}` |
+| `upload_file(path_or_bytes, content_type=)`, `upload_from_url(url)` | `POST /uploads` + signed `PUT` |
+| `list_models(kind=)`, `list_templates()` | `GET /models`, `GET /templates` |
+| `list_callbacks(limit=, cursor=)`, `retry_callback(event_id)`, `get_callback_secret()`, `rotate_callback_secret()` | `/callbacks…` |
+| `Diffusr.verify_callback(raw_body, headers, secret)` | |
+
+`run_template` takes one flat body: `template="<id from list_templates()>"` plus the fields that
+template takes (`mode`, `prompt`, `pictures`, `image_urls`, `product_image_url`, `script`, `place`,
+`people`, `setup`, `resolution`):
+
+```python
+diffusr.run_template(template="tpl-ugc-talking-head", script="Hi!", people=[{"name": "Mia", "image_url": "https://…"}], dry_run=True)
+```
+
+`dry_run=True` on any make call answers with the price only. Pass
+`idempotency_key="…"` to use your own key.
+
+## Retries and errors
+
+- Every request times out after 60 s (`Diffusr(timeout=...)`) with a `TIMEOUT` error.
+- `GET`s (and so `wait_for`) retry on 429, 500, 502, 503, 504, network errors
+  and timeouts with backoff, honouring `Retry-After` (waits over 30 s are not
+  slept: the error is raised).
+- Make calls retry on 429, 503, network errors and timeouts only, **with the
+  same Idempotency-Key**.
+- Every failure is a `DiffusrError`:
+
+```python
+from diffusr import DiffusrError
+
+try:
+    diffusr.make_video(prompt="…")
+except DiffusrError as e:
+    print(e.status, e.code, e.message, e.request_id, e.retry_after)
+    # e.body has the extras: issues, field, budget…
+```
+
+Codes are the API's (`RATE_LIMITED`, `BUDGET_EXCEEDED`, `INSUFFICIENT_CREDITS`…).
+The SDK adds `NETWORK_ERROR`, `TIMEOUT`, `WAIT_TIMEOUT`, `UPLOAD_FAILED`,
+`CONTENT_TYPE_REQUIRED` and `MISSING_API_KEY`. Handle codes you don't know.
+
+## Docs
+
+Full API reference, prices and agent guides: https://diffusr.ai/docs
+
+MIT licensed.

diffusr-0.1.0/README.md

@@ -0,0 +1,120 @@
+# diffusr
+
+The diffusr API client for Python 3.9+. Make videos, images and music from
+code. Standard library only. Bodies and answers are the API's own snake_case
+JSON (plain dicts).
+
+```sh
+pip install diffusr
+```
+
+## Quickstart
+
+Use a **test key** (`dfsr_test_…`) while you build: prices are quoted exactly,
+nothing is charged, no model runs, and the result is a placeholder file a few
+seconds later. Swap in a live key (`dfsr_live_…`) when you are ready to spend.
+Mint keys on the Developers page in the app.
+
+```python
+from diffusr import Diffusr
+
+diffusr = Diffusr()  # reads DIFFUSR_KEY
+
+# 1. Ask the price. Free: nothing is made, nothing is spent.
+quote = diffusr.make_video(
+    prompt="A can of sparkling water on a wet street, slow push-in, rain",
+    duration_sec=5,
+    dry_run=True,
+)
+print(quote["price"])  # {'credits': 63, 'usd': '0.6300', ...}
+
+# 2. Make it. An Idempotency-Key is added for you and reused on retries,
+#    so a dropped connection never pays twice.
+job = diffusr.make_video(
+    prompt="A can of sparkling water on a wet street, slow push-in, rain",
+    duration_sec=5,
+)
+
+# 3. Wait for it (polls with backoff; raises WAIT_TIMEOUT if it takes too long).
+result = diffusr.wait_for(job["id"], timeout=600)
+if result["status"] == "SUCCEEDED":
+    print(result["output"]["url"])
+else:
+    print(result["status"], result.get("error"))
+print(result["charge"])  # quoted_credits, charged_credits, final
+```
+
+### Callbacks instead of polling
+
+Pass `callback_url` (https, public) and we POST one signed event when the job
+ends. Verify it with your signing secret (`diffusr.get_callback_secret()["secret"]`):
+
+```python
+from diffusr import Diffusr
+
+# Flask: use the RAW body, not the parsed one.
+@app.post("/diffusr")
+def hook():
+    raw = request.get_data(as_text=True)
+    if not Diffusr.verify_callback(raw, request.headers, os.environ["DIFFUSR_WHSEC"]):
+        return "", 400
+    event = json.loads(raw)  # {id, type: "result.finished", data: <result>}
+    return "", 200  # any 2xx; drop repeats of event["id"]
+```
+
+`verify_callback` implements [Standard Webhooks](https://www.standardwebhooks.com):
+constant-time compare, two signatures after a secret rotation, a 5-minute
+timestamp window, `whsec_` prefix handled.
+
+## Methods
+
+| Method | REST |
+|---|---|
+| `make_video`, `make_image`, `edit_image`, `recast`, `make_music`, `creator_video`, `run_template` `(**body)` | `POST /{tool}` |
+| `get_result(id)`, `list_results(limit=)`, `cancel(id)` (stops queued work; a step already generating may finish and be charged: check `result["charge"]`) | `GET /results/{id}`, `GET /results`, `POST /results/{id}/cancel` |
+| `wait_for(id, timeout=, interval=, on_poll=)` | polls `GET /results/{id}` |
+| `upload_file(path_or_bytes, content_type=)`, `upload_from_url(url)` | `POST /uploads` + signed `PUT` |
+| `list_models(kind=)`, `list_templates()` | `GET /models`, `GET /templates` |
+| `list_callbacks(limit=, cursor=)`, `retry_callback(event_id)`, `get_callback_secret()`, `rotate_callback_secret()` | `/callbacks…` |
+| `Diffusr.verify_callback(raw_body, headers, secret)` | |
+
+`run_template` takes one flat body: `template="<id from list_templates()>"` plus the fields that
+template takes (`mode`, `prompt`, `pictures`, `image_urls`, `product_image_url`, `script`, `place`,
+`people`, `setup`, `resolution`):
+
+```python
+diffusr.run_template(template="tpl-ugc-talking-head", script="Hi!", people=[{"name": "Mia", "image_url": "https://…"}], dry_run=True)
+```
+
+`dry_run=True` on any make call answers with the price only. Pass
+`idempotency_key="…"` to use your own key.
+
+## Retries and errors
+
+- Every request times out after 60 s (`Diffusr(timeout=...)`) with a `TIMEOUT` error.
+- `GET`s (and so `wait_for`) retry on 429, 500, 502, 503, 504, network errors
+  and timeouts with backoff, honouring `Retry-After` (waits over 30 s are not
+  slept: the error is raised).
+- Make calls retry on 429, 503, network errors and timeouts only, **with the
+  same Idempotency-Key**.
+- Every failure is a `DiffusrError`:
+
+```python
+from diffusr import DiffusrError
+
+try:
+    diffusr.make_video(prompt="…")
+except DiffusrError as e:
+    print(e.status, e.code, e.message, e.request_id, e.retry_after)
+    # e.body has the extras: issues, field, budget…
+```
+
+Codes are the API's (`RATE_LIMITED`, `BUDGET_EXCEEDED`, `INSUFFICIENT_CREDITS`…).
+The SDK adds `NETWORK_ERROR`, `TIMEOUT`, `WAIT_TIMEOUT`, `UPLOAD_FAILED`,
+`CONTENT_TYPE_REQUIRED` and `MISSING_API_KEY`. Handle codes you don't know.
+
+## Docs
+
+Full API reference, prices and agent guides: https://diffusr.ai/docs
+
+MIT licensed.

diffusr-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "diffusr"
+version = "0.1.0"
+description = "The diffusr API client: make videos, images and music from code. Free price checks, idempotent starts, wait_for, signed callbacks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+keywords = ["diffusr", "video", "image", "ai", "api"]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://diffusr.ai"
+Documentation = "https://diffusr.ai/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/diffusr"]

diffusr-0.1.0/src/diffusr/__init__.py

@@ -0,0 +1,20 @@
+"""The diffusr API client. Stdlib only.
+
+    from diffusr import Diffusr
+    d = Diffusr()  # reads DIFFUSR_KEY
+    quote = d.make_video(prompt="...", dry_run=True)   # free
+"""
+
+from ._client import DEFAULT_BASE_URL, TERMINAL_STATUSES, Diffusr
+from ._errors import DiffusrError
+from ._verify import SIGNATURE_TOLERANCE_SEC, verify_callback
+
+__all__ = [
+    "Diffusr",
+    "DiffusrError",
+    "verify_callback",
+    "DEFAULT_BASE_URL",
+    "TERMINAL_STATUSES",
+    "SIGNATURE_TOLERANCE_SEC",
+]
+__version__ = "0.1.0"

diffusr-0.1.0/src/diffusr/_client.py

@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Callable, Dict, Mapping, Optional, Union
+
+from ._errors import DiffusrError
+from ._verify import verify_callback as _verify_callback
+
+DEFAULT_BASE_URL = "https://app.diffusr.ai/api/v2"
+SDK_VERSION = "0.1.0"
+TERMINAL_STATUSES = ("SUCCEEDED", "FAILED", "CANCELED")
+# Never sleep longer than this on one automatic retry; raise instead.
+MAX_AUTO_RETRY_WAIT_SEC = 30
+
+_CONTENT_TYPES = {
+    ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp",
+    ".gif": "image/gif", ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm",
+    ".mp3": "audio/mpeg", ".wav": "audio/wav", ".m4a": "audio/mp4",
+}
+
+
+class Diffusr:
+    """Client for the diffusr REST API (v2). Bodies and answers are the API's own snake_case JSON.
+
+    api_key   dfsr_live_... or dfsr_test_... (free). Default: the DIFFUSR_KEY environment variable.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        *,
+        max_retries: int = 3,
+        retry_base: float = 0.5,
+        timeout: float = 60.0,
+    ) -> None:
+        key = api_key or os.environ.get("DIFFUSR_KEY")
+        if not key:
+            raise DiffusrError(0, "MISSING_API_KEY", "Pass an API key or set DIFFUSR_KEY.")
+        self._key = key
+        self._base = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._max_retries = max_retries
+        self._retry_base = retry_base
+        self._timeout = timeout
+
+    # ——— make calls (paid; dry_run=True is free) ———
+
+    def make_video(self, **body: Any) -> Dict[str, Any]:
+        return self._make("make_video", body)
+
+    def make_image(self, **body: Any) -> Dict[str, Any]:
+        return self._make("make_image", body)
+
+    def edit_image(self, **body: Any) -> Dict[str, Any]:
+        return self._make("edit_image", body)
+
+    def recast(self, **body: Any) -> Dict[str, Any]:
+        return self._make("recast", body)
+
+    def make_music(self, **body: Any) -> Dict[str, Any]:
+        return self._make("make_music", body)
+
+    def creator_video(self, **body: Any) -> Dict[str, Any]:
+        return self._make("creator_video", body)
+
+    def run_template(self, **body: Any) -> Dict[str, Any]:
+        """Run one of diffusr's templates. One flat body: template="<id from list_templates()>",
+        plus the fields that template takes (mode, prompt, pictures, image_urls, product_image_url,
+        script, place, people, setup, resolution, dry_run, callback_url)."""
+        return self._make("run_template", body)
+
+    def _make(self, tool: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        # One Idempotency-Key per call, reused by every automatic retry.
+        key = body.pop("idempotency_key", None) or str(uuid.uuid4())
+        return self._request("POST", f"/{tool}", body=body, headers={"Idempotency-Key": key})
+
+    # ——— results ———
+
+    def get_result(self, id: str) -> Dict[str, Any]:
+        return self._request("GET", f"/results/{urllib.parse.quote(id, safe='')}")
+
+    def list_results(self, limit: Optional[int] = None) -> Dict[str, Any]:
+        return self._request("GET", "/results" + _query(limit=limit))
+
+    def cancel(self, id: str) -> Dict[str, Any]:
+        """Stop queued work before it generates (that part is never charged).
+
+        A step that is already generating may still finish and be charged: check
+        result["charge"] on the answer. A finished job comes back unchanged.
+        """
+        return self._request("POST", f"/results/{urllib.parse.quote(id, safe='')}/cancel", body={})
+
+    def wait_for(
+        self,
+        id: str,
+        timeout: float = 900.0,
+        interval: float = 3.0,
+        on_poll: Optional[Callable[[Dict[str, Any]], None]] = None,
+    ) -> Dict[str, Any]:
+        """Poll until the job is over and return the result (seconds, not ms).
+
+        A job that ends FAILED or CANCELED is returned too: check result["status"].
+        Raises DiffusrError(code="WAIT_TIMEOUT") if it is still running at the
+        deadline (the job itself keeps going).
+        """
+        deadline = time.monotonic() + timeout
+        pause = interval
+        while True:
+            result = self.get_result(id)
+            if on_poll:
+                on_poll(result)
+            if result.get("status") in TERMINAL_STATUSES:
+                return result
+            left = deadline - time.monotonic()
+            if left <= 0:
+                break
+            time.sleep(min(pause, left))
+            pause = min(pause * 1.5, max(15.0, interval))
+            if time.monotonic() >= deadline:
+                break
+        raise DiffusrError(
+            0,
+            "WAIT_TIMEOUT",
+            f"Result {id} was still not finished after {int(timeout)} s. It keeps running: call wait_for or get_result again.",
+        )
+
+    # ——— files ———
+
+    def upload_file(
+        self, file: Union[str, "os.PathLike[str]", bytes, bytearray], content_type: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Upload a local file (a path, or bytes) and get a file_url to pass to a tool.
+
+        Two steps: ask for a signed URL, PUT the exact bytes to it.
+        """
+        if isinstance(file, (bytes, bytearray)):
+            data = bytes(file)
+        else:
+            path = os.fspath(file)
+            with open(path, "rb") as f:
+                data = f.read()
+            content_type = content_type or _CONTENT_TYPES.get(os.path.splitext(path)[1].lower()) or mimetypes.guess_type(path)[0]
+        if not content_type:
+            raise DiffusrError(0, "CONTENT_TYPE_REQUIRED", 'Pass content_type (e.g. "video/mp4"): it could not be worked out.')
+        ticket = self._request("POST", "/uploads", body={"content_type": content_type, "size_bytes": len(data)})
+        req = urllib.request.Request(ticket["upload_url"], data=data, method=ticket.get("method", "PUT"))
+        for k, v in ticket.get("headers", {}).items():
+            req.add_header(k, v)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout):
+                pass
+        except urllib.error.HTTPError as e:
+            raise DiffusrError(e.code, "UPLOAD_FAILED", f"The upload PUT failed with HTTP {e.code}.") from None
+        except urllib.error.URLError as e:
+            raise DiffusrError(0, "NETWORK_ERROR", f"The upload PUT failed: {e.reason}") from None
+        return {"file_url": ticket["file_url"], "kind": ticket.get("kind")}
+
+    def upload_from_url(self, source_url: str) -> Dict[str, Any]:
+        """Have us copy a public link in (images and short clips; use upload_file for big videos)."""
+        return self._request("POST", "/uploads", body={"source_url": source_url})
+
+    # ——— catalog ———
+
+    def list_models(self, kind: Optional[str] = None) -> Dict[str, Any]:
+        return self._request("GET", "/models" + _query(kind=kind))
+
+    def list_templates(self) -> Dict[str, Any]:
+        return self._request("GET", "/templates")
+
+    # ——— callbacks ———
+
+    def list_callbacks(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._request("GET", "/callbacks" + _query(limit=limit, cursor=cursor))
+
+    def retry_callback(self, event_id: str) -> Dict[str, Any]:
+        """One more try for a FAILED event (up to 3 by hand)."""
+        return self._request("POST", f"/callbacks/{urllib.parse.quote(event_id, safe='')}/retry", body={})
+
+    def get_callback_secret(self) -> Dict[str, Any]:
+        """Your signing secret (whsec_...) for Diffusr.verify_callback."""
+        return self._request("GET", "/callbacks/secret")
+
+    def rotate_callback_secret(self) -> Dict[str, Any]:
+        return self._request("POST", "/callbacks/secret/rotate", body={})
+
+    @staticmethod
+    def verify_callback(
+        raw_body: Union[str, bytes],
+        headers: Mapping[str, str],
+        secret: str,
+        tolerance_sec: int = 300,
+        now: Optional[float] = None,
+    ) -> bool:
+        """Check a callback's signature (Standard Webhooks). Rejects a timestamp more than 5 minutes off."""
+        return _verify_callback(raw_body, headers, secret, tolerance_sec, now)
+
+    # ——— plumbing ———
+
+    def _backoff(self, attempt: int) -> float:
+        return self._retry_base * (2**attempt)
+
+    def _request(
+        self, method: str, path: str, body: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None
+    ) -> Dict[str, Any]:
+        hdrs = {
+            "Authorization": f"Bearer {self._key}",
+            "Accept": "application/json",
+            "User-Agent": f"diffusr-python/{SDK_VERSION}",
+        }
+        data = None
+        if body is not None:
+            hdrs["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        hdrs.update(headers or {})
+
+        attempt = 0
+        while True:
+            req = urllib.request.Request(self._base + path, data=data, method=method, headers=hdrs)
+            try:
+                with urllib.request.urlopen(req, timeout=self._timeout) as res:
+                    text = res.read().decode("utf-8")
+                    return json.loads(text) if text else {}
+            except urllib.error.HTTPError as e:
+                err = _to_error(e)
+                wait = err.retry_after if err.retry_after is not None else self._backoff(attempt)
+                retryable = e.code in (429, 503) or (method == "GET" and e.code in (500, 502, 504))
+                if retryable and attempt < self._max_retries and wait <= MAX_AUTO_RETRY_WAIT_SEC:
+                    time.sleep(wait)
+                    attempt += 1
+                    continue
+                raise err from None
+            except (urllib.error.URLError, OSError) as e:
+                # OSError covers socket.timeout (a separate class before 3.10), TimeoutError, ConnectionError.
+                if attempt < self._max_retries:
+                    time.sleep(self._backoff(attempt))
+                    attempt += 1
+                    continue
+                reason = getattr(e, "reason", e)
+                if _is_timeout(e) or _is_timeout(reason):
+                    raise DiffusrError(0, "TIMEOUT", f"diffusr did not answer within {self._timeout:g} s.") from None
+                raise DiffusrError(0, "NETWORK_ERROR", f"Could not reach diffusr: {reason}") from None
+
+
+def _is_timeout(e: Any) -> bool:
+    return isinstance(e, (socket.timeout, TimeoutError))
+
+
+def _query(**params: Any) -> str:
+    q = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+    return f"?{q}" if q else ""
+
+
+def _to_error(e: urllib.error.HTTPError) -> DiffusrError:
+    text = ""
+    try:
+        text = e.read().decode("utf-8", "replace")
+    except Exception:
+        pass
+    body: Optional[Dict[str, Any]] = None
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict):
+            body = parsed
+    except ValueError:
+        pass
+    retry_after: Optional[float] = None
+    header = e.headers.get("Retry-After") if e.headers else None
+    if header is not None:
+        try:
+            retry_after = float(header)
+        except ValueError:
+            pass
+    if retry_after is None and body and isinstance(body.get("retry_after_seconds"), (int, float)):
+        retry_after = float(body["retry_after_seconds"])
+    message = body["error"] if body and isinstance(body.get("error"), str) else (text[:300] or f"HTTP {e.code}")
+    code = body["code"] if body and isinstance(body.get("code"), str) else f"HTTP_{e.code}"
+    request_id = body.get("request_id") if body and isinstance(body.get("request_id"), str) else None
+    request_id = request_id or (e.headers.get("X-Request-Id") if e.headers else None)
+    return DiffusrError(e.code, code, message, request_id, retry_after, body)

diffusr-0.1.0/src/diffusr/_errors.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class DiffusrError(Exception):
+    """Every non-2xx answer (and a few client-side failures) raises this.
+
+    status       HTTP status; 0 when no answer came (network error, wait timeout)
+    code         the API's machine code, e.g. "RATE_LIMITED"
+    message      the API's plain-words error
+    request_id   quote it to support
+    retry_after  seconds to wait before trying again, when the API said so
+    body         the whole JSON error body (field, issues, budget...)
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        body: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        self.retry_after = retry_after
+        self.body = body
+
+    def __str__(self) -> str:
+        rid = f" (request_id {self.request_id})" if self.request_id else ""
+        return f"[{self.code}] {self.message}{rid}"

diffusr-0.1.0/src/diffusr/_verify.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import time
+from typing import Mapping, Optional, Union
+
+SIGNATURE_TOLERANCE_SEC = 300
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    for k, v in headers.items():
+        if k.lower() == name:
+            return v if isinstance(v, str) else " ".join(v)
+    return None
+
+
+def verify_callback(
+    raw_body: Union[str, bytes],
+    headers: Mapping[str, str],
+    secret: str,
+    tolerance_sec: int = SIGNATURE_TOLERANCE_SEC,
+    now: Optional[float] = None,
+) -> bool:
+    """Check a diffusr callback (Standard Webhooks).
+
+    raw_body is the request body exactly as received, before JSON parsing.
+    Returns False for a missing header, a bad or stale signature; never raises.
+    """
+    try:
+        msg_id = _header(headers, "webhook-id")
+        timestamp = _header(headers, "webhook-timestamp")
+        signature = _header(headers, "webhook-signature")
+        if not msg_id or not timestamp or not signature or not timestamp.isdigit():
+            return False
+        current = time.time() if now is None else now
+        if abs(int(current) - int(timestamp)) > tolerance_sec:
+            return False
+        body = raw_body if isinstance(raw_body, (bytes, bytearray)) else raw_body.encode("utf-8")
+        key = base64.b64decode(secret[6:] if secret.startswith("whsec_") else secret)
+        expected = hmac.new(key, f"{msg_id}.{timestamp}.".encode("utf-8") + bytes(body), hashlib.sha256).digest()
+        ok = False
+        for part in signature.split(" "):
+            if not part.startswith("v1,"):
+                continue
+            try:
+                given = base64.b64decode(part[3:], validate=True)
+            except (binascii.Error, ValueError):
+                continue
+            if hmac.compare_digest(given, expected):
+                ok = True
+        return ok
+    except Exception:
+        return False

diffusr-0.1.0/tests/test_client.py

@@ -0,0 +1,336 @@
+import base64
+import hashlib
+import hmac
+import json
+import os
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+from diffusr import Diffusr, DiffusrError  # noqa: E402
+
+VECTORS = os.path.join(os.path.dirname(__file__), "..", "..", "test-vectors", "callbacks.json")
+
+
+class Mock:
+    """A local HTTP server; `handler(req, n)` returns (status, body, headers)."""
+
+    def __init__(self):
+        self.seen = []
+        self.handler = lambda req, n: (200, {}, {})
+        mock = self
+
+        class H(BaseHTTPRequestHandler):
+            def _do(self):
+                length = int(self.headers.get("Content-Length") or 0)
+                raw = self.rfile.read(length) if length else b""
+                req = {"method": self.command, "path": self.path, "headers": self.headers, "body": raw}
+                mock.seen.append(req)
+                status, body, headers = mock.handler(req, len(mock.seen))
+                payload = b"" if body is None else (body if isinstance(body, bytes) else json.dumps(body).encode())
+                self.send_response(status)
+                self.send_header("Content-Length", str(len(payload)))
+                for k, v in headers.items():
+                    self.send_header(k, v)
+                self.end_headers()
+                try:
+                    self.wfile.write(payload)
+                except (BrokenPipeError, ConnectionResetError):
+                    pass  # the client gave up (timeout tests)
+
+            do_GET = do_POST = do_PUT = _do
+
+            def log_message(self, *a):
+                pass
+
+        self.server = HTTPServer(("127.0.0.1", 0), H)
+        self.root = f"http://127.0.0.1:{self.server.server_port}"
+        self.base = self.root + "/api/v2"
+        self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+        self.thread.start()
+
+    def close(self):
+        self.server.shutdown()
+        self.server.server_close()
+
+
+def result(status):
+    return {"id": "r1", "status": status, "model": "m", "created_at": "now",
+            "charge": {"quoted_credits": 5, "charged_credits": 0, "final": False}}
+
+
+class ClientTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.mock = Mock()
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.mock.close()
+
+    def setUp(self):
+        self.mock.seen = []
+        self.mock.handler = lambda req, n: (200, {}, {})
+
+    def client(self, **kw):
+        return Diffusr("dfsr_test_abc", self.mock.base, retry_base=0.001, **kw)
+
+    def test_every_method_hits_the_right_path(self):
+        d = self.client()
+        cases = [
+            (lambda: d.make_video(prompt="p"), "POST", "/make_video"),
+            (lambda: d.make_image(prompt="p"), "POST", "/make_image"),
+            (lambda: d.edit_image(prompt="p", image_urls=["https://x/a.png"]), "POST", "/edit_image"),
+            (lambda: d.recast(video_url="https://x/a.mp4", mode="swap"), "POST", "/recast"),
+            (lambda: d.make_music(prompt="p"), "POST", "/make_music"),
+            (lambda: d.creator_video(creator_id="c", script="s"), "POST", "/creator_video"),
+            (lambda: d.run_template(template="t", prompt="p"), "POST", "/run_template"),
+            (lambda: d.get_result("r 1"), "GET", "/results/r%201"),
+            (lambda: d.list_results(limit=5), "GET", "/results?limit=5"),
+            (lambda: d.cancel("r1"), "POST", "/results/r1/cancel"),
+            (lambda: d.list_models(kind="video"), "GET", "/models?kind=video"),
+            (lambda: d.list_templates(), "GET", "/templates"),
+            (lambda: d.list_callbacks(limit=2, cursor="c"), "GET", "/callbacks?limit=2&cursor=c"),
+            (lambda: d.retry_callback("evt_1"), "POST", "/callbacks/evt_1/retry"),
+            (lambda: d.get_callback_secret(), "GET", "/callbacks/secret"),
+            (lambda: d.rotate_callback_secret(), "POST", "/callbacks/secret/rotate"),
+            (lambda: d.upload_from_url("https://x/a.png"), "POST", "/uploads"),
+        ]
+        for call, method, path in cases:
+            with self.subTest(path=path):
+                self.mock.seen = []
+                call()
+                s = self.mock.seen[0]
+                self.assertEqual(s["method"], method)
+                self.assertEqual(s["path"], "/api/v2" + path)
+                self.assertEqual(s["headers"]["Authorization"], "Bearer dfsr_test_abc")
+                self.assertTrue(s["headers"]["User-Agent"].startswith("diffusr-python/"))
+                if method == "POST":
+                    self.assertEqual(s["headers"]["Content-Type"], "application/json")
+
+    def test_body_passes_through_and_idempotency_key_moves_to_header(self):
+        self.client().make_video(prompt="p", duration_sec=8, callback_url="https://x/cb", idempotency_key="mine-1")
+        s = self.mock.seen[0]
+        self.assertEqual(json.loads(s["body"]), {"prompt": "p", "duration_sec": 8, "callback_url": "https://x/cb"})
+        self.assertEqual(s["headers"]["Idempotency-Key"], "mine-1")
+
+    def test_a_key_is_generated_and_differs_per_call(self):
+        d = self.client()
+        d.make_image(prompt="p")
+        d.make_image(prompt="p")
+        a, b = (s["headers"]["Idempotency-Key"] for s in self.mock.seen)
+        self.assertGreaterEqual(len(a), 8)
+        self.assertNotEqual(a, b)
+
+    def test_dry_run_answer(self):
+        self.mock.handler = lambda r, n: (200, {"dry_run": True, "credits_estimated": 12, "note": "n"}, {})
+        out = self.client().make_video(prompt="p", dry_run=True)
+        self.assertTrue(json.loads(self.mock.seen[0]["body"])["dry_run"])
+        self.assertEqual(out["credits_estimated"], 12)
+
+    def test_env_key(self):
+        old = os.environ.pop("DIFFUSR_KEY", None)
+        try:
+            with self.assertRaises(DiffusrError):
+                Diffusr()
+            os.environ["DIFFUSR_KEY"] = "dfsr_test_env"
+            Diffusr()
+        finally:
+            os.environ.pop("DIFFUSR_KEY", None)
+            if old is not None:
+                os.environ["DIFFUSR_KEY"] = old
+
+    def test_error_mapping(self):
+        self.mock.handler = lambda r, n: (
+            402, {"error": "Over the daily limit", "code": "BUDGET_EXCEEDED", "request_id": "req_1", "budget": {"limit": "key"}}, {})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client().make_image(prompt="p")
+        e = cm.exception
+        self.assertEqual((e.status, e.code, e.message, e.request_id), (402, "BUDGET_EXCEEDED", "Over the daily limit", "req_1"))
+        self.assertEqual(e.body["budget"], {"limit": "key"})
+        self.assertEqual(len(self.mock.seen), 1)
+
+    def test_retry_after_header_and_body_fallback(self):
+        self.mock.handler = lambda r, n: (429, {"error": "slow", "code": "CONCURRENCY_LIMIT", "request_id": "req_2"}, {"Retry-After": "15"})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client(max_retries=0).get_result("r1")
+        self.assertEqual(cm.exception.retry_after, 15)
+        self.mock.handler = lambda r, n: (503, {"error": "paused", "code": "API_PAUSED", "retry_after_seconds": 300}, {"X-Request-Id": "req_h"})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client(max_retries=0).get_result("r1")
+        self.assertEqual((cm.exception.retry_after, cm.exception.request_id), (300, "req_h"))
+
+    def test_non_json_error(self):
+        self.mock.handler = lambda r, n: (502, b"bad gateway", {})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client().get_result("r1")
+        self.assertEqual((cm.exception.status, cm.exception.code, cm.exception.message), (502, "HTTP_502", "bad gateway"))
+
+    def test_get_retries_429_then_503(self):
+        def h(r, n):
+            if n == 1:
+                return 429, {"error": "x", "code": "RATE_LIMITED"}, {"Retry-After": "0"}
+            if n == 2:
+                return 503, {"error": "x", "code": "WALLET_BUSY"}, {}
+            return 200, result("PENDING"), {}
+        self.mock.handler = h
+        self.assertEqual(self.client().get_result("r1")["id"], "r1")
+        self.assertEqual(len(self.mock.seen), 3)
+
+    def test_make_retry_reuses_the_idempotency_key(self):
+        def h(r, n):
+            if n < 3:
+                return 503, {"error": "busy", "code": "WALLET_BUSY"}, {"Retry-After": "0"}
+            return 202, {"id": "r1", "status": "PENDING", "credits_estimated": 3, "next": ""}, {}
+        self.mock.handler = h
+        self.assertEqual(self.client().make_video(prompt="p")["id"], "r1")
+        keys = {s["headers"]["Idempotency-Key"] for s in self.mock.seen}
+        self.assertEqual(len(self.mock.seen), 3)
+        self.assertEqual(len(keys), 1)
+
+    def test_other_errors_are_not_retried_and_retries_are_bounded(self):
+        self.mock.handler = lambda r, n: (422, {"error": "bad", "code": "VALIDATION_FAILED"}, {})
+        with self.assertRaises(DiffusrError):
+            self.client().make_video(prompt="")
+        self.assertEqual(len(self.mock.seen), 1)
+        self.mock.seen = []
+        self.mock.handler = lambda r, n: (503, {"error": "x", "code": "WALLET_BUSY"}, {"Retry-After": "0"})
+        with self.assertRaises(DiffusrError):
+            self.client(max_retries=2).get_result("r1")
+        self.assertEqual(len(self.mock.seen), 3)
+
+    def test_long_retry_after_is_not_slept(self):
+        self.mock.handler = lambda r, n: (429, {"error": "x", "code": "CONCURRENCY_LIMIT"}, {"Retry-After": "300"})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client().get_result("r1")
+        self.assertEqual(cm.exception.retry_after, 300)
+        self.assertEqual(len(self.mock.seen), 1)
+
+    def test_run_template_posts_flat_template(self):
+        self.client().run_template(template="tpl-x", mode="remix", pictures={"him": "https://x/a.png"}, dry_run=True)
+        sent = json.loads(self.mock.seen[0]["body"])
+        self.assertEqual(sent, {"template": "tpl-x", "mode": "remix", "pictures": {"him": "https://x/a.png"}, "dry_run": True})
+
+    def test_get_retries_5xx_but_make_does_not(self):
+        for status in (500, 502, 504):
+            self.mock.seen = []
+            self.mock.handler = lambda r, n, s=status: (s, {"error": "x", "code": "BOOM"}, {}) if n < 2 else (200, result("RUNNING"), {})
+            self.assertEqual(self.client().get_result("r1")["status"], "RUNNING")
+            self.assertEqual(len(self.mock.seen), 2)
+        self.mock.seen = []
+        self.mock.handler = lambda r, n: (502, {"error": "x", "code": "BOOM"}, {})
+        with self.assertRaises(DiffusrError):
+            self.client().make_image(prompt="p")
+        self.assertEqual(len(self.mock.seen), 1)
+
+    def test_timeout_code_and_same_idempotency_key(self):
+        def slow(r, n):
+            time.sleep(0.3)
+            return 200, {}, {}
+        self.mock.handler = slow
+        d = Diffusr("k", self.mock.base, max_retries=1, retry_base=0.001, timeout=0.05)
+        with self.assertRaises(DiffusrError) as cm:
+            d.make_image(prompt="p")
+        self.assertEqual((cm.exception.status, cm.exception.code), (0, "TIMEOUT"))
+        time.sleep(0.7)  # let the slow handlers finish
+        self.assertEqual(len(self.mock.seen), 2)
+        keys = {s["headers"]["Idempotency-Key"] for s in self.mock.seen}
+        self.assertEqual(len(keys), 1)
+
+    def test_network_error(self):
+        d = Diffusr("k", "http://127.0.0.1:1/api/v2", max_retries=1, retry_base=0.001)
+        with self.assertRaises(DiffusrError) as cm:
+            d.get_result("r1")
+        self.assertEqual((cm.exception.status, cm.exception.code), (0, "NETWORK_ERROR"))
+
+    # ——— wait_for ———
+
+    def test_wait_for_terminal(self):
+        self.mock.handler = lambda r, n: (200, result("RUNNING" if n < 3 else "SUCCEEDED"), {})
+        seen = []
+        out = self.client().wait_for("r1", interval=0.005, on_poll=lambda x: seen.append(x["status"]))
+        self.assertEqual(out["status"], "SUCCEEDED")
+        self.assertEqual(seen, ["RUNNING", "RUNNING", "SUCCEEDED"])
+
+    def test_wait_for_returns_failed_and_canceled(self):
+        for status in ("FAILED", "CANCELED"):
+            self.mock.handler = lambda r, n, s=status: (200, result(s), {})
+            self.assertEqual(self.client().wait_for("r1", interval=0.001)["status"], status)
+
+    def test_wait_for_times_out(self):
+        self.mock.handler = lambda r, n: (200, result("RUNNING"), {})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client().wait_for("r1", interval=0.005, timeout=0.06)
+        self.assertEqual(cm.exception.code, "WAIT_TIMEOUT")
+
+    # ——— upload ———
+
+    def _ticket(self, n):
+        return {"upload_url": f"{self.mock.root}/put/{n}", "method": "PUT", "headers": {"Content-Type": "video/mp4"},
+                "file_url": "https://media.diffusr.ai/uploads/u/1.mp4", "kind": "video", "expires_in_sec": 900, "curl": "", "next": ""}
+
+    def test_upload_bytes(self):
+        self.mock.handler = lambda r, n: (201, self._ticket(1), {}) if r["path"] == "/api/v2/uploads" else (200, None, {})
+        out = self.client().upload_file(b"0123456789", content_type="video/mp4")
+        self.assertEqual(out["file_url"], "https://media.diffusr.ai/uploads/u/1.mp4")
+        self.assertEqual(json.loads(self.mock.seen[0]["body"]), {"content_type": "video/mp4", "size_bytes": 10})
+        put = self.mock.seen[1]
+        self.assertEqual((put["method"], put["body"]), ("PUT", b"0123456789"))
+        self.assertEqual(put["headers"]["Content-Type"], "video/mp4")
+        self.assertEqual(put["headers"]["Content-Length"], "10")
+        self.assertIsNone(put["headers"]["Authorization"])
+
+    def test_upload_path(self):
+        self.mock.handler = lambda r, n: (201, self._ticket(2), {}) if r["path"] == "/api/v2/uploads" else (200, None, {})
+        with tempfile.TemporaryDirectory() as tmp:
+            p = os.path.join(tmp, "clip.mp4")
+            with open(p, "wb") as f:
+                f.write(b"abc")
+            self.client().upload_file(p)
+        self.assertEqual(json.loads(self.mock.seen[0]["body"]), {"content_type": "video/mp4", "size_bytes": 3})
+
+    def test_upload_needs_type_and_reports_failed_put(self):
+        with self.assertRaises(DiffusrError) as cm:
+            self.client().upload_file(b"x")
+        self.assertEqual(cm.exception.code, "CONTENT_TYPE_REQUIRED")
+        self.assertEqual(len(self.mock.seen), 0)
+        self.mock.handler = lambda r, n: (201, self._ticket(4), {}) if r["path"] == "/api/v2/uploads" else (403, None, {})
+        with self.assertRaises(DiffusrError) as cm:
+            self.client().upload_file(b"x", content_type="video/mp4")
+        self.assertEqual((cm.exception.code, cm.exception.status), ("UPLOAD_FAILED", 403))
+
+
+class VerifyTests(unittest.TestCase):
+    def test_shared_vectors(self):
+        with open(VECTORS) as f:
+            cases = json.load(f)["cases"]
+        self.assertGreater(len(cases), 10)
+        for c in cases:
+            with self.subTest(c["name"]):
+                self.assertEqual(Diffusr.verify_callback(c["body"], c["headers"], c["secret"], now=c["now"]), c["expected"])
+
+    def test_fresh_signature_real_clock_and_bytes_body(self):
+        secret = "whsec_" + base64.b64encode(b"fresh-secret").decode()
+        ts = str(int(time.time()))
+        body = '{"id":"evt_9"}'
+        mac = hmac.new(base64.b64decode(secret[6:]), f"evt_9.{ts}.{body}".encode(), hashlib.sha256).digest()
+        headers = {"webhook-id": "evt_9", "webhook-timestamp": ts, "webhook-signature": "v1," + base64.b64encode(mac).decode()}
+        self.assertTrue(Diffusr.verify_callback(body, headers, secret))
+        self.assertTrue(Diffusr.verify_callback(body.encode(), headers, secret))
+        self.assertFalse(Diffusr.verify_callback(body + " ", headers, secret))
+        # bytes that are not valid UTF-8 are signed as bytes, never decoded
+        raw = b'{"x":"\xff\xfe"}'
+        mac = hmac.new(base64.b64decode(secret[6:]), b"evt_9." + ts.encode() + b"." + raw, hashlib.sha256).digest()
+        h2 = dict(headers, **{"webhook-signature": "v1," + base64.b64encode(mac).decode()})
+        self.assertTrue(Diffusr.verify_callback(raw, h2, secret))
+        old = dict(headers, **{"webhook-timestamp": str(int(time.time()) - 3600)})
+        self.assertFalse(Diffusr.verify_callback(body, old, secret))
+
+
+if __name__ == "__main__":
+    unittest.main()