genrelay 0.1.0__tar.gz

genrelay-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.mp4
+*.part

genrelay-0.1.0/LICENSE

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

genrelay-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: genrelay
+Version: 0.1.0
+Summary: Unified Python client for Veo 3.1, Grok Imagine, Nano Banana and other video & image generation models via the GenRelay API
+Project-URL: Homepage, https://genrelay.ai
+Project-URL: Documentation, https://genrelay.ai/docs
+Project-URL: Source, https://github.com/genrelay/genrelay-python
+Project-URL: Issues, https://github.com/genrelay/genrelay-python/issues
+Author: GenRelay
+License: MIT License
+        
+        Copyright (c) 2026 GenRelay
+        
+        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.
+License-File: LICENSE
+Keywords: api-client,generative-ai,grok-imagine,image-generation,image-to-video,nano-banana,text-to-video,veo,veo-3,video-generation
+Classifier: Development Status :: 4 - Beta
+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
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# genrelay-python
+
+Python client for [GenRelay](https://genrelay.ai) — one API for **Veo 3.1**, **Grok Imagine**, **Nano Banana Pro/2**, **GPT Image 2** and **Omni Flash**. Text-to-video, image-to-video, first/last-frame, and image generation.
+
+```bash
+pip install genrelay
+```
+
+## Quick start
+
+```python
+from genrelay import GenRelay
+
+client = GenRelay()  # reads GENRELAY_API_KEY
+
+video = client.videos.generate(
+    model="veo_3_1",
+    prompt="a neon fox running through a rainy city at night",
+    seconds=8,
+    size="1280x720",
+    tier="1080p",
+)
+
+client.videos.download(video.id, "fox.mp4")
+```
+
+That's the whole loop: submit, poll with backoff, stream to disk. Generation
+takes seconds to minutes depending on the model and length.
+
+## Why this exists
+
+Chat and image edits on GenRelay are **OpenAI-compatible** — point the
+official `openai` package at `https://genrelay.ai/v1` and you're done:
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="https://genrelay.ai/v1", api_key="sk-...")
+```
+
+Generation jobs are different: they're asynchronous, with a submit → poll →
+download cycle that has no equivalent in that SDK. That's what this package
+handles — the polling loop, the backoff, the terminal-state detection, the
+streamed download, and typed errors instead of dict-digging.
+
+## Async, when you need control
+
+```python
+job = client.videos.create(model="veo_3_1", prompt="...", seconds=8)
+print(job.id, job.status)          # task_xxx queued
+
+# ... do other work, persist job.id, come back later ...
+
+video = client.videos.wait(job.id, timeout=900)
+```
+
+Watch progress while it runs:
+
+```python
+client.videos.generate(
+    model="veo_3_1",
+    prompt="...",
+    on_progress=lambda v: print(f"{v.status} {v.progress}%"),
+)
+```
+
+## Models
+
+| Model | Kind | Notes |
+|---|---|---|
+| `veo_3_1` | video | Google Veo 3.1 |
+| `veo_3_1-fl` | video | first/last frame |
+| `veo_3_1-components` | video | component-guided |
+| `grok-imagine-video-1-5-preview` | video | xAI Grok Imagine 1.5 |
+| `grok-imagine-1-0-video` | video | Grok Imagine 1.0 |
+| `omni-flash` | video | fast, long clips |
+| `omni_flash_abra_edit` | video | video editing |
+| `nano-banana-pro` | image | Google |
+| `nano-banana-2` | image | Google |
+| `gpt-image-2` | image | OpenAI |
+
+Current list and per-model options: **https://genrelay.ai/models**
+
+## Parameters
+
+| Name | Type | Notes |
+|---|---|---|
+| `model` | str | required |
+| `prompt` | str | required |
+| `seconds` | int \| str | 1–60, default 4. Ignored by image models |
+| `size` | str | `"1280x720"`. Aspect ratio is inferred — no separate parameter |
+| `tier` | str | `1k`/`2k`/`4k` (images), `720p`/`1080p`/`4k` (Veo) |
+| `reference_images` | list[str] | HTTPS or `data:` URLs |
+| `metadata` | dict | model-specific extras, e.g. `{"first_last_frame": True}` |
+
+> **Set `tier` explicitly.** Pricing is per tier, and a `size` that matches no
+> tier falls back to the model's base rate — which can cost noticeably more
+> than you expected.
+
+Unknown keyword arguments are forwarded as-is, so new API fields work before
+this client knows about them.
+
+## Errors
+
+```python
+from genrelay import InsufficientCreditsError, JobFailedError, JobTimeout
+
+try:
+    video = client.videos.generate(model="veo_3_1", prompt="...")
+except InsufficientCreditsError:
+    ...                      # 402 — top up
+except JobFailedError as e:
+    print(e.video.error)     # model couldn't produce a result
+except JobTimeout as e:
+    print(e.task_id)         # still running — poll later, don't resubmit
+```
+
+`JobTimeout` deliberately keeps the task id: resubmitting bills a second time,
+polling doesn't.
+
+All exceptions derive from `GenRelayError`.
+
+## Configuration
+
+| | |
+|---|---|
+| `GENRELAY_API_KEY` | API key, or pass `api_key=` |
+| `GENRELAY_BASE_URL` | override the endpoint (default `https://genrelay.ai/v1`) |
+
+```python
+client = GenRelay(api_key="sk-...", timeout=60.0, max_retries=2)
+```
+
+`GenRelay` is a context manager and closes its HTTP client on exit. Pass your
+own `httpx.Client` via `http_client=` to control pooling or proxies.
+
+## License
+
+MIT

genrelay-0.1.0/README.md

@@ -0,0 +1,138 @@
+# genrelay-python
+
+Python client for [GenRelay](https://genrelay.ai) — one API for **Veo 3.1**, **Grok Imagine**, **Nano Banana Pro/2**, **GPT Image 2** and **Omni Flash**. Text-to-video, image-to-video, first/last-frame, and image generation.
+
+```bash
+pip install genrelay
+```
+
+## Quick start
+
+```python
+from genrelay import GenRelay
+
+client = GenRelay()  # reads GENRELAY_API_KEY
+
+video = client.videos.generate(
+    model="veo_3_1",
+    prompt="a neon fox running through a rainy city at night",
+    seconds=8,
+    size="1280x720",
+    tier="1080p",
+)
+
+client.videos.download(video.id, "fox.mp4")
+```
+
+That's the whole loop: submit, poll with backoff, stream to disk. Generation
+takes seconds to minutes depending on the model and length.
+
+## Why this exists
+
+Chat and image edits on GenRelay are **OpenAI-compatible** — point the
+official `openai` package at `https://genrelay.ai/v1` and you're done:
+
+```python
+from openai import OpenAI
+client = OpenAI(base_url="https://genrelay.ai/v1", api_key="sk-...")
+```
+
+Generation jobs are different: they're asynchronous, with a submit → poll →
+download cycle that has no equivalent in that SDK. That's what this package
+handles — the polling loop, the backoff, the terminal-state detection, the
+streamed download, and typed errors instead of dict-digging.
+
+## Async, when you need control
+
+```python
+job = client.videos.create(model="veo_3_1", prompt="...", seconds=8)
+print(job.id, job.status)          # task_xxx queued
+
+# ... do other work, persist job.id, come back later ...
+
+video = client.videos.wait(job.id, timeout=900)
+```
+
+Watch progress while it runs:
+
+```python
+client.videos.generate(
+    model="veo_3_1",
+    prompt="...",
+    on_progress=lambda v: print(f"{v.status} {v.progress}%"),
+)
+```
+
+## Models
+
+| Model | Kind | Notes |
+|---|---|---|
+| `veo_3_1` | video | Google Veo 3.1 |
+| `veo_3_1-fl` | video | first/last frame |
+| `veo_3_1-components` | video | component-guided |
+| `grok-imagine-video-1-5-preview` | video | xAI Grok Imagine 1.5 |
+| `grok-imagine-1-0-video` | video | Grok Imagine 1.0 |
+| `omni-flash` | video | fast, long clips |
+| `omni_flash_abra_edit` | video | video editing |
+| `nano-banana-pro` | image | Google |
+| `nano-banana-2` | image | Google |
+| `gpt-image-2` | image | OpenAI |
+
+Current list and per-model options: **https://genrelay.ai/models**
+
+## Parameters
+
+| Name | Type | Notes |
+|---|---|---|
+| `model` | str | required |
+| `prompt` | str | required |
+| `seconds` | int \| str | 1–60, default 4. Ignored by image models |
+| `size` | str | `"1280x720"`. Aspect ratio is inferred — no separate parameter |
+| `tier` | str | `1k`/`2k`/`4k` (images), `720p`/`1080p`/`4k` (Veo) |
+| `reference_images` | list[str] | HTTPS or `data:` URLs |
+| `metadata` | dict | model-specific extras, e.g. `{"first_last_frame": True}` |
+
+> **Set `tier` explicitly.** Pricing is per tier, and a `size` that matches no
+> tier falls back to the model's base rate — which can cost noticeably more
+> than you expected.
+
+Unknown keyword arguments are forwarded as-is, so new API fields work before
+this client knows about them.
+
+## Errors
+
+```python
+from genrelay import InsufficientCreditsError, JobFailedError, JobTimeout
+
+try:
+    video = client.videos.generate(model="veo_3_1", prompt="...")
+except InsufficientCreditsError:
+    ...                      # 402 — top up
+except JobFailedError as e:
+    print(e.video.error)     # model couldn't produce a result
+except JobTimeout as e:
+    print(e.task_id)         # still running — poll later, don't resubmit
+```
+
+`JobTimeout` deliberately keeps the task id: resubmitting bills a second time,
+polling doesn't.
+
+All exceptions derive from `GenRelayError`.
+
+## Configuration
+
+| | |
+|---|---|
+| `GENRELAY_API_KEY` | API key, or pass `api_key=` |
+| `GENRELAY_BASE_URL` | override the endpoint (default `https://genrelay.ai/v1`) |
+
+```python
+client = GenRelay(api_key="sk-...", timeout=60.0, max_retries=2)
+```
+
+`GenRelay` is a context manager and closes its HTTP client on exit. Pass your
+own `httpx.Client` via `http_client=` to control pooling or proxies.
+
+## License
+
+MIT

genrelay-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "genrelay"
+version = "0.1.0"
+description = "Unified Python client for Veo 3.1, Grok Imagine, Nano Banana and other video & image generation models via the GenRelay API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [{ name = "GenRelay" }]
+keywords = [
+    "veo",
+    "veo-3",
+    "grok-imagine",
+    "nano-banana",
+    "text-to-video",
+    "image-to-video",
+    "video-generation",
+    "image-generation",
+    "generative-ai",
+    "api-client",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "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",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://genrelay.ai"
+Documentation = "https://genrelay.ai/docs"
+Source = "https://github.com/genrelay/genrelay-python"
+Issues = "https://github.com/genrelay/genrelay-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov", "ruff", "mypy"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/genrelay"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# src layout: let the tests import the package without an editable install,
+# so `pytest` works straight after a clone.
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.9"
+strict = true

genrelay-0.1.0/src/genrelay/__init__.py

@@ -0,0 +1,42 @@
+"""GenRelay — unified API client for Veo 3.1, Grok Imagine, Nano Banana and more.
+
+Generation jobs are asynchronous: you submit, the server works for anywhere
+from seconds to minutes, then you collect. This package wraps that loop —
+submit, poll with backoff, stream the result to disk — so callers write one
+line instead of a retry loop.
+
+Chat and image edits are OpenAI-compatible; use the official ``openai``
+package against ``https://genrelay.ai/v1`` for those.
+"""
+
+from .errors import (
+    APIError,
+    AuthenticationError,
+    GenRelayError,
+    InsufficientCreditsError,
+    JobFailedError,
+    JobTimeout,
+    RateLimitError,
+)
+from .types import TERMINAL_STATUSES, Video, VideoError, VideoStatus
+
+__version__ = "0.1.0"
+
+from ._client import GenRelay, Videos  # noqa: E402  (needs __version__ above)
+
+__all__ = [
+    "GenRelay",
+    "Videos",
+    "Video",
+    "VideoError",
+    "VideoStatus",
+    "TERMINAL_STATUSES",
+    "GenRelayError",
+    "APIError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "JobFailedError",
+    "JobTimeout",
+    "__version__",
+]

genrelay-0.1.0/src/genrelay/_client.py

@@ -0,0 +1,383 @@
+"""HTTP client for the GenRelay generation API."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from pathlib import Path
+from typing import Any, Callable, Iterator, Mapping, Sequence
+
+import httpx
+
+from .errors import (
+    APIError,
+    AuthenticationError,
+    InsufficientCreditsError,
+    JobFailedError,
+    JobTimeout,
+    RateLimitError,
+)
+from .types import Video
+
+__all__ = ["GenRelay", "Videos"]
+
+DEFAULT_BASE_URL = "https://genrelay.ai/v1"
+
+# Generation is slow by nature — a 1080p Veo clip regularly takes minutes.
+# These bound the *HTTP* calls, not the job: a job outliving the request is
+# normal and is what polling is for.
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_POLL_INTERVAL = 3.0
+DEFAULT_MAX_WAIT = 900.0
+
+
+def _user_agent(version: str) -> str:
+    return f"genrelay-python/{version}"
+
+
+class Videos:
+    """Generation jobs — video *and* image (the API models both as "videos")."""
+
+    def __init__(self, client: "GenRelay") -> None:
+        self._client = client
+
+    # ---------------------------------------------------------------- create
+
+    def create(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        seconds: int | str | None = None,
+        size: str | None = None,
+        tier: str | None = None,
+        reference_images: Sequence[str] | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        **extra: Any,
+    ) -> Video:
+        """Submit a job and return immediately, without waiting for the result.
+
+        Args:
+            model: Public model name, e.g. ``"veo_3_1"`` or ``"gpt-image-2"``.
+            prompt: What to generate.
+            seconds: Clip length, 1–60 (default 4). Ignored by image models.
+            size: Pixel size as ``"WxH"``, e.g. ``"1280x720"``. The aspect
+                ratio is inferred from it — there is no separate parameter.
+            tier: Resolution/quality tier — ``1k``/``2k``/``4k`` for images,
+                ``720p``/``1080p``/``4k`` for Veo video. **Worth setting
+                explicitly**: pricing is per tier, and a size that matches no
+                tier falls back to the model's base rate.
+            reference_images: HTTPS URLs or ``data:`` URLs. Per-model limits
+                apply; see the model's page.
+            metadata: Model-specific extras that are not top-level fields,
+                e.g. ``{"first_last_frame": True}`` for omni.
+            **extra: Passed through verbatim, so a newly added API field is
+                usable before this client knows about it.
+
+        Returns:
+            The job in its initial state — usually ``queued``.
+        """
+        body: dict[str, Any] = {"model": model, "prompt": prompt}
+        if seconds is not None:
+            body["seconds"] = seconds
+        if size is not None:
+            body["size"] = size
+        if tier is not None:
+            body["tier"] = tier
+        if reference_images:
+            body["reference_images"] = list(reference_images)
+        if metadata:
+            body["metadata"] = dict(metadata)
+        body.update(extra)
+
+        return Video._from_json(self._client._request("POST", "/videos", json=body))
+
+    # -------------------------------------------------------------- retrieve
+
+    def retrieve(self, task_id: str) -> Video:
+        """Read the job's current state. One HTTP call, no waiting."""
+        return Video._from_json(self._client._request("GET", f"/videos/{task_id}"))
+
+    # ------------------------------------------------------------------ wait
+
+    def wait(
+        self,
+        task_id: str,
+        *,
+        timeout: float = DEFAULT_MAX_WAIT,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        on_progress: Callable[[Video], None] | None = None,
+    ) -> Video:
+        """Poll until the job reaches a terminal state.
+
+        Raises:
+            JobFailedError: the job finished as ``failed``.
+            JobTimeout: still running when ``timeout`` elapsed. The job is
+                *not* cancelled — poll ``task_id`` again later rather than
+                resubmitting, which would bill a second time.
+        """
+        deadline = time.monotonic() + timeout
+        attempt = 0
+
+        while True:
+            video = self.retrieve(task_id)
+            if on_progress is not None:
+                on_progress(video)
+            if video.is_done:
+                if video.status == "failed":
+                    detail = video.error.message if video.error else "no detail given"
+                    raise JobFailedError(
+                        f"job {video.id} failed: {detail}", video=video
+                    )
+                return video
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise JobTimeout(
+                    f"job {task_id} still {video.status} after {timeout:g}s; "
+                    f"poll it again later instead of resubmitting",
+                    task_id=task_id,
+                )
+
+            # Small jitter so a batch of jobs started together does not poll in
+            # lockstep. Capped at 10s: generation is slow, but people watch
+            # progress bars.
+            delay = min(poll_interval * (1 + 0.25 * attempt), 10.0)
+            delay += random.uniform(0, 0.4)
+            time.sleep(min(delay, max(remaining, 0.1)))
+            attempt += 1
+
+    # -------------------------------------------------------------- generate
+
+    def generate(
+        self,
+        *,
+        model: str,
+        prompt: str,
+        timeout: float = DEFAULT_MAX_WAIT,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        on_progress: Callable[[Video], None] | None = None,
+        **params: Any,
+    ) -> Video:
+        """Submit and wait — the one-liner for scripts and notebooks.
+
+        Equivalent to :meth:`create` followed by :meth:`wait`, and takes the
+        same generation parameters as :meth:`create`.
+        """
+        job = self.create(model=model, prompt=prompt, **params)
+        return self.wait(
+            job.id,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            on_progress=on_progress,
+        )
+
+    # -------------------------------------------------------------- download
+
+    def download(self, task_id: str, dest: str | Path) -> Path:
+        """Stream the finished asset to ``dest`` and return the path.
+
+        Streams rather than buffering: a minute of 1080p is tens of megabytes
+        and there is no reason to hold it in memory.
+        """
+        path = Path(dest)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Write to a sibling temp file first so an interrupted download never
+        # leaves a half-written file that looks complete.
+        tmp = path.with_suffix(path.suffix + ".part")
+        with self._client._stream("GET", f"/videos/{task_id}/content") as response:
+            with tmp.open("wb") as fh:
+                for chunk in response.iter_bytes(chunk_size=1 << 16):
+                    fh.write(chunk)
+        tmp.replace(path)
+        return path
+
+
+class GenRelay:
+    """Client for the GenRelay generation API.
+
+    Usage::
+
+        from genrelay import GenRelay
+
+        client = GenRelay()  # reads GENRELAY_API_KEY
+        video = client.videos.generate(
+            model="veo_3_1",
+            prompt="a neon fox running through a rainy city at night",
+            seconds=8,
+            size="1280x720",
+            tier="1080p",
+        )
+        client.videos.download(video.id, "fox.mp4")
+
+    Chat and image-edit endpoints are OpenAI-compatible — point the official
+    ``openai`` package at ``https://genrelay.ai/v1`` for those. This client
+    exists for the generation jobs, which are asynchronous and have no
+    equivalent in that SDK.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        key = api_key or os.environ.get("GENRELAY_API_KEY", "")
+        if not key:
+            raise AuthenticationError(
+                "no API key: pass api_key=... or set GENRELAY_API_KEY"
+            )
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("GENRELAY_BASE_URL")
+                         or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max(0, max_retries)
+
+        from . import __version__
+
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": _user_agent(__version__),
+        }
+
+        self.videos = Videos(self)
+
+    # ------------------------------------------------------------- lifecycle
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "GenRelay":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()
+
+    # --------------------------------------------------------------- request
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        last_error: Exception | None = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self._http.request(
+                    method, self._url(path), headers=self._headers, **kwargs
+                )
+            except httpx.TimeoutException as exc:
+                last_error = exc
+                if attempt < self.max_retries:
+                    time.sleep(_backoff(attempt))
+                    continue
+                raise APIError(f"request to {path} timed out") from exc
+            except httpx.HTTPError as exc:
+                raise APIError(f"request to {path} failed: {exc}") from exc
+
+            if response.status_code < 400:
+                return _decode(response, path)
+
+            # 429 and 5xx are worth retrying; 4xx means the request itself is
+            # wrong and retrying would only bill or annoy.
+            if response.status_code in (429, 500, 502, 503, 504) and attempt < self.max_retries:
+                time.sleep(_retry_after(response) or _backoff(attempt))
+                continue
+
+            raise _error_for(response, path)
+
+        raise APIError(f"request to {path} failed: {last_error}")
+
+    def _stream(self, method: str, path: str, **kwargs: Any):
+        return _StreamContext(self, method, path, kwargs)
+
+
+class _StreamContext:
+    """Context manager that surfaces API errors before the body is streamed."""
+
+    def __init__(self, client: GenRelay, method: str, path: str, kwargs: dict[str, Any]):
+        self._ctx = client._http.stream(
+            method, client._url(path), headers=client._headers, **kwargs
+        )
+        self._path = path
+
+    def __enter__(self) -> httpx.Response:
+        response = self._ctx.__enter__()
+        if response.status_code >= 400:
+            response.read()  # error bodies are small; read before classifying
+            raise _error_for(response, self._path)
+        return response
+
+    def __exit__(self, *exc: Any) -> None:
+        self._ctx.__exit__(*exc)
+
+
+# ------------------------------------------------------------------ helpers
+
+
+def _backoff(attempt: int) -> float:
+    return min(0.5 * (2**attempt), 8.0) + random.uniform(0, 0.3)
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    raw = response.headers.get("Retry-After")
+    if not raw:
+        return None
+    try:
+        return max(0.0, float(raw))
+    except ValueError:
+        return None
+
+
+def _decode(response: httpx.Response, path: str) -> dict[str, Any]:
+    try:
+        data = response.json()
+    except ValueError as exc:
+        raise APIError(
+            f"{path} returned non-JSON body", status=response.status_code
+        ) from exc
+    if not isinstance(data, dict):
+        raise APIError(f"{path} returned {type(data).__name__}, expected an object",
+                       status=response.status_code, body=data)
+    return data
+
+
+def _error_for(response: httpx.Response, path: str) -> APIError:
+    status = response.status_code
+    body: Any
+    try:
+        body = response.json()
+    except ValueError:
+        body = response.text
+
+    message, code = _extract_error(body)
+    message = message or f"{path} failed with HTTP {status}"
+
+    cls = {
+        401: AuthenticationError,
+        403: AuthenticationError,
+        402: InsufficientCreditsError,
+        429: RateLimitError,
+    }.get(status, APIError)
+    return cls(message, status=status, code=code, body=body)
+
+
+def _extract_error(body: Any) -> tuple[str, str | None]:
+    """Pull (message, code) out of the several error shapes the API can emit."""
+    if not isinstance(body, dict):
+        return (str(body)[:300] if body else ""), None
+
+    error = body.get("error")
+    if isinstance(error, dict):
+        return str(error.get("message") or ""), (error.get("code") or None)
+    if isinstance(error, str) and error:
+        return error, None
+    if body.get("message"):
+        return str(body["message"]), (body.get("code") or None)
+    return "", None

genrelay-0.1.0/src/genrelay/errors.py

@@ -0,0 +1,87 @@
+"""Exceptions raised by the GenRelay client.
+
+Every failure mode gets its own class so callers can react without parsing
+strings: a 402 means "top up", a 429 means "back off", a failed job means
+"the prompt or the model choice is the problem". Catching ``GenRelayError``
+catches all of them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class GenRelayError(Exception):
+    """Base class for everything this library raises."""
+
+
+class APIError(GenRelayError):
+    """The API returned a non-2xx response.
+
+    ``status`` is the HTTP status, ``code`` the machine-readable error code
+    when the response carried one, and ``body`` the decoded payload (or the
+    raw text when it was not JSON).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int | None = None,
+        code: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.body = body
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        parts = [super().__str__()]
+        if self.status is not None:
+            parts.append(f"(HTTP {self.status}")
+            parts[-1] += f", code={self.code})" if self.code else ")"
+        return " ".join(parts)
+
+
+class AuthenticationError(APIError):
+    """401 — the API key is missing, malformed, or revoked."""
+
+
+class InsufficientCreditsError(APIError):
+    """402 — the account is out of credits.
+
+    Generation is pay-per-call, so this is an ordinary, expected outcome
+    rather than a bug. Surface it to the user and let them top up.
+    """
+
+
+class RateLimitError(APIError):
+    """429 — too many requests. Retry after a delay."""
+
+
+class JobFailedError(GenRelayError):
+    """The job was accepted but finished with ``status == "failed"``.
+
+    This is not a transport error: the request was valid and billed-or-not per
+    platform rules, but the upstream model could not produce a result. The
+    failed :class:`~genrelay.types.Video` is attached as ``video`` so callers
+    can inspect ``video.error`` and ``video.model``.
+    """
+
+    def __init__(self, message: str, *, video: Any = None) -> None:
+        super().__init__(message)
+        self.video = video
+
+
+class JobTimeout(GenRelayError):
+    """The job did not reach a terminal state within ``timeout`` seconds.
+
+    The job itself keeps running server-side — the task id is attached as
+    ``task_id`` so it can be polled again later instead of being resubmitted
+    (resubmitting bills a second time).
+    """
+
+    def __init__(self, message: str, *, task_id: str | None = None) -> None:
+        super().__init__(message)
+        self.task_id = task_id

genrelay-0.1.0/src/genrelay/types.py

@@ -0,0 +1,86 @@
+"""Typed views over the API's JSON payloads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+VideoStatus = Literal["queued", "in_progress", "completed", "failed"]
+
+#: Statuses the server never moves away from. Polling stops here.
+TERMINAL_STATUSES: frozenset[str] = frozenset({"completed", "failed"})
+
+
+@dataclass(frozen=True)
+class VideoError:
+    """The ``error`` object present on failed jobs."""
+
+    message: str = ""
+    code: str = ""
+
+    @classmethod
+    def _from_json(cls, data: Any) -> "VideoError | None":
+        if not isinstance(data, dict):
+            return None
+        return cls(
+            message=str(data.get("message") or ""),
+            code=str(data.get("code") or ""),
+        )
+
+
+@dataclass(frozen=True)
+class Video:
+    """One generation job.
+
+    The same shape is returned by create and by every poll, so a ``Video`` is
+    a snapshot rather than a live handle — re-read it to see progress move.
+
+    Despite the name the API uses ``object == "video"`` for image jobs too;
+    that is the platform's convention, not a bug in this client.
+    """
+
+    id: str
+    status: VideoStatus
+    model: str = ""
+    progress: int = 0
+    created_at: int = 0
+    completed_at: int | None = None
+    expires_at: int | None = None
+    output_url: str | None = None
+    error: VideoError | None = None
+    #: The untouched response body. Anything this dataclass does not model yet
+    #: (new fields, model-specific extras) stays reachable here.
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def is_done(self) -> bool:
+        """True once the server will not change this job any further."""
+        return self.status in TERMINAL_STATUSES
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status == "completed"
+
+    @classmethod
+    def _from_json(cls, data: dict[str, Any]) -> "Video":
+        # `id` is the documented field; `task_id` is the deprecated alias kept
+        # for older integrations. Prefer `id`, fall back so we keep working if
+        # a response only carries the legacy name.
+        ident = data.get("id") or data.get("task_id") or ""
+
+        def _opt_int(key: str) -> int | None:
+            value = data.get(key)
+            return int(value) if isinstance(value, (int, float)) else None
+
+        return cls(
+            id=str(ident),
+            status=str(data.get("status") or "queued"),  # type: ignore[arg-type]
+            model=str(data.get("model") or ""),
+            progress=int(data.get("progress") or 0),
+            created_at=int(data.get("created_at") or 0),
+            completed_at=_opt_int("completed_at"),
+            expires_at=_opt_int("expires_at"),
+            output_url=data.get("output_url") or None,
+            error=VideoError._from_json(data.get("error")),
+            raw=data,
+        )

genrelay-0.1.0/tests/test_videos.py

@@ -0,0 +1,264 @@
+"""Tests for the generation client.
+
+Everything runs against an httpx mock transport — no network, no API key, no
+credits burned. The point is to pin the behaviour that is easy to get wrong:
+polling stops at terminal states, failures raise instead of returning a
+half-empty object, and HTTP status codes map to the right exception.
+"""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from genrelay import (
+    APIError,
+    AuthenticationError,
+    GenRelay,
+    InsufficientCreditsError,
+    JobFailedError,
+    JobTimeout,
+    RateLimitError,
+)
+
+
+def client_with(handler) -> GenRelay:
+    transport = httpx.MockTransport(handler)
+    return GenRelay(
+        api_key="sk-test",
+        http_client=httpx.Client(transport=transport),
+        max_retries=0,
+    )
+
+
+def job(status: str, **extra) -> dict:
+    body = {
+        "id": "task_abc",
+        "task_id": "task_abc",
+        "object": "video",
+        "model": "veo_3_1",
+        "status": status,
+        "progress": 100 if status == "completed" else 10,
+        "created_at": 1790000000,
+    }
+    body.update(extra)
+    return body
+
+
+# ------------------------------------------------------------------- create
+
+
+def test_create_sends_only_the_fields_given():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.update(json.loads(request.content))
+        return httpx.Response(200, json=job("queued"))
+
+    c = client_with(handler)
+    c.videos.create(model="veo_3_1", prompt="a fox", seconds=8, tier="1080p")
+
+    # Optional params the caller omitted must not be sent at all: sending
+    # size=None would override a model default server-side.
+    assert seen == {"model": "veo_3_1", "prompt": "a fox", "seconds": 8, "tier": "1080p"}
+
+
+def test_create_passes_unknown_fields_through():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen.update(json.loads(request.content))
+        return httpx.Response(200, json=job("queued"))
+
+    c = client_with(handler)
+    c.videos.create(model="m", prompt="p", some_new_api_field="x")
+    assert seen["some_new_api_field"] == "x"
+
+
+def test_create_sends_auth_header():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["auth"] = request.headers.get("Authorization")
+        seen["ua"] = request.headers.get("User-Agent")
+        return httpx.Response(200, json=job("queued"))
+
+    client_with(handler).videos.create(model="m", prompt="p")
+    assert seen["auth"] == "Bearer sk-test"
+    assert seen["ua"].startswith("genrelay-python/")
+
+
+# --------------------------------------------------------------------- wait
+
+
+def test_wait_polls_until_completed():
+    states = iter(["queued", "in_progress", "completed"])
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(200, json=job(next(states), output_url="https://x/v"))
+
+    c = client_with(handler)
+    video = c.videos.wait("task_abc", poll_interval=0.001)
+
+    assert calls["n"] == 3
+    assert video.succeeded and video.is_done
+    assert video.output_url == "https://x/v"
+
+
+def test_wait_raises_on_failed_and_keeps_the_job():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(
+            200,
+            json=job("failed", error={"message": "unsafe prompt", "code": "rejected"}),
+        )
+
+    c = client_with(handler)
+    with pytest.raises(JobFailedError) as excinfo:
+        c.videos.wait("task_abc", poll_interval=0.001)
+
+    # The failed job must be reachable — callers need the reason and the model.
+    assert excinfo.value.video.error.code == "rejected"
+    assert "unsafe prompt" in str(excinfo.value)
+
+
+def test_wait_times_out_without_losing_the_task_id():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=job("in_progress"))
+
+    c = client_with(handler)
+    with pytest.raises(JobTimeout) as excinfo:
+        c.videos.wait("task_abc", timeout=0.05, poll_interval=0.001)
+
+    # Losing the id would force a resubmit, which bills a second time.
+    assert excinfo.value.task_id == "task_abc"
+
+
+def test_on_progress_sees_every_poll():
+    states = iter(["queued", "in_progress", "completed"])
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=job(next(states)))
+
+    seen = []
+    c = client_with(handler)
+    c.videos.wait("task_abc", poll_interval=0.001, on_progress=seen.append)
+    assert [v.status for v in seen] == ["queued", "in_progress", "completed"]
+
+
+# ----------------------------------------------------------------- generate
+
+
+def test_generate_creates_then_waits():
+    seen_paths = []
+    states = iter(["queued", "completed"])
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen_paths.append((request.method, request.url.path))
+        if request.method == "POST":
+            return httpx.Response(200, json=job("queued"))
+        return httpx.Response(200, json=job(next(states)))
+
+    c = client_with(handler)
+    video = c.videos.generate(model="veo_3_1", prompt="p", poll_interval=0.001)
+
+    assert seen_paths[0] == ("POST", "/v1/videos")
+    assert all(m == "GET" for m, _ in seen_paths[1:])
+    assert video.succeeded
+
+
+# ------------------------------------------------------------------- errors
+
+
+@pytest.mark.parametrize(
+    "status,expected",
+    [
+        (401, AuthenticationError),
+        (403, AuthenticationError),
+        (402, InsufficientCreditsError),
+        (429, RateLimitError),
+        (400, APIError),
+        (500, APIError),
+    ],
+)
+def test_status_codes_map_to_exceptions(status, expected):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status, json={"error": {"message": "nope", "code": "e"}})
+
+    c = client_with(handler)
+    with pytest.raises(expected) as excinfo:
+        c.videos.create(model="m", prompt="p")
+    assert excinfo.value.status == status
+    assert excinfo.value.code == "e"
+
+
+def test_error_message_survives_a_plain_string_body():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, text="upstream exploded")
+
+    c = client_with(handler)
+    with pytest.raises(APIError) as excinfo:
+        c.videos.create(model="m", prompt="p")
+    assert "upstream exploded" in str(excinfo.value)
+
+
+def test_missing_api_key_fails_fast(monkeypatch):
+    monkeypatch.delenv("GENRELAY_API_KEY", raising=False)
+    with pytest.raises(AuthenticationError):
+        GenRelay()
+
+
+def test_api_key_from_environment(monkeypatch):
+    monkeypatch.setenv("GENRELAY_API_KEY", "sk-env")
+    assert GenRelay().api_key == "sk-env"
+
+
+# ----------------------------------------------------------------- download
+
+
+def test_download_streams_to_disk(tmp_path):
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/videos/task_abc/content"
+        return httpx.Response(200, content=b"\x00\x01binary")
+
+    c = client_with(handler)
+    out = c.videos.download("task_abc", tmp_path / "nested" / "clip.mp4")
+
+    assert out.read_bytes() == b"\x00\x01binary"
+    # The .part file must not survive a successful download.
+    assert not (tmp_path / "nested" / "clip.mp4.part").exists()
+
+
+def test_download_raises_before_writing_anything(tmp_path):
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={"error": {"message": "gone"}})
+
+    c = client_with(handler)
+    dest = tmp_path / "clip.mp4"
+    with pytest.raises(APIError):
+        c.videos.download("task_abc", dest)
+    assert not dest.exists()
+
+
+# -------------------------------------------------------------------- types
+
+
+def test_legacy_task_id_is_accepted_when_id_is_absent():
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = job("completed")
+        del body["id"]  # older responses only carried task_id
+        return httpx.Response(200, json=body)
+
+    c = client_with(handler)
+    assert c.videos.retrieve("task_abc").id == "task_abc"
+
+
+def test_raw_keeps_unmodelled_fields():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json=job("completed", future_field={"a": 1}))
+
+    c = client_with(handler)
+    assert c.videos.retrieve("task_abc").raw["future_field"] == {"a": 1}