Metadata-Version: 2.4
Name: varya-avataar
Version: 0.1.2
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`.


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 snow leopard prowling the Himalayan slopes at dawn",
    resolution="480p",   # "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`, `--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`,
`image_path` (image-to-video). The output is always watermarked.

> 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