varya-avataar 0.1.2

Python client for the Varya video generation API

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

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.

export VARYA_API_KEY=sk_live_xxxxx

Quick start

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.

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:

# 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:

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 GETs 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

pip install -e ".[dev]"
pytest

License

MIT