runmux 0.1.0__tar.gz

runmux-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+build/
+*.log
+.pytest_cache/

runmux-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: runmux
+Version: 0.1.0
+Summary: Official RunMux Python SDK — video generation (Seedance 2.0) and the face asset library, with submit-and-wait helpers so you never hand-roll polling.
+Project-URL: Homepage, https://runmux.com
+Author: RunMux
+License: MIT
+Keywords: ai-video,runmux,sdk,seedance,video-generation
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# runmux
+
+Official Python SDK for **RunMux** — generate video with Seedance 2.0 and manage the
+face asset library, without hand-rolling polling loops or the multi-step face upload.
+
+Synchronous and Pythonic: construct one client, call resource methods with
+keyword arguments, get plain dicts back.
+
+## Install
+
+```bash
+pip install runmux
+```
+
+Requires Python 3.9+ (built on [httpx](https://www.python-httpx.org/)).
+
+## Quickstart — text to video (one call)
+
+```python
+import os
+from runmux import RunmuxClient
+
+client = RunmuxClient(api_key=os.environ["RUNMUX_API_KEY"])
+
+# run() submits the job AND waits for the result — no polling code on your side.
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="a diamond necklace rotating on black velvet, soft highlights, product ad",
+    resolution="480p",
+    duration=5,
+)
+
+print(video["url"])  # downloadable result (expires ~1h unless you pass ttl)
+```
+
+The API key falls back to the `RUNMUX_API_KEY` environment variable, so
+`RunmuxClient()` works when that variable is set.
+
+Prefer to manage polling yourself? Use `create()` then `wait()`:
+
+```python
+job = client.videos.create(model="seedance-2-0-mini", prompt="...")
+done = client.videos.wait(job["id"])
+```
+
+## Putting a person in the video (faces)
+
+Raw human faces cannot be sent to the model directly. `faces.enroll()` runs the
+whole flow — register, wait until active, return the ready-to-use `asset://`
+reference:
+
+```python
+# Use an ordinary (non-celebrity) face photo.
+asset_uri = client.faces.enroll(url="https://your-cdn.com/model.jpg")
+
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="Image 1 wearing the necklace, smiling at the camera",
+    image_url=asset_uri,  # or reference_images=[asset_uri]
+)
+```
+
+Even simpler — let RunMux enroll the face for you in one shot:
+
+```python
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="Image 1 wearing the necklace",
+    image_url="https://your-cdn.com/model.jpg",
+    auto_enroll_faces=True,
+)
+```
+
+If a face is rejected (e.g. a celebrity / copyrighted likeness), the call raises
+a `RunmuxError` whose message explains why — switch to an ordinary face photo.
+
+## Image-to-video, batches, and inputs
+
+```python
+# Product image as the first frame:
+client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="the ring rotates",
+    frame_images=["https://cdn/ring.jpg"],
+)
+
+# Several variations at once (number_results 1–4) returns a list:
+variations = client.videos.run(
+    model="seedance-2-0-mini", prompt="...", number_results=3
+)
+
+# Upload a local file, then reference it:
+with open("ring.png", "rb") as f:
+    file_url = client.files.upload(f.read(), "image/png")
+```
+
+`frame_images` entries may be plain URL/`asset://` strings, or dicts with an
+explicit frame, e.g. `{"image": "https://cdn/ring.jpg", "frame": "first"}`.
+
+## Webhooks
+
+Submit with `webhook_url` to get the result POSTed to you, then verify the
+signature against the raw request body:
+
+```python
+ok = client.webhooks.verify(
+    payload=raw_request_body,                 # the raw string body, not re-serialized
+    signature=request.headers.get("x-runmux-signature"),
+    secret=os.environ["RUNMUX_WEBHOOK_SECRET"],
+)
+```
+
+The signature scheme is `sha256=<hex>` where the hex is
+`HMAC-SHA256(raw_body, secret)`; comparison is constant-time.
+
+## Errors
+
+Every non-2xx response (and any failed job/asset) raises a `RunmuxError` with
+`.code`, `.status`, and `.request_id` for precise branching and support.
+
+```python
+from runmux import RunmuxError
+
+try:
+    client.videos.run(model="seedance-2-0-mini", prompt="...")
+except RunmuxError as exc:
+    print(exc.code, exc.status, exc.request_id)
+```
+
+## API surface
+
+- `client.videos` — `create`, `run`, `wait`, `get`
+- `client.assets` — `create`, `get`, `list`, `delete`, `wait_active`
+- `client.faces` — `enroll`, `enroll_asset`
+- `client.files` — `create_upload`, `upload`
+- `client.webhooks` — `verify`
+
+## Wire field names
+
+You pass clean Python snake_case keyword arguments; the SDK maps them to the
+exact field names the API expects. For example `image_url`, `reference_images`,
+`auto_enroll_faces`, and `number_results` are sent as-is, while `output_type`,
+`output_format`, `output_quality`, and `upload_endpoint` are sent as their
+camelCase wire equivalents. Pass `idempotency_key` to dedup retries — it is sent
+as the `Idempotency-Key` header, not a body field.

runmux-0.1.0/README.md

@@ -0,0 +1,145 @@
+# runmux
+
+Official Python SDK for **RunMux** — generate video with Seedance 2.0 and manage the
+face asset library, without hand-rolling polling loops or the multi-step face upload.
+
+Synchronous and Pythonic: construct one client, call resource methods with
+keyword arguments, get plain dicts back.
+
+## Install
+
+```bash
+pip install runmux
+```
+
+Requires Python 3.9+ (built on [httpx](https://www.python-httpx.org/)).
+
+## Quickstart — text to video (one call)
+
+```python
+import os
+from runmux import RunmuxClient
+
+client = RunmuxClient(api_key=os.environ["RUNMUX_API_KEY"])
+
+# run() submits the job AND waits for the result — no polling code on your side.
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="a diamond necklace rotating on black velvet, soft highlights, product ad",
+    resolution="480p",
+    duration=5,
+)
+
+print(video["url"])  # downloadable result (expires ~1h unless you pass ttl)
+```
+
+The API key falls back to the `RUNMUX_API_KEY` environment variable, so
+`RunmuxClient()` works when that variable is set.
+
+Prefer to manage polling yourself? Use `create()` then `wait()`:
+
+```python
+job = client.videos.create(model="seedance-2-0-mini", prompt="...")
+done = client.videos.wait(job["id"])
+```
+
+## Putting a person in the video (faces)
+
+Raw human faces cannot be sent to the model directly. `faces.enroll()` runs the
+whole flow — register, wait until active, return the ready-to-use `asset://`
+reference:
+
+```python
+# Use an ordinary (non-celebrity) face photo.
+asset_uri = client.faces.enroll(url="https://your-cdn.com/model.jpg")
+
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="Image 1 wearing the necklace, smiling at the camera",
+    image_url=asset_uri,  # or reference_images=[asset_uri]
+)
+```
+
+Even simpler — let RunMux enroll the face for you in one shot:
+
+```python
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="Image 1 wearing the necklace",
+    image_url="https://your-cdn.com/model.jpg",
+    auto_enroll_faces=True,
+)
+```
+
+If a face is rejected (e.g. a celebrity / copyrighted likeness), the call raises
+a `RunmuxError` whose message explains why — switch to an ordinary face photo.
+
+## Image-to-video, batches, and inputs
+
+```python
+# Product image as the first frame:
+client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="the ring rotates",
+    frame_images=["https://cdn/ring.jpg"],
+)
+
+# Several variations at once (number_results 1–4) returns a list:
+variations = client.videos.run(
+    model="seedance-2-0-mini", prompt="...", number_results=3
+)
+
+# Upload a local file, then reference it:
+with open("ring.png", "rb") as f:
+    file_url = client.files.upload(f.read(), "image/png")
+```
+
+`frame_images` entries may be plain URL/`asset://` strings, or dicts with an
+explicit frame, e.g. `{"image": "https://cdn/ring.jpg", "frame": "first"}`.
+
+## Webhooks
+
+Submit with `webhook_url` to get the result POSTed to you, then verify the
+signature against the raw request body:
+
+```python
+ok = client.webhooks.verify(
+    payload=raw_request_body,                 # the raw string body, not re-serialized
+    signature=request.headers.get("x-runmux-signature"),
+    secret=os.environ["RUNMUX_WEBHOOK_SECRET"],
+)
+```
+
+The signature scheme is `sha256=<hex>` where the hex is
+`HMAC-SHA256(raw_body, secret)`; comparison is constant-time.
+
+## Errors
+
+Every non-2xx response (and any failed job/asset) raises a `RunmuxError` with
+`.code`, `.status`, and `.request_id` for precise branching and support.
+
+```python
+from runmux import RunmuxError
+
+try:
+    client.videos.run(model="seedance-2-0-mini", prompt="...")
+except RunmuxError as exc:
+    print(exc.code, exc.status, exc.request_id)
+```
+
+## API surface
+
+- `client.videos` — `create`, `run`, `wait`, `get`
+- `client.assets` — `create`, `get`, `list`, `delete`, `wait_active`
+- `client.faces` — `enroll`, `enroll_asset`
+- `client.files` — `create_upload`, `upload`
+- `client.webhooks` — `verify`
+
+## Wire field names
+
+You pass clean Python snake_case keyword arguments; the SDK maps them to the
+exact field names the API expects. For example `image_url`, `reference_images`,
+`auto_enroll_faces`, and `number_results` are sent as-is, while `output_type`,
+`output_format`, `output_quality`, and `upload_endpoint` are sent as their
+camelCase wire equivalents. Pass `idempotency_key` to dedup retries — it is sent
+as the `Idempotency-Key` header, not a body field.

runmux-0.1.0/examples/face_portrait.py

@@ -0,0 +1,22 @@
+"""Put a specific person (ordinary, non-celebrity face) into a jewelry shot.
+
+Run: RUNMUX_API_KEY=sk-... python examples/face_portrait.py
+"""
+
+import os
+
+from runmux import RunmuxClient
+
+client = RunmuxClient(api_key=os.environ.get("RUNMUX_API_KEY"))
+
+# One-call onboarding: register the face and get its asset:// reference.
+model = client.faces.enroll(url="https://your-cdn.com/model.jpg", name="model")
+
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="Image 1 wearing a diamond ring, raising her hand to show it, product ad",
+    reference_images=[model, "https://your-cdn.com/ring.jpg"],
+    resolution="480p",
+)
+
+print("Portrait video:", video["url"])

runmux-0.1.0/examples/quickstart.py

@@ -0,0 +1,19 @@
+"""Quickstart: text to video in one call.
+
+Run: RUNMUX_API_KEY=sk-... python examples/quickstart.py
+"""
+
+import os
+
+from runmux import RunmuxClient
+
+client = RunmuxClient(api_key=os.environ.get("RUNMUX_API_KEY"))
+
+video = client.videos.run(
+    model="seedance-2-0-mini",
+    prompt="a hot air balloon rising over green hills at dawn, cinematic",
+    resolution="480p",
+    duration=5,
+)
+
+print("Done:", video["url"])

runmux-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runmux"
+version = "0.1.0"
+description = "Official RunMux Python SDK — video generation (Seedance 2.0) and the face asset library, with submit-and-wait helpers so you never hand-roll polling."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "RunMux" }]
+keywords = ["runmux", "video-generation", "seedance", "ai-video", "sdk"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "respx>=0.21"]
+
+[project.urls]
+Homepage = "https://runmux.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["runmux"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

runmux-0.1.0/runmux/__init__.py

@@ -0,0 +1,28 @@
+"""RunMux — official Python SDK.
+
+Generate video with Seedance 2.0 and manage the face asset library, with
+submit-and-wait helpers so you never hand-roll polling.
+"""
+
+from __future__ import annotations
+
+from .assets import Assets
+from .client import RunmuxClient
+from .errors import RunmuxError
+from .faces import Faces
+from .files import Files
+from .videos import Videos
+from .webhooks import Webhooks
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RunmuxClient",
+    "RunmuxError",
+    "Videos",
+    "Assets",
+    "Faces",
+    "Files",
+    "Webhooks",
+    "__version__",
+]

runmux-0.1.0/runmux/assets.py

@@ -0,0 +1,83 @@
+"""The face / portrait asset library: register media and poll until active."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from urllib.parse import quote
+
+from .errors import RunmuxError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .client import RunmuxClient
+
+
+class Assets:
+    def __init__(self, client: "RunmuxClient") -> None:
+        self._client = client
+
+    def create(
+        self,
+        *,
+        url: Optional[str] = None,
+        data_url: Optional[str] = None,
+        name: Optional[str] = None,
+        asset_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Register a face/portrait asset by public URL or inline ``data_url``.
+
+        Returns a ``processing`` record. ``asset_type`` is ``"Image"`` or
+        ``"Video"``.
+        """
+        body: Dict[str, Any] = {}
+        if url is not None:
+            body["url"] = url
+        if data_url is not None:
+            body["dataUrl"] = data_url
+        if name is not None:
+            body["name"] = name
+        if asset_type is not None:
+            body["assetType"] = asset_type
+        return self._client.request("POST", "/v1/assets", body=body)
+
+    def get(self, id: str) -> Dict[str, Any]:
+        return self._client.request("GET", f"/v1/assets/{quote(id, safe='')}")
+
+    def list(self) -> List[Dict[str, Any]]:
+        res = self._client.request("GET", "/v1/assets")
+        if isinstance(res, dict):
+            return res.get("data") or []
+        return []
+
+    def delete(self, id: str) -> None:
+        self._client.request("DELETE", f"/v1/assets/{quote(id, safe='')}")
+
+    def wait_active(
+        self,
+        id: str,
+        interval: float = 3,
+        timeout: float = 120,
+    ) -> Dict[str, Any]:
+        """Poll an asset until it leaves ``processing``.
+
+        Returns the active asset record. Raises ``RunmuxError`` (carrying
+        ``statusReason``) if the asset fails or is rejected, or on timeout
+        (seconds).
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            asset = self.get(id)
+            status = asset.get("status")
+            if status == "active":
+                return asset
+            if status in ("failed", "rejected"):
+                raise RunmuxError(
+                    asset.get("statusReason") or "Asset failed processing.",
+                    code="bad_request",
+                )
+            if time.monotonic() >= deadline:
+                raise RunmuxError(
+                    f"Timed out waiting for asset {id} to become active.",
+                    code="upstream_timeout",
+                )
+            time.sleep(interval)

runmux-0.1.0/runmux/client.py

@@ -0,0 +1,132 @@
+"""The RunMux client — construct once with your API key, then use the resource
+namespaces: ``client.videos``, ``client.files``, ``client.assets``,
+``client.faces``, ``client.webhooks``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, Mapping, Optional
+
+import httpx
+
+from .assets import Assets
+from .errors import RunmuxError
+from .faces import Faces
+from .files import Files
+from .videos import Videos
+from .webhooks import Webhooks
+
+DEFAULT_BASE_URL = "https://api.runmux.com"
+
+
+class RunmuxClient:
+    """Synchronous RunMux client.
+
+    Args:
+        api_key: Your RunMux API key (Bearer). Falls back to the
+            ``RUNMUX_API_KEY`` environment variable.
+        base_url: API base URL. Default ``https://api.runmux.com``.
+        timeout: Per-request timeout in seconds. Default ``60``.
+        transport: Optional ``httpx`` transport override (for tests / custom
+            transports).
+
+    Raises:
+        RunmuxError: with ``code="invalid_key"`` if no API key is provided.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 60,
+        *,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        key = api_key if api_key is not None else os.environ.get("RUNMUX_API_KEY")
+        if not key:
+            raise RunmuxError(
+                "A RunMux API key is required (pass api_key or set RUNMUX_API_KEY).",
+                code="invalid_key",
+            )
+        self._api_key = key
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={
+                "authorization": f"Bearer {self._api_key}",
+                "content-type": "application/json",
+            },
+        )
+
+        self.videos = Videos(self)
+        self.files = Files(self)
+        self.assets = Assets(self)
+        self.faces = Faces(self)
+        self.webhooks = Webhooks()
+
+    # -- context manager / lifecycle ------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> "RunmuxClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # -- low-level request ----------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        """Low-level JSON request against the RunMux API.
+
+        Raises ``RunmuxError`` on any non-2xx response, parsing the API's
+        ``{"error": {code, message, request_id}}`` envelope when present.
+        """
+        try:
+            response = self._http.request(
+                method,
+                path,
+                json=body if body is not None else None,
+                headers=dict(headers) if headers else None,
+            )
+        except httpx.TimeoutException as exc:
+            raise RunmuxError(
+                "Request to RunMux timed out.", code="upstream_timeout"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise RunmuxError(
+                str(exc) or "Network request failed.", code="upstream_unavailable"
+            ) from exc
+
+        text = response.text
+        data: Any = None
+        if text:
+            try:
+                data = response.json()
+            except ValueError:
+                data = None
+
+        if not response.is_success:
+            err: Dict[str, Any] = {}
+            if isinstance(data, dict) and isinstance(data.get("error"), dict):
+                err = data["error"]
+            raise RunmuxError(
+                err.get("message") or f"RunMux request failed ({response.status_code}).",
+                status=response.status_code,
+                code=err.get("code") or "upstream_unavailable",
+                request_id=err.get("request_id"),
+            )
+        return data

runmux-0.1.0/runmux/errors.py

@@ -0,0 +1,54 @@
+"""Error type for the RunMux SDK."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+# Stable error codes returned by the RunMux API (mirrors the server's error codes).
+ERROR_CODES = (
+    "invalid_key",
+    "insufficient_balance",
+    "model_not_allowed",
+    "rate_limited",
+    "upstream_timeout",
+    "stream_interrupted",
+    "upstream_unavailable",
+    "internal_error",
+    "permission_denied",
+    "bad_request",
+)
+
+
+class RunmuxError(Exception):
+    """Raised for any non-2xx RunMux API response, or when a job/asset reaches a
+    failed terminal state.
+
+    Carries the API's ``code`` and ``request_id`` so callers can branch and
+    report precisely.
+
+    Attributes:
+        message: Human-readable description.
+        status: HTTP status code (0 when not from an HTTP response).
+        code: A stable machine-readable error code (see ``ERROR_CODES``).
+        request_id: Server-side request id for support, when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "internal_error",
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return (
+            f"RunmuxError(message={self.message!r}, status={self.status!r}, "
+            f"code={self.code!r}, request_id={self.request_id!r})"
+        )