tanvo 0.1.0__tar.gz

tanvo-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+# Publishes to PyPI when a version tag (v0.1.0, …) is pushed. Uses PyPI trusted publishing: no token is stored here.
+# One-time setup on pypi.org: add a trusted publisher for this repository, workflow "publish.yml", environment "pypi".
+name: publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: python -m unittest discover -s tests
+      - run: python -m pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

tanvo-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,14 @@
+name: test
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m unittest discover -s tests -v

tanvo-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

tanvo-0.1.0/LICENSE

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

tanvo-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: tanvo
+Version: 0.1.0
+Summary: Python client for Tanvo: AI images, video and songs on Nano Banana, Seedream, GPT Image, Veo, Kling, Seedance and Suno, plus 80 ready-made photo apps. No dependencies; the house image engine works without an API key.
+Project-URL: Homepage, https://tanvo.ai/?utm_source=pypi&utm_medium=referral
+Project-URL: Documentation, https://github.com/tanvoai/tanvo-python#readme
+Project-URL: Repository, https://github.com/tanvoai/tanvo-python
+Project-URL: Issues, https://github.com/tanvoai/tanvo-python/issues
+Author-email: Tanvo <support@tanvo.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai image generator,ai music,ai video generator,api,image to video,kling,nano banana,seedance,seedream,suno,tanvo,text to image,text to video,veo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Tanvo for Python
+
+[![PyPI](https://img.shields.io/pypi/v/tanvo)](https://pypi.org/project/tanvo/) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+The Python client for [Tanvo](https://tanvo.ai/?utm_source=github&utm_medium=referral), an AI image, video and music studio. Generate images on Nano Banana, Seedream, GPT Image and Qwen, video on Veo, Kling, Seedance and Wan, and songs on Suno, or run one of 80 ready-made photo apps (pet portraits, figurines, old photo restoration, trend videos) on your own photos.
+
+- No dependencies: only the standard library. Python 3.9+.
+- **Works without an API key** on the free tier (house image engine, watermarked).
+- Local files are uploaded for you; results download with one call.
+- Retries that never double-charge (every submit carries an idempotency key).
+
+```bash
+pip install tanvo
+```
+
+## Quick start
+
+```python
+import tanvo
+
+client = tanvo.Client()  # reads TANVO_API_KEY; without one it runs on the free tier
+image = client.generate_image("a paper lantern floating over a misty lake at dawn", aspect="16:9")
+print(image.url)
+client.download(image, "out/")
+```
+
+Create a key under [Settings → API keys](https://tanvo.ai/settings/apikeys?utm_source=github&utm_medium=referral) to use every model, get clean output and have runs land in your history.
+
+```python
+client = tanvo.Client("sk_...")  # or export TANVO_API_KEY=sk_...
+```
+
+## Ready-made apps
+
+Each app has preset looks: a tuned prompt, model and settings with a real example output.
+
+```python
+for app in client.apps(kind="image")[:5]:
+    print(app.slug, "-", app.name, [look.id for look in app.looks])
+
+portrait = client.generate_from_app(
+    "ai-pet-portrait-generator",
+    look="royal",
+    photos=["rex.jpg"],          # local path, https URL or bytes, in the order of app.inputs
+    details="Rex, a very good boy",
+)
+client.download(portrait, "out/")
+```
+
+## Images
+
+```python
+# Text to image on any model (see client.models("image") for ids, options and prices)
+img = client.generate_image("isometric cutaway of a tiny ramen shop", model="nano-banana-2", resolution="2K")
+
+# Edit or combine photos: describe what to change and what to keep
+edit = client.generate_image(
+    "change the jacket to dark green; keep the face, pose and background exactly as they are",
+    model="nano-banana-2",
+    images=["portrait.jpg"],
+)
+```
+
+## Video
+
+Video takes one to several minutes, so `generate_video` returns at once by default.
+
+```python
+job = client.generate_video(
+    "slow dolly-in on a lighthouse in a storm, waves crashing, cinematic",
+    model="kling-3-0", aspect="16:9", resolution="720p", duration=5,
+)
+clip = client.wait(job.id)        # or pass wait=True above
+client.download(clip, "out/")
+
+# Image to video, with an optional end frame on models that support it
+client.generate_video("the cat turns its head and blinks", model="seedance-2-5", image="cat.jpg", wait=True)
+```
+
+## Songs
+
+Two takes per run, each an MP3 with cover art, a title and the lyrics as sung.
+
+```python
+song = client.generate_music(
+    "an upbeat birthday song for my sister Ana: surfing, terrible puns, a big singalong chorus",
+    style="acoustic pop, hand claps, warm female vocal",
+)
+for take in song.outputs:
+    print(take.title, take.seconds, take.url, take.cover)
+
+client.generate_music("[Verse]\n...\n[Chorus]\n...", mode="Lyrics", title="Ana Rides Again", vocal="f")
+client.generate_music("mellow lo-fi study beat, vinyl crackle, 75 bpm", mode="Instrumental")
+```
+
+## Runs, history and webhooks
+
+```python
+g = client.get("cm...")                # one run
+items, next_before = client.list(limit=20)
+
+# Skip polling: have the result POSTed to you when it finishes
+client.generate_video("...", model="veo-3-1", webhook_url="https://example.com/hooks/tanvo")
+
+# In your web handler, verify with the secret from Settings → Webhooks (pass the raw body)
+generation = tanvo.verify_webhook(secret, request.headers, request.get_data())
+```
+
+Webhooks can arrive more than once; de-duplicate on the `webhook-id` header.
+
+## Errors
+
+| Exception | When | What to do |
+|---|---|---|
+| `InvalidRequest` | Bad option, refused prompt, file too large | Fix the input |
+| `AuthError` | Missing or invalid key | Check the key |
+| `QuotaError` | Out of credits, free tier limit, `busy` | Top up, add a key, or wait (`wait_for_slot=True` waits for a free slot) |
+| `ServiceError` | Upstream model or network failure | Already retried twice with the same request key; try again later |
+
+All carry `.code` (stable string), `.message` and `.status`. Failed runs are refunded automatically.
+
+## Settings
+
+| | |
+|---|---|
+| `TANVO_API_KEY` | API key (or `Client(api_key=...)`) |
+| `TANVO_BASE_URL` | Another deployment (default `https://tanvo.ai`) |
+
+## Also from Tanvo
+
+- [tanvo-mcp](https://github.com/tanvoai/tanvo-mcp): the same apps and models inside Claude, Cursor and other MCP clients.
+- [tanvo-js](https://github.com/tanvoai/tanvo-js): the TypeScript / JavaScript client.
+
+## License
+
+MIT

tanvo-0.1.0/README.md

@@ -0,0 +1,136 @@
+# Tanvo for Python
+
+[![PyPI](https://img.shields.io/pypi/v/tanvo)](https://pypi.org/project/tanvo/) [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+The Python client for [Tanvo](https://tanvo.ai/?utm_source=github&utm_medium=referral), an AI image, video and music studio. Generate images on Nano Banana, Seedream, GPT Image and Qwen, video on Veo, Kling, Seedance and Wan, and songs on Suno, or run one of 80 ready-made photo apps (pet portraits, figurines, old photo restoration, trend videos) on your own photos.
+
+- No dependencies: only the standard library. Python 3.9+.
+- **Works without an API key** on the free tier (house image engine, watermarked).
+- Local files are uploaded for you; results download with one call.
+- Retries that never double-charge (every submit carries an idempotency key).
+
+```bash
+pip install tanvo
+```
+
+## Quick start
+
+```python
+import tanvo
+
+client = tanvo.Client()  # reads TANVO_API_KEY; without one it runs on the free tier
+image = client.generate_image("a paper lantern floating over a misty lake at dawn", aspect="16:9")
+print(image.url)
+client.download(image, "out/")
+```
+
+Create a key under [Settings → API keys](https://tanvo.ai/settings/apikeys?utm_source=github&utm_medium=referral) to use every model, get clean output and have runs land in your history.
+
+```python
+client = tanvo.Client("sk_...")  # or export TANVO_API_KEY=sk_...
+```
+
+## Ready-made apps
+
+Each app has preset looks: a tuned prompt, model and settings with a real example output.
+
+```python
+for app in client.apps(kind="image")[:5]:
+    print(app.slug, "-", app.name, [look.id for look in app.looks])
+
+portrait = client.generate_from_app(
+    "ai-pet-portrait-generator",
+    look="royal",
+    photos=["rex.jpg"],          # local path, https URL or bytes, in the order of app.inputs
+    details="Rex, a very good boy",
+)
+client.download(portrait, "out/")
+```
+
+## Images
+
+```python
+# Text to image on any model (see client.models("image") for ids, options and prices)
+img = client.generate_image("isometric cutaway of a tiny ramen shop", model="nano-banana-2", resolution="2K")
+
+# Edit or combine photos: describe what to change and what to keep
+edit = client.generate_image(
+    "change the jacket to dark green; keep the face, pose and background exactly as they are",
+    model="nano-banana-2",
+    images=["portrait.jpg"],
+)
+```
+
+## Video
+
+Video takes one to several minutes, so `generate_video` returns at once by default.
+
+```python
+job = client.generate_video(
+    "slow dolly-in on a lighthouse in a storm, waves crashing, cinematic",
+    model="kling-3-0", aspect="16:9", resolution="720p", duration=5,
+)
+clip = client.wait(job.id)        # or pass wait=True above
+client.download(clip, "out/")
+
+# Image to video, with an optional end frame on models that support it
+client.generate_video("the cat turns its head and blinks", model="seedance-2-5", image="cat.jpg", wait=True)
+```
+
+## Songs
+
+Two takes per run, each an MP3 with cover art, a title and the lyrics as sung.
+
+```python
+song = client.generate_music(
+    "an upbeat birthday song for my sister Ana: surfing, terrible puns, a big singalong chorus",
+    style="acoustic pop, hand claps, warm female vocal",
+)
+for take in song.outputs:
+    print(take.title, take.seconds, take.url, take.cover)
+
+client.generate_music("[Verse]\n...\n[Chorus]\n...", mode="Lyrics", title="Ana Rides Again", vocal="f")
+client.generate_music("mellow lo-fi study beat, vinyl crackle, 75 bpm", mode="Instrumental")
+```
+
+## Runs, history and webhooks
+
+```python
+g = client.get("cm...")                # one run
+items, next_before = client.list(limit=20)
+
+# Skip polling: have the result POSTed to you when it finishes
+client.generate_video("...", model="veo-3-1", webhook_url="https://example.com/hooks/tanvo")
+
+# In your web handler, verify with the secret from Settings → Webhooks (pass the raw body)
+generation = tanvo.verify_webhook(secret, request.headers, request.get_data())
+```
+
+Webhooks can arrive more than once; de-duplicate on the `webhook-id` header.
+
+## Errors
+
+| Exception | When | What to do |
+|---|---|---|
+| `InvalidRequest` | Bad option, refused prompt, file too large | Fix the input |
+| `AuthError` | Missing or invalid key | Check the key |
+| `QuotaError` | Out of credits, free tier limit, `busy` | Top up, add a key, or wait (`wait_for_slot=True` waits for a free slot) |
+| `ServiceError` | Upstream model or network failure | Already retried twice with the same request key; try again later |
+
+All carry `.code` (stable string), `.message` and `.status`. Failed runs are refunded automatically.
+
+## Settings
+
+| | |
+|---|---|
+| `TANVO_API_KEY` | API key (or `Client(api_key=...)`) |
+| `TANVO_BASE_URL` | Another deployment (default `https://tanvo.ai`) |
+
+## Also from Tanvo
+
+- [tanvo-mcp](https://github.com/tanvoai/tanvo-mcp): the same apps and models inside Claude, Cursor and other MCP clients.
+- [tanvo-js](https://github.com/tanvoai/tanvo-js): the TypeScript / JavaScript client.
+
+## License
+
+MIT

tanvo-0.1.0/examples/pet_portrait.py

@@ -0,0 +1,11 @@
+"""python examples/pet_portrait.py rex.jpg: a royal portrait of your pet (needs TANVO_API_KEY)."""
+import sys
+
+import tanvo
+
+client = tanvo.Client()
+app = client.app("ai-pet-portrait-generator")
+print("Looks:", ", ".join(f"{l.id} ({l.name})" for l in app.looks))
+result = client.generate_from_app(app.slug, look="royal", photos=[sys.argv[1]])
+print(result.status, result.url)
+print("saved to", client.download(result, "out/"))

tanvo-0.1.0/examples/quickstart.py

@@ -0,0 +1,7 @@
+"""python examples/quickstart.py: one free image, no API key needed."""
+import tanvo
+
+client = tanvo.Client()
+image = client.generate_image("a paper lantern floating over a misty lake at dawn", aspect="16:9")
+print(image.status, image.url)
+print("saved to", client.download(image, "out/"))

tanvo-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tanvo"
+version = "0.1.0"
+description = "Python client for Tanvo: AI images, video and songs on Nano Banana, Seedream, GPT Image, Veo, Kling, Seedance and Suno, plus 80 ready-made photo apps. No dependencies; the house image engine works without an API key."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Tanvo", email = "support@tanvo.ai" }]
+keywords = ["tanvo", "ai image generator", "ai video generator", "text to image", "image to video", "text to video", "ai music", "nano banana", "seedream", "kling", "veo", "seedance", "suno", "api"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://tanvo.ai/?utm_source=pypi&utm_medium=referral"
+Documentation = "https://github.com/tanvoai/tanvo-python#readme"
+Repository = "https://github.com/tanvoai/tanvo-python"
+Issues = "https://github.com/tanvoai/tanvo-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tanvo"]

tanvo-0.1.0/src/tanvo/__init__.py

@@ -0,0 +1,12 @@
+"""Tanvo: AI images, video and songs from Python. https://tanvo.ai"""
+
+from ._client import DEFAULT_BASE_URL, Client, __version__
+from ._errors import AuthError, InvalidRequest, QuotaError, ServiceError, TanvoError, WebhookVerificationError
+from ._types import Account, App, AppInput, Generation, Look, Model, Output
+from ._webhook import verify_webhook
+
+__all__ = [
+    "Client", "DEFAULT_BASE_URL", "__version__", "verify_webhook",
+    "TanvoError", "InvalidRequest", "AuthError", "QuotaError", "ServiceError", "WebhookVerificationError",
+    "Account", "App", "AppInput", "Generation", "Look", "Model", "Output",
+]

tanvo-0.1.0/src/tanvo/_client.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import time
+import uuid
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from ._errors import ServiceError, TanvoError, error_for
+from ._types import Account, App, Generation, Model
+from ._webhook import verify_webhook
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://tanvo.ai"
+ImageInput = Union[str, os.PathLike, bytes]
+_MIME = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".mp4": "video/mp4", ".mov": "video/quicktime", ".mp3": "audio/mpeg", ".wav": "audio/wav", ".m4a": "audio/mp4"}
+
+
+class Client:
+    """Tanvo API client.
+
+    With no key (argument or TANVO_API_KEY) it runs on the anonymous free tier: the house image engine only,
+    watermarked, about one image per client. Create a key at https://tanvo.ai/settings/apikeys for everything else.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, anon_id: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 60.0):
+        self.api_key = api_key or os.environ.get("TANVO_API_KEY") or None
+        self.anon_id = None if self.api_key else (anon_id or f"py-{uuid.uuid4()}")
+        self.base_url = (base_url or os.environ.get("TANVO_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self._models: Optional[List[Model]] = None
+        self._apps: Optional[List[App]] = None
+
+    # ─── HTTP ──────────────────────────────────────────────────────────────
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None, *, retries: int = 0) -> Dict[str, Any]:
+        url = f"{self.base_url}/api/v1{path}"
+        headers = {"Content-Type": "application/json", "Accept": "application/json", "User-Agent": f"tanvo-python/{__version__}"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        else:
+            headers["x-anon-id"] = self.anon_id or ""
+        data = json.dumps(body).encode() if body is not None else None
+        delays = [1, 3]
+        rate_limited_once = False
+        attempt = 0
+        while True:
+            try:
+                req = urllib.request.Request(url, data=data, method=method, headers=headers)
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    raw = res.read()
+                    return json.loads(raw) if raw else {}
+            except urllib.error.HTTPError as e:
+                err = self._error(e)
+            except (urllib.error.URLError, TimeoutError, ConnectionError, OSError) as e:
+                err = ServiceError("network", f"Could not reach {self.base_url}: {getattr(e, 'reason', e)}", 0)
+            if err.code == "rate_limited" and not rate_limited_once:
+                rate_limited_once = True
+                time.sleep(min(err.retry_after or 5, 60))
+                continue
+            if isinstance(err, ServiceError) and attempt < retries:
+                time.sleep(delays[min(attempt, len(delays) - 1)])
+                attempt += 1
+                continue
+            raise err
+
+    def _error(self, e: urllib.error.HTTPError) -> TanvoError:
+        try:
+            payload = json.loads(e.read() or b"{}")
+        except ValueError:
+            payload = {}
+        retry = e.headers.get("Retry-After") if e.headers else None
+        return error_for(payload.get("error") or f"http_{e.code}", payload.get("message") or f"HTTP {e.code}", e.code, payload.get("issues"), float(retry) if retry and retry.isdigit() else None, has_key=bool(self.api_key))
+
+    # ─── Catalogue and account ─────────────────────────────────────────────
+
+    def models(self, kind: Optional[str] = None) -> List[Model]:
+        """Every model with its options, defaults and credit cost at defaults. Cached on the client."""
+        if self._models is None:
+            self._models = [Model.from_dict(m) for m in self._request("GET", "/models", retries=2)["models"]]
+        return [m for m in self._models if kind is None or m.kind == kind]
+
+    def model(self, model_id: str) -> Model:
+        for m in self.models():
+            if m.id == model_id:
+                return m
+        raise KeyError(f"Unknown model {model_id!r}. See client.models().")
+
+    def apps(self, kind: Optional[str] = None) -> List[App]:
+        """Ready-made apps (pet portraits, figurines, trend videos, songs…) with their preset looks. Cached on the client."""
+        if self._apps is None:
+            self._apps = [App.from_dict(a) for a in self._request("GET", "/apps", retries=2)["apps"]]
+        return [a for a in self._apps if kind is None or a.kind == kind]
+
+    def app(self, slug: str) -> App:
+        for a in self.apps():
+            if a.slug == slug:
+                return a
+        raise KeyError(f"Unknown app {slug!r}. See client.apps().")
+
+    def me(self) -> Account:
+        d = self._request("GET", "/me", retries=2)
+        return Account(tier=d.get("tier", ""), credits=d.get("credits", 0), watermarked=bool(d.get("watermarked")), concurrency=d.get("concurrency", 1), email=d.get("email"))
+
+    # ─── Generation ────────────────────────────────────────────────────────
+
+    def _options(self, model_id: str, given: Dict[str, Any]) -> Dict[str, Any]:
+        """The model's defaults, overridden by whatever the caller set."""
+        try:
+            base = dict(self.model(model_id).defaults)
+        except KeyError:
+            base = {}
+        base.update({k: v for k, v in given.items() if v is not None})
+        return base
+
+    def _submit(self, body: Dict[str, Any], wait: bool, timeout: float, wait_for_slot: bool) -> Generation:
+        body = {k: v for k, v in body.items() if v not in (None, [], "")}
+        body.setdefault("requestKey", str(uuid.uuid4()))  # makes the retries below safe: a repeat returns the first run
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                g = Generation.from_dict(self._request("POST", "/generations", body, retries=2)["generation"])
+                break
+            except TanvoError as e:
+                if e.code == "busy" and wait_for_slot and time.monotonic() + 5 < deadline:
+                    time.sleep(5)
+                    continue
+                raise
+        if wait:
+            return self.wait(g.id, timeout=max(1.0, deadline - time.monotonic()), every=6 if g.kind == "video" else 4)
+        return g
+
+    def generate_image(
+        self, prompt: str, *, model: str = "studio-image-v1", aspect: Optional[str] = None, resolution: Optional[str] = None, format: Optional[str] = None,
+        images: Sequence[ImageInput] = (), negative_prompt: Optional[str] = None, wait: bool = True, timeout: float = 180, request_key: Optional[str] = None,
+        webhook_url: Optional[str] = None, wait_for_slot: bool = False,
+    ) -> Generation:
+        """Text to image, or an edit / combination when `images` are given (https URLs, local paths or bytes)."""
+        return self._submit({
+            "kind": "image", "model": model, "prompt": prompt, "negativePrompt": negative_prompt,
+            "options": self._options(model, {"aspect": aspect, "resolution": resolution, "format": format}),
+            "imageUrls": [self._ref(i) for i in images], "requestKey": request_key, "webhookUrl": webhook_url,
+        }, wait, timeout, wait_for_slot)
+
+    def generate_video(
+        self, prompt: str, *, model: str = "studio-video-v1", aspect: Optional[str] = None, resolution: Optional[str] = None, duration: Optional[int] = None,
+        audio: Optional[bool] = None, image: Optional[ImageInput] = None, end_image: Optional[ImageInput] = None, negative_prompt: Optional[str] = None,
+        wait: bool = False, timeout: float = 600, request_key: Optional[str] = None, webhook_url: Optional[str] = None, wait_for_slot: bool = False,
+    ) -> Generation:
+        """Text to video, or image to video from `image` (optionally ending on `end_image`). Returns at once unless wait=True."""
+        return self._submit({
+            "kind": "video", "model": model, "prompt": prompt, "negativePrompt": negative_prompt,
+            "options": self._options(model, {"aspect": aspect, "resolution": resolution, "duration": duration, "audio": audio}),
+            "imageUrls": [self._ref(image)] if image is not None else [], "endImageUrl": self._ref(end_image) if end_image is not None else None,
+            "requestKey": request_key, "webhookUrl": webhook_url,
+        }, wait, timeout, wait_for_slot)
+
+    def generate_music(
+        self, prompt: str, *, mode: str = "Describe", style: Optional[str] = None, title: Optional[str] = None, vocal: Optional[str] = None,
+        model: str = "suno-v6", wait: bool = True, timeout: float = 300, request_key: Optional[str] = None, webhook_url: Optional[str] = None,
+        wait_for_slot: bool = False,
+    ) -> Generation:
+        """Two takes of a song. mode: "Describe" (prompt describes the song), "Lyrics" (prompt is your lyrics) or "Instrumental"."""
+        return self._submit({
+            "kind": "music", "model": model, "prompt": prompt,
+            "options": {k: v for k, v in {"tier": mode, "resolution": "song", "style": style, "title": title, "vocal": vocal}.items() if v is not None},
+            "requestKey": request_key, "webhookUrl": webhook_url,
+        }, wait, timeout, wait_for_slot)
+
+    def generate_from_app(
+        self, app: str, *, look: Optional[str] = None, photos: Sequence[ImageInput] = (), details: Optional[str] = None, wait: Optional[bool] = None,
+        timeout: Optional[float] = None, request_key: Optional[str] = None, webhook_url: Optional[str] = None, wait_for_slot: bool = False,
+    ) -> Generation:
+        """Runs one of an app's preset looks on your photos (in the order of app.inputs), e.g.
+        client.generate_from_app("ai-pet-portrait-generator", look="royal", photos=["rex.jpg"])."""
+        a = self.app(app)
+        l = a.look(look)
+        needed = sum(1 for i in a.inputs if i.min > 0)
+        if len(photos) < needed:
+            raise ValueError(f"{a.name} needs {needed} photo(s): {', '.join(i.label for i in a.inputs if i.min > 0)}.")
+        prompt = f"{l.prompt}\n\nThis one is for: {details.strip()}." if details else l.prompt
+        is_video = a.kind == "video"
+        return self._submit({
+            "kind": a.kind, "model": l.model, "prompt": prompt, "options": self._options(l.model, dict(l.options)),
+            "imageUrls": [self._ref(p) for p in photos] if a.kind != "music" else [], "requestKey": request_key, "webhookUrl": webhook_url,
+        }, (not is_video) if wait is None else wait, timeout or (600 if is_video else 300 if a.kind == "music" else 180), wait_for_slot)
+
+    # ─── Runs ──────────────────────────────────────────────────────────────
+
+    def get(self, generation_id: str) -> Generation:
+        return Generation.from_dict(self._request("GET", f"/generations/{urllib.parse.quote(generation_id)}", retries=2)["generation"])
+
+    def wait(self, generation_id: str, timeout: float = 600, every: float = 4) -> Generation:
+        """Polls until the run finishes. On timeout returns the last state seen (still running) instead of raising."""
+        deadline = time.monotonic() + timeout
+        time.sleep(min(2, timeout))
+        last: Optional[Generation] = None
+        while True:
+            try:
+                last = self.get(generation_id)
+                if last.done:
+                    return last
+            except ServiceError:
+                pass  # one failed read is not a failed run
+            if time.monotonic() + every > deadline:
+                return last if last is not None else self.get(generation_id)
+            time.sleep(every)
+
+    def list(self, limit: int = 20, before: Optional[int] = None) -> Tuple[List[Generation], Optional[int]]:
+        q = urllib.parse.urlencode({k: v for k, v in {"limit": limit, "before": before}.items() if v is not None})
+        d = self._request("GET", f"/generations?{q}", retries=2)
+        return [Generation.from_dict(g) for g in d.get("generations", [])], d.get("next_before")
+
+    # ─── Files ─────────────────────────────────────────────────────────────
+
+    def upload(self, file: Union[str, os.PathLike, bytes], mime: Optional[str] = None) -> str:
+        """Uploads a local file (path or bytes) and returns a URL usable in images= / image=."""
+        if isinstance(file, bytes):
+            data = file
+            if not mime:
+                raise ValueError("Pass mime= when uploading bytes, e.g. mime='image/png'.")
+        else:
+            p = Path(file).expanduser()
+            data = p.read_bytes()
+            mime = mime or _MIME.get(p.suffix.lower()) or mimetypes.guess_type(p.name)[0]
+            if not mime:
+                raise ValueError(f"Cannot tell the file type of {p.name}; pass mime=.")
+        slot = self._request("POST", "/uploads", {"mime": mime, "bytes": len(data)})
+        req = urllib.request.Request(slot["upload_url"], data=data, method="PUT", headers={"Content-Type": mime})
+        try:
+            with urllib.request.urlopen(req, timeout=max(self.timeout, 120)):
+                pass
+        except urllib.error.HTTPError as e:
+            raise ServiceError("upload_failed", f"Upload failed with HTTP {e.code}.", e.code) from None
+        return slot["url"]
+
+    def _ref(self, ref: ImageInput) -> str:
+        if isinstance(ref, str) and ref.startswith("https://"):
+            return ref
+        if isinstance(ref, str) and ref.startswith("http://") and not self.base_url.startswith("http://"):
+            raise ValueError(f"Only https URLs can be fetched by the service: {ref}")
+        if isinstance(ref, bytes):
+            return self.upload(ref, mime="image/png" if ref[:8] == b"\x89PNG\r\n\x1a\n" else "image/jpeg" if ref[:3] == b"\xff\xd8\xff" else "image/webp")
+        return self.upload(ref)
+
+    def download(self, generation: Union[Generation, str], path: Union[str, os.PathLike] = ".", index: int = 0) -> str:
+        """Saves one output to `path` (a folder or a file name) and returns the file path."""
+        g = self.get(generation) if isinstance(generation, str) else generation
+        if not g.outputs:
+            raise ValueError(f"Generation {g.id} has no outputs (status {g.status}).")
+        url = g.outputs[index].url
+        target = Path(path).expanduser()
+        if target.is_dir() or str(path).endswith(("/", os.sep)):
+            target.mkdir(parents=True, exist_ok=True)
+            target = target / f"tanvo-{g.id}-{index}{Path(urllib.parse.urlparse(url).path).suffix or '.bin'}"
+        with urllib.request.urlopen(urllib.request.Request(url, headers={"User-Agent": f"tanvo-python/{__version__}"}), timeout=max(self.timeout, 120)) as res:
+            target.write_bytes(res.read())
+        return str(target)
+
+    verify_webhook = staticmethod(verify_webhook)

tanvo-0.1.0/src/tanvo/_errors.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+KEYS_URL = "https://tanvo.ai/settings/apikeys"
+
+
+class TanvoError(Exception):
+    """Base class. `code` is the API's stable error string, `status` the HTTP status (0 for network errors)."""
+
+    def __init__(self, code: str, message: str, status: int = 0, issues: Optional[List[str]] = None, retry_after: Optional[float] = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.issues = issues or []
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        extra = f" ({'; '.join(self.issues)})" if self.issues else ""
+        return f"{self.code}: {self.message}{extra}"
+
+
+class InvalidRequest(TanvoError):
+    """Bad parameters, a prompt the moderator refused, a file too large, or a record that does not exist. Do not retry."""
+
+
+class AuthError(TanvoError):
+    """No identity, or an invalid / revoked API key."""
+
+
+class QuotaError(TanvoError):
+    """Out of credits, the free tier does not cover this, or a limit was hit. `busy` and `rate_limited` clear by waiting."""
+
+
+class ServiceError(TanvoError):
+    """The service or an upstream model failed. Safe to retry with the same request_key."""
+
+
+class WebhookVerificationError(TanvoError):
+    """A webhook's signature or timestamp did not check out."""
+
+
+_KINDS = {
+    InvalidRequest: {"invalid", "rejected", "too_large", "not_found"},
+    AuthError: {"unauthorized", "invalid_api_key", "unknown_anon_id"},
+    QuotaError: {"credits", "allowance", "needs_api_key", "anon_ip_daily", "trial_closed", "rate_limited", "limit", "busy"},
+}
+NEEDS_KEY = {"needs_api_key", "allowance", "anon_ip_daily", "trial_closed"}
+
+
+def error_for(code: str, message: str, status: int, issues: Optional[List[str]] = None, retry_after: Optional[float] = None, has_key: bool = True) -> TanvoError:
+    cls = next((c for c, codes in _KINDS.items() if code in codes), ServiceError)
+    if code in NEEDS_KEY and not has_key:
+        message = f"{message} Get a key at {KEYS_URL} (then pass api_key= or set TANVO_API_KEY)."
+    return cls(code, message, status, issues, retry_after)

tanvo-0.1.0/src/tanvo/_types.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+TERMINAL = {"SUCCEEDED", "FAILED", "CANCELED"}
+
+
+@dataclass(frozen=True)
+class Output:
+    url: str
+    mime: str
+    # Songs only.
+    cover: Optional[str] = None
+    title: Optional[str] = None
+    lyrics: Optional[str] = None
+    seconds: Optional[float] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Output":
+        return cls(url=d["url"], mime=d.get("mime", ""), cover=d.get("cover"), title=d.get("title"), lyrics=d.get("lyrics"), seconds=d.get("seconds"))
+
+
+@dataclass(frozen=True)
+class Generation:
+    id: str
+    kind: str
+    model: str
+    prompt: str
+    options: Dict[str, Any]
+    cost: int
+    status: str
+    error: Optional[str]
+    created_at: int
+    outputs: List[Output] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Generation":
+        return cls(
+            id=d["id"],
+            kind=d.get("kind", ""),
+            model=d.get("model", ""),
+            prompt=d.get("prompt", ""),
+            options=d.get("options") or {},
+            cost=d.get("cost", 0),
+            status=d.get("status", ""),
+            error=d.get("error"),
+            created_at=d.get("createdAt", 0),
+            outputs=[Output.from_dict(o) for o in d.get("outputs") or []],
+        )
+
+    @property
+    def done(self) -> bool:
+        return self.status in TERMINAL
+
+    @property
+    def succeeded(self) -> bool:
+        return self.status == "SUCCEEDED"
+
+    @property
+    def url(self) -> Optional[str]:
+        """The first output's URL, or None while running or after a failure."""
+        return self.outputs[0].url if self.outputs else None
+
+
+@dataclass(frozen=True)
+class Model:
+    id: str
+    kind: str
+    name: str
+    free_tier: bool
+    inputs: List[str]
+    options: Dict[str, Any]
+    defaults: Dict[str, Any]
+    credits_at_defaults: int
+    prompt_max_chars: int
+    raw: Dict[str, Any] = field(repr=False, default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Model":
+        return cls(
+            id=d["id"], kind=d.get("kind", ""), name=d.get("name", ""), free_tier=bool(d.get("free_tier")), inputs=d.get("inputs") or [],
+            options=d.get("options") or {}, defaults=d.get("defaults") or {}, credits_at_defaults=d.get("credits_at_defaults", 0),
+            prompt_max_chars=d.get("prompt_max_chars", 0), raw=d,
+        )
+
+
+@dataclass(frozen=True)
+class Look:
+    id: str
+    name: str
+    prompt: str
+    model: str
+    options: Dict[str, Any]
+    example: Optional[str]
+    url: str
+
+
+@dataclass(frozen=True)
+class AppInput:
+    id: str
+    label: str
+    hint: str
+    min: int
+    max: int
+
+
+@dataclass(frozen=True)
+class App:
+    slug: str
+    kind: str
+    name: str
+    description: str
+    category: Optional[str]
+    model: str
+    url: str
+    inputs: List[AppInput]
+    looks: List[Look]
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "App":
+        return cls(
+            slug=d["slug"], kind=d.get("kind", ""), name=d.get("name", ""), description=d.get("description", ""), category=d.get("category"),
+            model=d.get("model", ""), url=d.get("url", ""),
+            inputs=[AppInput(id=i["id"], label=i.get("label", ""), hint=i.get("hint", ""), min=i.get("min", 1), max=i.get("max", 1)) for i in d.get("inputs") or []],
+            looks=[
+                Look(id=l["id"], name=l.get("name", ""), prompt=l.get("prompt", ""), model=l.get("model", ""), options=l.get("options") or {},
+                     example=(l.get("example") or {}).get("video") or (l.get("example") or {}).get("url"), url=l.get("url", ""))
+                for l in d.get("looks") or []
+            ],
+        )
+
+    def look(self, look_id: Optional[str] = None) -> Look:
+        if look_id is None:
+            return self.looks[0]
+        for l in self.looks:
+            if l.id == look_id:
+                return l
+        raise KeyError(f"{self.slug} has no look {look_id!r}; looks: {', '.join(l.id for l in self.looks)}")
+
+
+@dataclass(frozen=True)
+class Account:
+    tier: str
+    credits: int
+    watermarked: bool
+    concurrency: int
+    email: Optional[str] = None

tanvo-0.1.0/src/tanvo/_webhook.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import time
+from typing import Mapping, Optional, Union
+
+from ._errors import WebhookVerificationError
+from ._types import Generation
+
+
+def _header(headers: Mapping[str, str], name: str) -> Optional[str]:
+    for k, v in headers.items():
+        if k.lower() == name:
+            return v
+    return None
+
+
+def verify_webhook(secret: str, headers: Mapping[str, str], body: Union[bytes, str], tolerance: int = 300) -> Generation:
+    """Checks a completion webhook (Standard Webhooks) and returns the Generation it carries.
+
+    Pass the raw request body exactly as received, not re-serialised JSON. Raises WebhookVerificationError when the
+    signature does not match or the timestamp is more than `tolerance` seconds away. The same `webhook-id` can arrive
+    more than once (retries, manual resends): de-duplicate on it.
+    """
+    raw = body.encode() if isinstance(body, str) else body
+    msg_id, ts, sig = _header(headers, "webhook-id"), _header(headers, "webhook-timestamp"), _header(headers, "webhook-signature")
+    if not msg_id or not ts or not sig:
+        raise WebhookVerificationError("missing_headers", "webhook-id, webhook-timestamp and webhook-signature are required.")
+    try:
+        sent = int(ts)
+    except ValueError:
+        raise WebhookVerificationError("bad_timestamp", "webhook-timestamp is not a number.") from None
+    if abs(time.time() - sent) > tolerance:
+        raise WebhookVerificationError("stale", f"The webhook timestamp is more than {tolerance} s from now.")
+    key = base64.b64decode(secret[len("whsec_"):] if secret.startswith("whsec_") else secret)
+    expected = base64.b64encode(hmac.new(key, f"{msg_id}.{ts}.".encode() + raw, hashlib.sha256).digest()).decode()
+    candidates = [part.split(",", 1)[1] for part in sig.split() if part.startswith("v1,")]
+    if not any(hmac.compare_digest(expected, c) for c in candidates):
+        raise WebhookVerificationError("bad_signature", "The webhook signature does not match. Check the secret under Settings → Webhooks.")
+    return Generation.from_dict(json.loads(raw))

tanvo-0.1.0/tests/test_client.py

@@ -0,0 +1,328 @@
+"""Offline tests against a fake API server (standard library only): python -m unittest discover -s tests"""
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import sys
+import tempfile
+import threading
+import time
+import unittest
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from unittest import mock
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+import tanvo  # noqa: E402
+from tanvo import AuthError, Client, InvalidRequest, QuotaError, ServiceError, WebhookVerificationError, verify_webhook  # noqa: E402
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"0" * 32
+MODELS = [
+    {"id": "studio-image-v1", "kind": "image", "name": "Tanvo Image v1", "free_tier": True, "inputs": ["text", "image"], "options": {}, "defaults": {"aspect": "1:1", "resolution": "1K", "format": "PNG"}, "credits_at_defaults": 5, "prompt_max_chars": 2000},
+    {"id": "seedream-4", "kind": "image", "name": "Seedream 4.0", "free_tier": False, "inputs": ["text", "image"], "options": {}, "defaults": {"aspect": "1:1", "resolution": "2K"}, "credits_at_defaults": 10, "prompt_max_chars": 5000},
+    {"id": "studio-video-v1", "kind": "video", "name": "Tanvo Video v1", "free_tier": True, "inputs": ["text", "image"], "options": {}, "defaults": {"aspect": "16:9", "resolution": "480p", "duration": 5}, "credits_at_defaults": 20, "prompt_max_chars": 2000},
+]
+APPS = [{
+    "slug": "ai-pet-portrait-generator", "kind": "image", "name": "Pet Portrait Generator", "description": "A painted portrait.", "category": "Pets", "model": "seedream-4",
+    "url": "https://tanvo.ai/image/ai-pet-portrait-generator", "inputs": [{"id": "in1", "label": "Pet photo", "hint": "", "accept": "image/*", "min": 1, "max": 1}],
+    "looks": [{"id": "renaissance", "name": "Renaissance oil", "prompt": "Paint the pet as a Renaissance oil portrait.", "model": "seedream-4", "options": {}, "example": {"url": "https://x/e.webp", "kind": "image"}, "url": "https://tanvo.ai/image/ai-pet-portrait-generator?look=renaissance"},
+              {"id": "royal", "name": "Royal monarch", "prompt": "Paint the pet as a monarch.", "model": "seedream-4", "options": {"aspect": "3:4"}, "example": None, "url": "https://tanvo.ai/image/ai-pet-portrait-generator?look=royal"}],
+}]
+
+
+class Fake:
+    """State shared with the handler: what was asked, and which failures to inject next."""
+
+    def __init__(self):
+        self.reset()
+
+    def reset(self):
+        self.requests = []
+        self.runs = {}
+        self.by_key = {}
+        self.fail_next = []  # (status, error, extra_headers)
+        self.polls_until_done = 1
+        self.uploaded = {}
+
+
+FAKE = Fake()
+
+
+class Handler(BaseHTTPRequestHandler):
+    def log_message(self, *a):
+        pass
+
+    def _send(self, status, payload, headers=None):
+        body = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _body(self):
+        n = int(self.headers.get("Content-Length") or 0)
+        return self.rfile.read(n) if n else b""
+
+    def _handle(self, method):
+        raw = self._body()
+        FAKE.requests.append((method, self.path, dict(self.headers), raw))
+        if self.path.startswith("/put/"):
+            FAKE.uploaded[self.path] = (self.headers.get("Content-Type"), raw)
+            self.send_response(200)
+            self.send_header("Content-Length", "0")
+            self.end_headers()
+            return
+        if self.path.startswith("/files/"):
+            self.send_response(200)
+            self.send_header("Content-Length", str(len(PNG)))
+            self.end_headers()
+            self.wfile.write(PNG)
+            return
+        if FAKE.fail_next:
+            status, error, headers = FAKE.fail_next.pop(0)
+            return self._send(status, {"error": error, "message": f"injected {error}"}, headers)
+        auth = self.headers.get("Authorization")
+        if auth and auth != "Bearer sk_good":
+            return self._send(401, {"error": "invalid_api_key", "message": "That API key is not valid."})
+        path = self.path.split("?")[0]
+        if method == "GET" and path == "/api/v1/models":
+            return self._send(200, {"models": MODELS})
+        if method == "GET" and path == "/api/v1/apps":
+            return self._send(200, {"apps": APPS})
+        if method == "GET" and path == "/api/v1/me":
+            return self._send(200, {"tier": "paid" if auth else "anonymous", "credits": 900 if auth else 5, "watermarked": not auth, "concurrency": 3 if auth else 1})
+        if method == "POST" and path == "/api/v1/generations":
+            b = json.loads(raw)
+            if not auth and b["model"] != "studio-image-v1":
+                return self._send(403, {"error": "needs_api_key", "message": "The free tier covers the house image engine only."})
+            if b["options"].get("resolution") == "8K":
+                return self._send(400, {"error": "invalid", "message": "That model or setting is not available.", "issues": ["options.resolution: 8K"]})
+            key = b.get("requestKey")
+            if key in FAKE.by_key:
+                return self._send(202, {"generation": FAKE.runs[FAKE.by_key[key]]["g"]})
+            gid = f"gen{len(FAKE.runs) + 1}"
+            g = {"id": gid, "kind": b["kind"], "model": b["model"], "prompt": b["prompt"], "options": b["options"], "cost": 5, "status": "PROCESSING", "error": None, "createdAt": 1790000000000 + len(FAKE.runs), "outputs": []}
+            FAKE.runs[gid] = {"g": g, "polls": 0, "body": b}
+            FAKE.by_key[key] = gid
+            return self._send(202, {"generation": g})
+        if method == "GET" and path.startswith("/api/v1/generations/"):
+            r = FAKE.runs.get(path.rsplit("/", 1)[1])
+            if not r:
+                return self._send(404, {"error": "not_found", "message": "No such generation."})
+            r["polls"] += 1
+            if r["polls"] >= FAKE.polls_until_done:
+                host = f"http://127.0.0.1:{self.server.server_address[1]}"
+                r["g"] = {**r["g"], "status": "SUCCEEDED", "outputs": [{"url": f"{host}/files/{r['g']['id']}/0.png", "mime": "image/png"}]}
+            return self._send(200, {"generation": r["g"]})
+        if method == "GET" and path == "/api/v1/generations":
+            gs = sorted((r["g"] for r in FAKE.runs.values()), key=lambda g: -g["createdAt"])[:2]
+            return self._send(200, {"generations": gs, "next_before": gs[-1]["createdAt"] if gs else None})
+        if method == "POST" and path == "/api/v1/uploads":
+            b = json.loads(raw)
+            host = f"http://127.0.0.1:{self.server.server_address[1]}"
+            return self._send(200, {"upload_url": f"{host}/put/{len(FAKE.uploaded)}", "url": f"https://media.tanvo.ai/uploads/u/{len(FAKE.uploaded)}.png", "expires_in": 300, "_mime": b["mime"]})
+        self._send(404, {"error": "not_found", "message": self.path})
+
+    def do_GET(self):
+        self._handle("GET")
+
+    def do_POST(self):
+        self._handle("POST")
+
+    def do_PUT(self):
+        self._handle("PUT")
+
+
+class ClientTest(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=cls.server.serve_forever, daemon=True).start()
+        cls.base = f"http://127.0.0.1:{cls.server.server_address[1]}"
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.server.shutdown()
+
+    def setUp(self):
+        FAKE.reset()
+        # Polling and retry delays are real sleeps; make them instant.
+        self.sleep = mock.patch("tanvo._client.time.sleep", lambda s: None)
+        self.sleep.start()
+        os.environ.pop("TANVO_API_KEY", None)
+
+    def tearDown(self):
+        self.sleep.stop()
+
+    def client(self, key=None):
+        return Client(key, base_url=self.base)
+
+    def test_anonymous_free_image(self):
+        c = self.client()
+        self.assertEqual(c.me().tier, "anonymous")
+        g = c.generate_image("a cat")
+        self.assertTrue(g.succeeded)
+        self.assertEqual(g.cost, 5)
+        post = next(r for r in FAKE.requests if r[0] == "POST" and r[1] == "/api/v1/generations")
+        sent = json.loads(post[3])
+        self.assertEqual(sent["options"], {"aspect": "1:1", "resolution": "1K", "format": "PNG"})  # model defaults filled in
+        self.assertTrue(sent["requestKey"])
+        headers = post[2]
+        self.assertTrue(headers["X-Anon-Id"].startswith("py-"))
+        self.assertTrue(headers["User-Agent"].startswith("tanvo-python/"))
+
+    def test_free_tier_refuses_other_models_with_a_hint(self):
+        with self.assertRaises(QuotaError) as e:
+            self.client().generate_video("a fox")
+        self.assertEqual(e.exception.code, "needs_api_key")
+        self.assertIn("settings/apikeys", str(e.exception))
+
+    def test_key_options_override_defaults(self):
+        c = self.client("sk_good")
+        g = c.generate_image("a cat", model="seedream-4", aspect="16:9")
+        self.assertTrue(g.succeeded)
+        self.assertEqual(json.loads(FAKE.requests[-2][3])["options"], {"aspect": "16:9", "resolution": "2K"})
+        self.assertEqual(FAKE.requests[-1][2]["Authorization"], "Bearer sk_good")
+
+    def test_request_key_is_idempotent(self):
+        c = self.client("sk_good")
+        a = c.generate_image("a cat", request_key="job-1", wait=False)
+        b = c.generate_image("a cat", request_key="job-1", wait=False)
+        self.assertEqual(a.id, b.id)
+        self.assertEqual(len(FAKE.runs), 1)
+
+    def test_video_returns_at_once_then_wait(self):
+        c = self.client("sk_good")
+        FAKE.polls_until_done = 3
+        g = c.generate_video("a fox in snow")
+        self.assertEqual(g.status, "PROCESSING")
+        self.assertTrue(c.wait(g.id, timeout=60).succeeded)
+
+    def test_wait_timeout_returns_last_state(self):
+        c = self.client("sk_good")
+        FAKE.polls_until_done = 10_000
+        g = c.generate_video("a fox")
+        clock = iter(range(0, 10_000, 30))
+        with mock.patch("tanvo._client.time.monotonic", lambda: next(clock)):
+            last = c.wait(g.id, timeout=60)
+        self.assertEqual(last.status, "PROCESSING")
+
+    def test_errors_map_to_classes(self):
+        with self.assertRaises(AuthError) as e:
+            self.client("sk_bad").me()
+        self.assertEqual(e.exception.code, "invalid_api_key")
+        with self.assertRaises(InvalidRequest) as e:
+            self.client("sk_good").generate_image("x", resolution="8K")
+        self.assertEqual(e.exception.issues, ["options.resolution: 8K"])
+
+    def test_service_errors_retry_with_the_same_request_key(self):
+        c = self.client("sk_good")
+        c.models()
+        FAKE.fail_next = [(502, "provider", None), (500, "server_error", None)]
+        g = c.generate_image("a cat", wait=False)
+        posts = [json.loads(r[3])["requestKey"] for r in FAKE.requests if r[0] == "POST" and r[1] == "/api/v1/generations"]
+        self.assertEqual(len(posts), 3)
+        self.assertEqual(len(set(posts)), 1)
+        self.assertEqual(g.status, "PROCESSING")
+
+    def test_service_error_gives_up_after_two_retries(self):
+        c = self.client("sk_good")
+        c.models()
+        FAKE.fail_next = [(502, "provider", None)] * 3
+        with self.assertRaises(ServiceError):
+            c.generate_image("a cat", wait=False)
+
+    def test_rate_limit_waits_once(self):
+        c = self.client("sk_good")
+        c.models()
+        FAKE.fail_next = [(429, "rate_limited", {"Retry-After": "2"})]
+        self.assertEqual(c.me().tier, "paid")
+
+    def test_busy_waits_for_a_slot_when_asked(self):
+        c = self.client("sk_good")
+        c.models()
+        FAKE.fail_next = [(409, "busy", None)]
+        with self.assertRaises(QuotaError):
+            c.generate_image("a cat", wait=False)
+        FAKE.fail_next = [(409, "busy", None)]
+        self.assertEqual(c.generate_image("a cat", wait=False, wait_for_slot=True).status, "PROCESSING")
+
+    def test_local_images_are_uploaded(self):
+        c = self.client("sk_good")
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as f:
+            f.write(PNG)
+        try:
+            g = c.generate_image("make it winter", model="seedream-4", images=[f.name, "https://example.com/a.jpg", PNG], wait=False)
+        finally:
+            os.unlink(f.name)
+        sent = json.loads(next(r[3] for r in FAKE.requests if r[1] == "/api/v1/generations"))
+        self.assertEqual(sent["imageUrls"][1], "https://example.com/a.jpg")
+        self.assertTrue(all(u.startswith("https://media.tanvo.ai/uploads/") for u in (sent["imageUrls"][0], sent["imageUrls"][2])))
+        self.assertEqual([m for m, _ in FAKE.uploaded.values()], ["image/png", "image/png"])
+        self.assertEqual(g.status, "PROCESSING")
+
+    def test_generate_from_app_uses_the_look(self):
+        c = self.client("sk_good")
+        with self.assertRaises(ValueError):
+            c.generate_from_app("ai-pet-portrait-generator", look="royal")
+        g = c.generate_from_app("ai-pet-portrait-generator", look="royal", photos=["https://example.com/rex.jpg"], details="Rex, a very good boy")
+        self.assertTrue(g.succeeded)
+        sent = json.loads(next(r[3] for r in FAKE.requests if r[1] == "/api/v1/generations"))
+        self.assertEqual(sent["model"], "seedream-4")
+        self.assertEqual(sent["options"], {"aspect": "3:4", "resolution": "2K"})
+        self.assertTrue(sent["prompt"].startswith("Paint the pet as a monarch.") and sent["prompt"].endswith("This one is for: Rex, a very good boy."))
+        with self.assertRaises(KeyError):
+            c.app("ai-pet-portrait-generator").look("nope")
+
+    def test_list_and_download(self):
+        c = self.client("sk_good")
+        for i in range(3):
+            c.generate_image(f"cat {i}", wait=False)
+        items, nxt = c.list(limit=2)
+        self.assertEqual(len(items), 2)
+        self.assertEqual(nxt, items[-1].created_at)
+        g = c.wait(items[0].id)
+        with tempfile.TemporaryDirectory() as d:
+            path = c.download(g, d)
+            with open(path, "rb") as f:
+                self.assertEqual(f.read(), PNG)
+
+    def test_network_error_is_a_service_error(self):
+        with self.assertRaises(ServiceError) as e:
+            Client("sk_good", base_url="http://127.0.0.1:9").me()
+        self.assertEqual(e.exception.code, "network")
+
+
+class WebhookTest(unittest.TestCase):
+    secret = "whsec_" + base64.b64encode(b"k" * 24).decode()
+    body = json.dumps({"id": "gen1", "kind": "image", "model": "studio-image-v1", "prompt": "p", "options": {}, "cost": 5, "status": "SUCCEEDED", "error": None, "createdAt": 1, "outputs": [{"url": "https://x/0.png", "mime": "image/png"}]})
+
+    def sign(self, ts, body=None):
+        mac = hmac.new(b"k" * 24, f"msg_1.{ts}.{body or self.body}".encode(), hashlib.sha256).digest()
+        return {"webhook-id": "msg_1", "webhook-timestamp": str(ts), "webhook-signature": f"v1,{base64.b64encode(mac).decode()}"}
+
+    def test_valid(self):
+        g = verify_webhook(self.secret, self.sign(int(time.time())), self.body.encode())
+        self.assertEqual((g.id, g.url), ("gen1", "https://x/0.png"))
+        self.assertEqual(Client.verify_webhook(self.secret, {k.title(): v for k, v in self.sign(int(time.time())).items()}, self.body).id, "gen1")
+
+    def test_tampered_or_stale(self):
+        h = self.sign(int(time.time()))
+        with self.assertRaises(WebhookVerificationError):
+            verify_webhook(self.secret, h, self.body.replace("gen1", "gen2"))
+        with self.assertRaises(WebhookVerificationError):
+            verify_webhook(self.secret, self.sign(int(time.time()) - 600), self.body)
+        with self.assertRaises(WebhookVerificationError):
+            verify_webhook(self.secret, {}, self.body)
+
+    def test_version(self):
+        self.assertRegex(tanvo.__version__, r"^\d+\.\d+\.\d+$")
+
+
+if __name__ == "__main__":
+    unittest.main()