varya-avataar 0.1.0__tar.gz

varya_avataar-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+
+# Local artifacts
+*.mp4
+.DS_Store
+
+# Local-only dev scripts & examples (not part of the published package)
+smoke_test.py
+examples/

varya_avataar-0.1.0/LICENSE

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

varya_avataar-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: varya-avataar
+Version: 0.1.0
+Summary: Python client for the Varya video generation API
+Project-URL: Homepage, https://varya.avataar.ai
+Project-URL: Documentation, https://github.com/SoulVisionCreations/varya-python#readme
+Project-URL: Source, https://github.com/SoulVisionCreations/varya-python
+Author: Varya
+License: MIT
+License-File: LICENSE
+Keywords: ai,api,generation,sdk,text-to-video,varya,video
+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 :: Only
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# varya-avataar (Python)
+
+Python client for the **Varya** video generation API. Submit a text (or image)
+prompt, and the client handles the async job lifecycle — submit, poll, and
+download — for you.
+
+## Install
+
+```bash
+pip install varya-avataar
+```
+
+> Installs as `varya-avataar` on PyPI but **imports as `varya`**:
+> `from varya import VaryaClient`.
+
+While developing locally (from this folder):
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.8+ and `[requests](https://pypi.org/project/requests/)`.
+
+## Authentication
+
+Create a key in the Varya web app (**Account menu → API key**). It looks like
+`sk_live_…`. Keep it secret; it draws down your account's credit balance.
+
+```bash
+export VARYA_API_KEY=sk_live_xxxxx
+```
+
+## Quick start
+
+```python
+from varya import VaryaClient
+
+client = VaryaClient(api_key="sk_live_xxxxx")
+
+result = client.generate_video(
+    "a doctor making a shorts video on health",
+    resolution="720p",   # "480p" | "720p"
+    duration=5,           # seconds, 1–5
+    on_status=print,      # optional progress callback
+)
+
+print(result["video_url"])
+client.download(result["video_url"], "out.mp4")
+```
+
+> For a full end-to-end walkthrough (text-to-video **and** image-to-video,
+> saving the output, error handling), see **[USAGE.md](./USAGE.md)**.
+
+`VaryaClient` is also a context manager (`with VaryaClient(...) as client:`)
+which closes the underlying HTTP session on exit.
+
+## CLI
+
+Installing the package also installs a `varya` command:
+
+```bash
+# create a new video and download it
+varya "a cat surfing a wave" --resolution 720p --output out.mp4
+
+# resume / fetch an existing generation (no prompt, nothing re-charged)
+varya --get gen_xxxxxxxx --output out.mp4
+```
+
+Run `varya --help` for all flags (`--duration`, `--resolution`, `--style`,
+`--seed`, `--enhance`, `--watermark`, `--image`, `--timeout`, …).
+
+The key is read from `--key` or `$VARYA_API_KEY`; the base URL from
+`--base-url` or `$VARYA_BASE_URL`.
+
+## API
+
+### `VaryaClient(api_key, base_url=..., auth_scheme="x-api-key", connect_timeout=15, read_timeout=60)`
+
+
+| Method                                                              | Description                                                                                   |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `generate_video(prompt, **opts)`                                    | Submit **and** wait. Returns the final result `dict`. The 90% path.                           |
+| `submit(prompt, **opts)`                                            | `POST /api/generations`; returns `{ generation_id, status, credits_charged, … }` without waiting. |
+| `status(generation_id)`                                             | `GET /generations/{id}`; current status/result.                                               |
+| `wait(generation_id, poll_interval=2, timeout=600, on_status=None)` | Poll until `completed`/`failed`.                                                              |
+| `download(url, dest)`                                               | Stream a finished video URL to a local file.                                                  |
+
+
+**Generation options** (for `generate_video` / `submit`): `resolution`
+(`"480p"` / `"720p"`), `duration` (1–5 s), `style`, `seed`, `enhance`,
+`apply_watermark` (selects the logo; output is always watermarked), `image_path`
+(image-to-video).
+
+> Single-clip only: the client targets the streamlined `POST /api/generations`
+> endpoint, so there is no compare / long-form / continuation mode and `fps` is
+> fixed server-side. `duration` must be 1–5 (out-of-range raises
+> `LONG_FORM_NOT_SUPPORTED` before any request is sent).
+
+### Result shape
+
+- **completed**: `{ "status": "completed", "video_url": "https://…" }`
+- **failed**: `{ "status": "failed", "error": "…", "error_code": "…" }`
+
+### Errors
+
+Business/API failures raise `VaryaError` with a `.code` and `.status`:
+
+```python
+from varya import VaryaError
+
+try:
+    client.generate_video("…")
+except VaryaError as e:
+    if e.code == "INSUFFICIENT_CREDITS":
+        ...  # top up
+    elif e.code == "NSFW_CONTENT_BLOCKED":
+        ...  # adjust the prompt/image
+    else:
+        raise
+```
+
+## Notes
+
+- **Seed.** A `seed` is always sent. When you don't pass one it's randomized
+client-side (in `[100, 1_000_000)`, matching the web app) and returned on the
+result as `seed`, so you can reproduce a run by passing that same `seed` back.
+- **Async by design.** Jobs are queued; the client polls every ~2s — raise
+`timeout` if a job needs longer.
+- **Resilient polling.** One keep-alive connection is reused, idempotent `GET`s
+are retried with backoff, and transient network blips don't abort a run.
+`POST /api/generations` is never auto-retried, so a job is never double-charged.
+- **Auth header.** Defaults to `X-API-Key`. If your deployment expects
+`Authorization: Bearer`, pass `auth_scheme="bearer"`.
+- **Cost.** 1 credit (480p) / 2 (720p). The exact charge is returned as
+`credits_charged`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

varya_avataar-0.1.0/README.md

@@ -0,0 +1,146 @@
+# varya-avataar (Python)
+
+Python client for the **Varya** video generation API. Submit a text (or image)
+prompt, and the client handles the async job lifecycle — submit, poll, and
+download — for you.
+
+## Install
+
+```bash
+pip install varya-avataar
+```
+
+> Installs as `varya-avataar` on PyPI but **imports as `varya`**:
+> `from varya import VaryaClient`.
+
+While developing locally (from this folder):
+
+```bash
+pip install -e .
+```
+
+Requires Python 3.8+ and `[requests](https://pypi.org/project/requests/)`.
+
+## Authentication
+
+Create a key in the Varya web app (**Account menu → API key**). It looks like
+`sk_live_…`. Keep it secret; it draws down your account's credit balance.
+
+```bash
+export VARYA_API_KEY=sk_live_xxxxx
+```
+
+## Quick start
+
+```python
+from varya import VaryaClient
+
+client = VaryaClient(api_key="sk_live_xxxxx")
+
+result = client.generate_video(
+    "a doctor making a shorts video on health",
+    resolution="720p",   # "480p" | "720p"
+    duration=5,           # seconds, 1–5
+    on_status=print,      # optional progress callback
+)
+
+print(result["video_url"])
+client.download(result["video_url"], "out.mp4")
+```
+
+> For a full end-to-end walkthrough (text-to-video **and** image-to-video,
+> saving the output, error handling), see **[USAGE.md](./USAGE.md)**.
+
+`VaryaClient` is also a context manager (`with VaryaClient(...) as client:`)
+which closes the underlying HTTP session on exit.
+
+## CLI
+
+Installing the package also installs a `varya` command:
+
+```bash
+# create a new video and download it
+varya "a cat surfing a wave" --resolution 720p --output out.mp4
+
+# resume / fetch an existing generation (no prompt, nothing re-charged)
+varya --get gen_xxxxxxxx --output out.mp4
+```
+
+Run `varya --help` for all flags (`--duration`, `--resolution`, `--style`,
+`--seed`, `--enhance`, `--watermark`, `--image`, `--timeout`, …).
+
+The key is read from `--key` or `$VARYA_API_KEY`; the base URL from
+`--base-url` or `$VARYA_BASE_URL`.
+
+## API
+
+### `VaryaClient(api_key, base_url=..., auth_scheme="x-api-key", connect_timeout=15, read_timeout=60)`
+
+
+| Method                                                              | Description                                                                                   |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `generate_video(prompt, **opts)`                                    | Submit **and** wait. Returns the final result `dict`. The 90% path.                           |
+| `submit(prompt, **opts)`                                            | `POST /api/generations`; returns `{ generation_id, status, credits_charged, … }` without waiting. |
+| `status(generation_id)`                                             | `GET /generations/{id}`; current status/result.                                               |
+| `wait(generation_id, poll_interval=2, timeout=600, on_status=None)` | Poll until `completed`/`failed`.                                                              |
+| `download(url, dest)`                                               | Stream a finished video URL to a local file.                                                  |
+
+
+**Generation options** (for `generate_video` / `submit`): `resolution`
+(`"480p"` / `"720p"`), `duration` (1–5 s), `style`, `seed`, `enhance`,
+`apply_watermark` (selects the logo; output is always watermarked), `image_path`
+(image-to-video).
+
+> Single-clip only: the client targets the streamlined `POST /api/generations`
+> endpoint, so there is no compare / long-form / continuation mode and `fps` is
+> fixed server-side. `duration` must be 1–5 (out-of-range raises
+> `LONG_FORM_NOT_SUPPORTED` before any request is sent).
+
+### Result shape
+
+- **completed**: `{ "status": "completed", "video_url": "https://…" }`
+- **failed**: `{ "status": "failed", "error": "…", "error_code": "…" }`
+
+### Errors
+
+Business/API failures raise `VaryaError` with a `.code` and `.status`:
+
+```python
+from varya import VaryaError
+
+try:
+    client.generate_video("…")
+except VaryaError as e:
+    if e.code == "INSUFFICIENT_CREDITS":
+        ...  # top up
+    elif e.code == "NSFW_CONTENT_BLOCKED":
+        ...  # adjust the prompt/image
+    else:
+        raise
+```
+
+## Notes
+
+- **Seed.** A `seed` is always sent. When you don't pass one it's randomized
+client-side (in `[100, 1_000_000)`, matching the web app) and returned on the
+result as `seed`, so you can reproduce a run by passing that same `seed` back.
+- **Async by design.** Jobs are queued; the client polls every ~2s — raise
+`timeout` if a job needs longer.
+- **Resilient polling.** One keep-alive connection is reused, idempotent `GET`s
+are retried with backoff, and transient network blips don't abort a run.
+`POST /api/generations` is never auto-retried, so a job is never double-charged.
+- **Auth header.** Defaults to `X-API-Key`. If your deployment expects
+`Authorization: Bearer`, pass `auth_scheme="bearer"`.
+- **Cost.** 1 credit (480p) / 2 (720p). The exact charge is returned as
+`credits_charged`.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

varya_avataar-0.1.0/USAGE.md

@@ -0,0 +1,157 @@
+# Using `varya` (Python)
+
+A complete, copy-pasteable walkthrough that mirrors a real end-to-end run:
+submit a prompt, watch the status, and save the finished MP4. Covers both
+**text-to-video (T2V)** and **image-to-video (I2V)**.
+
+> Prerequisites: Python 3.8+ and an API key (`sk_live_…`) from the Varya web
+> app (**Account menu → API key**).
+
+## 1. Install & set your key
+
+```bash
+pip install varya-avataar   # installs as `varya-avataar`, imports as `varya`
+export VARYA_API_KEY=sk_live_xxxxx
+```
+
+Optionally override the API base URL (otherwise the SDK uses its built-in
+default):
+
+```bash
+export VARYA_BASE_URL=https://your-base-url   # only if you need a non-default host
+```
+
+## 2. Text-to-video, end-to-end
+
+This is the 90% path: `generate_video` submits the job **and** waits for it to
+finish, then you download the result. `VaryaClient` is a context manager, so
+use `with` to close the HTTP session cleanly.
+
+```python
+import os
+import sys
+
+from varya import VaryaClient, VaryaError
+
+api_key = os.environ["VARYA_API_KEY"]
+
+with VaryaClient(api_key) as client:
+    try:
+        result = client.generate_video(
+            "a doctor making a shorts video on health",
+            resolution="480p",   # "480p" (1 credit) | "720p" (2 credits)
+            duration=5,           # seconds, 1–5
+            style="none",         # "none" | "cinematic" | "anime" | …
+            seed=1762,            # omit (or None) for a random, reported seed
+            on_status=lambda s: print(f"status: {s}"),
+        )
+    except VaryaError as exc:
+        print(f"ERROR [{exc.code}] (HTTP {exc.status}): {exc}", file=sys.stderr)
+        raise SystemExit(1)
+
+    if result.get("status") == "failed":
+        print(f"failed: {result.get('error')} ({result.get('error_code')})")
+        raise SystemExit(1)
+
+    print("generation_id  :", result.get("generation_id"))
+    print("seed           :", result.get("seed"))
+    print("credits_charged:", result.get("credits_charged"))
+    print("video_url      :", result.get("video_url"))
+
+    client.download(result["video_url"], "out_t2v.mp4")
+    print("saved → out_t2v.mp4")
+```
+
+## 3. Image-to-video, end-to-end
+
+Pass `image_path` pointing at a local image; everything else is the same.
+
+```python
+import os
+
+from varya import VaryaClient
+
+with VaryaClient(os.environ["VARYA_API_KEY"]) as client:
+    result = client.generate_video(
+        "a watch floating on the water",
+        resolution="480p",
+        duration=5,
+        image_path="watch3.png",
+        on_status=lambda s: print(f"status: {s}"),
+    )
+
+    if result.get("status") == "failed":
+        raise SystemExit(f"{result.get('error')} ({result.get('error_code')})")
+
+    client.download(result["video_url"], "out_i2v.mp4")
+    print("saved → out_i2v.mp4")
+```
+
+## 4. Settings reference
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `resolution` | `"480p"` | `"480p"` = 1 credit, `"720p"` = 2 credits |
+| `duration` | `5` | seconds, `1`–`5` only (single clip) |
+| `style` | `"none"` | `none`, `cinematic`, `anime`, `documentary`, `product_ad`, `realistic`, `fantasy`, `cyberpunk`, `vintage_film` |
+| `seed` | random | pass an int to reproduce a run; the seed used is returned on the result |
+| `apply_watermark` | `False` | selects the watermark logo (`True` = brand logo); output is always watermarked |
+| `image_path` | — | switches to image-to-video |
+
+Polling options for `generate_video` / `wait`: `poll_interval` (default `2.0`),
+`timeout` (default `600.0`), `on_status`.
+
+## 5. Split submit / poll (advanced)
+
+If you don't want to block, submit and poll yourself:
+
+```python
+with VaryaClient(os.environ["VARYA_API_KEY"]) as client:
+    created = client.submit("a cat surfing a wave", resolution="720p")
+    gen_id = created["generation_id"]
+
+    # …later, or from another process:
+    result = client.wait(gen_id, on_status=print)
+    print(result["video_url"])
+
+    # or a single status check (no waiting):
+    snapshot = client.status(gen_id)
+    print(snapshot["status"])
+```
+
+## 6. Error handling
+
+API/business failures raise `VaryaError` with a machine-readable `.code` and
+HTTP `.status`:
+
+```python
+from varya import VaryaError
+
+try:
+    client.generate_video("…")
+except VaryaError as exc:
+    if exc.code == "INSUFFICIENT_CREDITS":
+        ...  # prompt the user to top up
+    elif exc.code == "NSFW_CONTENT_BLOCKED":
+        ...  # adjust the prompt/image
+    else:
+        raise
+```
+
+Note: a job that is accepted but ends unsuccessfully comes back as a normal
+result `dict` with `status == "failed"` (read `error` / `error_code`) — not as
+a raised `VaryaError`.
+
+## 7. CLI
+
+The package also installs a `varya` command:
+
+```bash
+# create and download a video
+varya "a cat surfing a wave" --resolution 720p --output out.mp4
+
+# fetch an existing generation (no prompt, nothing re-charged)
+varya --get <generation_id> --output out.mp4
+
+varya --help
+```

varya_avataar-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "varya-avataar"
+version = "0.1.0"
+description = "Python client for the Varya video generation API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Varya" }]
+keywords = ["varya", "video", "generation", "ai", "text-to-video", "api", "sdk"]
+dependencies = ["requests>=2.25"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Multimedia :: Video",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://varya.avataar.ai"
+Documentation = "https://github.com/SoulVisionCreations/varya-python#readme"
+Source = "https://github.com/SoulVisionCreations/varya-python"
+
+[project.scripts]
+varya = "varya.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/varya"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/varya", "README.md", "USAGE.md", "LICENSE", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

varya_avataar-0.1.0/src/varya/__init__.py

@@ -0,0 +1,10 @@
+"""Varya — Python client for the Varya video generation API.
+
+Public API:
+    from varya import VaryaClient, VaryaError, DEFAULT_BASE_URL
+"""
+
+from .client import DEFAULT_BASE_URL, VaryaClient, VaryaError
+
+__all__ = ["VaryaClient", "VaryaError", "DEFAULT_BASE_URL"]
+__version__ = "0.1.0"

varya_avataar-0.1.0/src/varya/cli.py

@@ -0,0 +1,98 @@
+"""Command-line interface: ``varya`` (and ``python -m varya``)."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from .client import DEFAULT_BASE_URL, VaryaClient, VaryaError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="varya", description="Generate a video with the Varya API."
+    )
+    parser.add_argument("prompt", nargs="?", help="Text prompt for the video.")
+    parser.add_argument(
+        "--get",
+        dest="get_id",
+        default=None,
+        help="Fetch/await an existing generation_id instead of creating one "
+        "(no prompt needed, nothing is re-charged).",
+    )
+    parser.add_argument(
+        "--key",
+        default=os.environ.get("VARYA_API_KEY"),
+        help="API key (sk_live_...). Defaults to $VARYA_API_KEY.",
+    )
+    parser.add_argument("--base-url", default=os.environ.get("VARYA_BASE_URL", DEFAULT_BASE_URL))
+    parser.add_argument("--auth-scheme", default="x-api-key", choices=["x-api-key", "bearer"])
+    parser.add_argument("--resolution", default="480p", choices=["480p", "720p"])
+    parser.add_argument("--duration", type=int, default=5, help="Seconds, 1-5.")
+    parser.add_argument("--style", default="none")
+    parser.add_argument("--seed", type=int, default=None)
+    parser.add_argument("--enhance", action="store_true")
+    parser.add_argument(
+        "--watermark",
+        action="store_true",
+        help="Use the primary brand logo (output is always watermarked).",
+    )
+    parser.add_argument("--image", default=None, help="Path to a reference image (I2V).")
+    parser.add_argument("--output", default=None, help="Download the result MP4 to this path.")
+    parser.add_argument("--timeout", type=float, default=600.0)
+    args = parser.parse_args(argv)
+
+    if not args.key:
+        print("error: no API key. Pass --key or set VARYA_API_KEY.", file=sys.stderr)
+        return 2
+    if not args.prompt and not args.get_id:
+        print("error: provide a prompt, or --get <generation_id>.", file=sys.stderr)
+        return 2
+
+    client = VaryaClient(args.key, base_url=args.base_url, auth_scheme=args.auth_scheme)
+
+    try:
+        if args.get_id:
+            result = client.wait(
+                args.get_id, timeout=args.timeout, on_status=lambda s: print(f"… {s}")
+            )
+            result.setdefault("generation_id", args.get_id)
+        else:
+            result = client.generate_video(
+                args.prompt,
+                resolution=args.resolution,
+                duration=args.duration,
+                style=args.style,
+                seed=args.seed,
+                enhance=args.enhance,
+                apply_watermark=args.watermark,
+                image_path=args.image,
+                timeout=args.timeout,
+                on_status=lambda s: print(f"… {s}"),
+            )
+    except VaryaError as exc:
+        print(f"error [{exc.code}]: {exc}", file=sys.stderr)
+        return 1
+
+    if result.get("status") == "failed":
+        print(f"failed: {result.get('error')} ({result.get('error_code')})", file=sys.stderr)
+        return 1
+
+    video_url = result.get("video_url")
+    print(
+        f"done — generation_id={result.get('generation_id')} "
+        f"seed={result.get('seed')} credits={result.get('credits_charged')}"
+    )
+    if video_url:
+        print(f"video_url: {video_url}")
+
+    if args.output and video_url:
+        client.download(video_url, args.output)
+        print(f"saved → {args.output}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

varya_avataar-0.1.0/src/varya/client.py

@@ -0,0 +1,313 @@
+"""Core client for the Varya video generation API.
+
+The API is asynchronous: you submit a job (`POST /api/generations`) and poll
+(`GET /generations/{id}`) until it is ``completed`` or ``failed``. This module
+wraps that flow with connection reuse and automatic backoff retries on
+idempotent requests so transient network blips don't abort a run.
+
+The SDK targets the streamlined single-clip endpoint: no compare / long-form /
+continuation mode, ``fps`` is fixed server-side, and ``duration`` is 1-5s.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+import random
+import time
+from typing import Any, Callable, Dict, Optional
+
+import requests
+from requests.adapters import HTTPAdapter
+
+try:  # urllib3 ships with requests; import path is stable across versions
+    from urllib3.util.retry import Retry
+except Exception:  # pragma: no cover - extremely old urllib3
+    Retry = None
+
+DEFAULT_BASE_URL = "https://video-backend.avataar.ai"
+
+# Matches the web app's seed range: [SEED_MIN, SEED_MAX).
+SEED_MIN = 100
+SEED_MAX = 1_000_000
+
+__all__ = ["VaryaClient", "VaryaError", "DEFAULT_BASE_URL"]
+
+
+class VaryaError(RuntimeError):
+    """Raised for API / business errors.
+
+    Attributes
+    ----------
+    code:
+        Machine-readable code from the backend (e.g. ``NSFW_CONTENT_BLOCKED``,
+        ``INSUFFICIENT_CREDITS``, ``GENERATION_NOT_FOUND``) or a client-side code
+        like ``TIMEOUT`` / ``NO_ID``.
+    status:
+        HTTP status code when the error originated from a response.
+    """
+
+    def __init__(self, message: str, *, code: str = "UNKNOWN", status: int = 0) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class VaryaClient:
+    """Thin, dependency-light wrapper over the Varya ``/api/generations`` pipeline.
+
+    Parameters
+    ----------
+    api_key:
+        A user API key (``sk_live_...``) minted from the Varya web app
+        (Account menu -> API key).
+    base_url:
+        API base URL. Defaults to the public production endpoint.
+    auth_scheme:
+        How the key is sent. ``"x-api-key"`` (default) sends an ``X-API-Key``
+        header; ``"bearer"`` sends ``Authorization: Bearer <key>``.
+    connect_timeout / read_timeout:
+        Per-request connect and read timeouts in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        auth_scheme: str = "x-api-key",
+        connect_timeout: float = 15.0,
+        read_timeout: float = 60.0,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.auth_scheme = auth_scheme.lower()
+        self.timeout = (connect_timeout, read_timeout)
+
+        # One keep-alive session reused for every call: avoids opening a fresh
+        # TCP/TLS connection per poll and adds backoff retries for transient,
+        # idempotent GET failures. POST is intentionally NOT auto-retried so a
+        # generation is never accidentally submitted (and charged) twice.
+        self._session = requests.Session()
+        if Retry is not None:
+            retry = Retry(
+                total=5,
+                connect=5,
+                read=3,
+                backoff_factor=1.5,
+                status_forcelist=(429, 500, 502, 503, 504),
+                allowed_methods=frozenset({"GET"}),
+                raise_on_status=False,
+            )
+            adapter = HTTPAdapter(max_retries=retry)
+            self._session.mount("https://", adapter)
+            self._session.mount("http://", adapter)
+
+    # -- internals ---------------------------------------------------------
+
+    def _auth_headers(self) -> Dict[str, str]:
+        if self.auth_scheme == "bearer":
+            return {"Authorization": f"Bearer {self.api_key}"}
+        return {"X-API-Key": self.api_key}
+
+    def _unwrap(self, resp: requests.Response) -> Dict[str, Any]:
+        """Parse the standard ``{ success, data, error }`` envelope.
+
+        FastAPI-level auth/transport errors arrive as ``{ "detail": ... }`` and
+        are converted to :class:`VaryaError` too.
+        """
+        try:
+            payload = resp.json()
+        except ValueError:
+            raise VaryaError(
+                f"Non-JSON response (HTTP {resp.status_code}): {resp.text[:200]}",
+                status=resp.status_code,
+            )
+
+        if isinstance(payload, dict) and "detail" in payload and "success" not in payload:
+            detail = payload["detail"]
+            msg = detail if isinstance(detail, str) else str(detail)
+            raise VaryaError(msg, code="HTTP_ERROR", status=resp.status_code)
+
+        if not isinstance(payload, dict):
+            raise VaryaError("Unexpected response shape", status=resp.status_code)
+
+        if payload.get("success") is False:
+            err = payload.get("error") or {}
+            raise VaryaError(
+                err.get("message") or "Request failed",
+                code=err.get("code") or "ERROR",
+                status=resp.status_code,
+            )
+
+        return payload.get("data") or {}
+
+    # -- public API --------------------------------------------------------
+
+    def submit(
+        self,
+        prompt: str,
+        *,
+        resolution: str = "480p",
+        duration: int = 5,
+        style: str = "none",
+        seed: Optional[int] = None,
+        enhance: bool = False,
+        apply_watermark: bool = False,
+        image_path: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """``POST /api/generations`` — enqueue a single-clip job.
+
+        Returns the created job's ``data`` (``generation_id``, ``status``,
+        ``credits_charged``, ...) plus the ``seed`` that was used. Does not wait
+        for completion; use :meth:`wait` or :meth:`generate_video` for that.
+
+        This is the streamlined SDK endpoint: **single clip only** (no compare,
+        long-form, or continuation), ``fps`` is fixed server-side, and
+        ``duration`` must be **1-5 seconds**. The output is always watermarked;
+        ``apply_watermark`` only selects which logo is overlaid.
+
+        ``seed`` is always sent: when omitted it is randomized client-side (in
+        ``[100, 1_000_000)``, matching the web app) and returned so the run is
+        reproducible — pass the same ``seed`` to repeat it.
+        """
+        if not prompt or not prompt.strip():
+            raise ValueError("prompt is required")
+
+        # Single-clip only; fail fast instead of round-tripping to a server
+        # ``LONG_FORM_NOT_SUPPORTED``.
+        if not isinstance(duration, int) or not (1 <= duration <= 5):
+            raise VaryaError(
+                "duration must be an integer between 1 and 5 (single clip only)",
+                code="LONG_FORM_NOT_SUPPORTED",
+            )
+
+        if seed is None:
+            seed = random.randint(SEED_MIN, SEED_MAX - 1)
+
+        # The endpoint expects multipart/form-data even with no image attached;
+        # requests sends multipart when every field is passed through `files`.
+        fields: Dict[str, Any] = {
+            "prompt": prompt,
+            "resolution": resolution,
+            "duration": duration,
+            "style": style,
+            "seed": seed,
+            "enhance": str(enhance).lower(),
+            "apply_watermark": str(apply_watermark).lower(),
+        }
+
+        parts = [(k, (None, str(v))) for k, v in fields.items()]
+
+        opened = None
+        if image_path:
+            mime = mimetypes.guess_type(image_path)[0] or "application/octet-stream"
+            opened = open(image_path, "rb")
+            parts.append(("image", (os.path.basename(image_path), opened, mime)))
+
+        try:
+            resp = self._session.post(
+                f"{self.base_url}/api/generations",
+                headers=self._auth_headers(),
+                files=parts,
+                timeout=self.timeout,
+            )
+        finally:
+            if opened:
+                opened.close()
+
+        data = self._unwrap(resp)
+        data.setdefault("seed", seed)
+        return data
+
+    def status(self, generation_id: str) -> Dict[str, Any]:
+        """``GET /generations/{id}`` — current status / result ``data``."""
+        resp = self._session.get(
+            f"{self.base_url}/generations/{generation_id}",
+            headers=self._auth_headers(),
+            timeout=self.timeout,
+        )
+        return self._unwrap(resp)
+
+    def wait(
+        self,
+        generation_id: str,
+        *,
+        poll_interval: float = 2.0,
+        timeout: float = 600.0,
+        on_status: Optional[Callable[[str], None]] = None,
+    ) -> Dict[str, Any]:
+        """Poll until the job is ``completed`` / ``failed`` or ``timeout`` elapses.
+
+        Transient network errors are tolerated: the job keeps running
+        server-side, so polling resumes after a short wait rather than raising.
+        """
+        start = time.monotonic()
+        last = None
+        while time.monotonic() - start < timeout:
+            try:
+                data = self.status(generation_id)
+            except requests.exceptions.RequestException as exc:
+                if on_status and last != "_reconnecting":
+                    on_status(f"network hiccup, retrying… ({type(exc).__name__})")
+                    last = "_reconnecting"
+                time.sleep(poll_interval)
+                continue
+            state = data.get("status")
+            if on_status and state != last:
+                on_status(state)
+                last = state
+            if state in ("completed", "failed"):
+                return data
+            time.sleep(poll_interval)
+        raise VaryaError("Timed out waiting for the generation to finish", code="TIMEOUT")
+
+    def generate_video(
+        self,
+        prompt: str,
+        *,
+        poll_interval: float = 2.0,
+        timeout: float = 600.0,
+        on_status: Optional[Callable[[str], None]] = None,
+        **submit_kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Submit a job and wait for it. Returns the final status ``data``.
+
+        On success the result has ``video_url``; on failure it has ``error``
+        (and an optional ``error_code``).
+        """
+        created = self.submit(prompt, **submit_kwargs)
+        gen_id = created.get("generation_id")
+        if not gen_id:
+            raise VaryaError("No generation_id returned from submit", code="NO_ID")
+        result = self.wait(
+            gen_id,
+            poll_interval=poll_interval,
+            timeout=timeout,
+            on_status=on_status,
+        )
+        result.setdefault("generation_id", gen_id)
+        result.setdefault("credits_charged", created.get("credits_charged"))
+        result.setdefault("seed", created.get("seed"))
+        return result
+
+    def download(self, url: str, dest: str, timeout: float = 120.0) -> str:
+        """Stream a finished video URL to a local file. Returns ``dest``."""
+        with self._session.get(url, stream=True, timeout=(self.timeout[0], timeout)) as resp:
+            resp.raise_for_status()
+            with open(dest, "wb") as fh:
+                for chunk in resp.iter_content(chunk_size=1 << 16):
+                    if chunk:
+                        fh.write(chunk)
+        return dest
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> "VaryaClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

varya_avataar-0.1.0/tests/test_client.py

@@ -0,0 +1,180 @@
+"""Unit tests for the Varya Python client.
+
+No network: the HTTP session is replaced with a fake that returns canned
+responses, so these run fast and offline.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+
+from varya import VaryaClient, VaryaError
+
+
+class FakeResponse:
+    def __init__(self, payload, status_code=200, text=""):
+        self._payload = payload
+        self.status_code = status_code
+        self.text = text
+
+    def json(self):
+        if self._payload is _NO_JSON:
+            raise ValueError("no json")
+        return self._payload
+
+    def raise_for_status(self):
+        if self.status_code >= 400:
+            raise requests.exceptions.HTTPError(response=self)
+
+
+_NO_JSON = object()
+
+
+def make_client():
+    client = VaryaClient(api_key="sk_live_test")
+    client._session = MagicMock()
+    return client
+
+
+def envelope(data=None, success=True, error=None):
+    return {"success": success, "data": data, "error": error}
+
+
+def test_requires_api_key():
+    with pytest.raises(ValueError):
+        VaryaClient(api_key="")
+
+
+def test_auth_header_default_is_x_api_key():
+    client = VaryaClient(api_key="sk_live_abc")
+    assert client._auth_headers() == {"X-API-Key": "sk_live_abc"}
+
+
+def test_auth_header_bearer():
+    client = VaryaClient(api_key="sk_live_abc", auth_scheme="bearer")
+    assert client._auth_headers() == {"Authorization": "Bearer sk_live_abc"}
+
+
+def test_submit_sends_multipart_fields_and_returns_data():
+    client = make_client()
+    client._session.post.return_value = FakeResponse(
+        envelope({"generation_id": "gen_1", "status": "queued", "credits_charged": 1})
+    )
+
+    data = client.submit("a cat", resolution="720p", duration=5)
+
+    assert data["generation_id"] == "gen_1"
+    # Verify it posted to /api/generations as multipart (files=...).
+    args, kwargs = client._session.post.call_args
+    assert args[0].endswith("/api/generations")
+    files = kwargs["files"]
+    sent = {name: part[1] for name, part in files}
+    assert sent["prompt"] == "a cat"
+    assert sent["resolution"] == "720p"
+    # Single-clip endpoint: these are no longer sent.
+    assert "mode" not in sent
+    assert "fps" not in sent
+
+
+def test_submit_sends_random_seed_and_returns_it():
+    client = make_client()
+    client._session.post.return_value = FakeResponse(
+        envelope({"generation_id": "gen_s", "status": "queued"})
+    )
+    data = client.submit("a cat")
+    _, kwargs = client._session.post.call_args
+    sent = {name: part[1] for name, part in kwargs["files"]}
+    assert "seed" in sent  # always sent, even when caller omits it
+    assert 100 <= int(sent["seed"]) < 1_000_000
+    assert int(sent["seed"]) == data["seed"]  # surfaced back to the caller
+
+
+def test_submit_honors_provided_seed():
+    client = make_client()
+    client._session.post.return_value = FakeResponse(
+        envelope({"generation_id": "gen_s", "status": "queued"})
+    )
+    data = client.submit("a cat", seed=12345)
+    _, kwargs = client._session.post.call_args
+    sent = {name: part[1] for name, part in kwargs["files"]}
+    assert sent["seed"] == "12345"
+    assert data["seed"] == 12345
+
+
+def test_submit_rejects_empty_prompt():
+    client = make_client()
+    with pytest.raises(ValueError):
+        client.submit("   ")
+
+
+def test_submit_rejects_out_of_range_duration():
+    client = make_client()
+    with pytest.raises(VaryaError) as ei:
+        client.submit("a cat", duration=8)
+    assert ei.value.code == "LONG_FORM_NOT_SUPPORTED"
+    # Nothing should have been sent to the server.
+    client._session.post.assert_not_called()
+
+
+def test_business_error_raises_varya_error_with_code():
+    client = make_client()
+    client._session.post.return_value = FakeResponse(
+        envelope(success=False, error={"code": "INSUFFICIENT_CREDITS", "message": "need 2, have 0"})
+    )
+    with pytest.raises(VaryaError) as ei:
+        client.submit("a cat")
+    assert ei.value.code == "INSUFFICIENT_CREDITS"
+    assert "need 2" in str(ei.value)
+
+
+def test_detail_error_raises_varya_error():
+    client = make_client()
+    client._session.get.return_value = FakeResponse(
+        {"detail": "This endpoint requires a Firebase ID token, not an API key."},
+        status_code=401,
+    )
+    with pytest.raises(VaryaError) as ei:
+        client.status("gen_x")
+    assert ei.value.status == 401
+    assert ei.value.code == "HTTP_ERROR"
+
+
+def test_generate_video_submits_then_polls_to_completion():
+    client = make_client()
+    client._session.post.return_value = FakeResponse(
+        envelope({"generation_id": "gen_2", "status": "queued", "credits_charged": 2})
+    )
+    client._session.get.side_effect = [
+        FakeResponse(envelope({"status": "processing"})),
+        FakeResponse(envelope({"status": "completed", "video_url": "https://cdn/v.mp4"})),
+    ]
+
+    seen = []
+    result = client.generate_video(
+        "a cat", resolution="720p", poll_interval=0, on_status=seen.append
+    )
+
+    assert result["status"] == "completed"
+    assert result["video_url"] == "https://cdn/v.mp4"
+    assert result["generation_id"] == "gen_2"
+    assert result["credits_charged"] == 2
+    assert "completed" in seen
+
+
+def test_wait_tolerates_transient_network_errors():
+    client = make_client()
+    client._session.get.side_effect = [
+        requests.exceptions.ConnectTimeout("boom"),
+        FakeResponse(envelope({"status": "completed", "video_url": "https://cdn/v.mp4"})),
+    ]
+    result = client.wait("gen_3", poll_interval=0, timeout=5)
+    assert result["status"] == "completed"
+
+
+def test_wait_times_out():
+    client = make_client()
+    client._session.get.return_value = FakeResponse(envelope({"status": "processing"}))
+    with pytest.raises(VaryaError) as ei:
+        client.wait("gen_4", poll_interval=0, timeout=0.05)
+    assert ei.value.code == "TIMEOUT"