clipwise 0.1.0b1__tar.gz

clipwise-0.1.0b1/.gitignore

@@ -0,0 +1,94 @@
+# Ignore compiled Python files
+__pycache__/
+*.pyc
+
+# Ignore the virtual environment
+venv/
+.venv/
+venv-py310/
+clipwise_env/
+lib/
+venv_py310
+
+# Ignore local development settings
+*.env
+
+# Ignore static files
+staticfiles/
+
+# Ignore media files
+media/
+
+# Ignore database file
+db.sqlite3
+
+# Ignore logs and other generated files
+*.log
+*.pot
+*.pyc
+*.swp
+*.swo
+
+# Ignore secret keys and sensitive information
+*.secret_key
+*.env
+
+# Ignore local database settings
+*.sqlite3
+
+# Ignore IDE specific files
+.vscode/
+.idea/
+
+# Ignore OS generated files
+.DS_Store
+Thumbs.db
+
+# Ignore node modules
+node_modules/
+package-lock.json
+cache/*
+local_scripts/*
+/dump.rdb
+API Collection.postman_collection.json
+example_request.txt
+jsconfig.json
+kling_cache.json
+postman_collection.json
+dump.rdb
+kling_cache.json
+jsconfig.json
+.firebaserc
+memory-bank/
+delete_linear_issues.js
+.clinerules
+local-tests
+mlartifacts
+mlruns/
+.ruff_cache/
+.pytest_cache/
+.parcel-cache/
+.claude/
+final_plan.md
+centrifugo_config.json
+centrifugo
+restart_dev.sh
+stop_dev.sh
+start_dev.sh
+uv.lock
+mlflow.pid
+
+# Local Codex worktree bootstrap
+.githooks/
+scripts/setup_worktree_from_main.sh
+
+.env.precommit
+.dspy_cache/
+*.un~
+.colima/
+.docker/
+.ipython/
+.python_history
+.ssh/
+.viminfo
+Library/

clipwise-0.1.0b1/CLI.md

@@ -0,0 +1,54 @@
+# Clipwise CLI
+
+Global environment:
+
+```bash
+export CLIPWISE_API_KEY="cw_live_..."
+export CLIPWISE_BASE_URL="https://app.clipwise.ai"
+```
+
+Commands:
+
+```bash
+clipwise auth set-key cw_live_...
+clipwise auth show
+clipwise auth clear
+
+clipwise formats list --kind all --platform all --json
+clipwise formats show ugc_video --json
+
+clipwise resources types --json
+clipwise resources list avatars --page 1 --limit 20 --json
+clipwise resources list poses --video-format ugc_product_background --json
+clipwise resources list background_music --json
+clipwise resources list overlays --type overlay --json
+clipwise resources upload product_images ./product.png --product-type skincare --json
+clipwise resources upload reference_ads ./ad.mp4 --type video --json
+clipwise resources upload background_music ./track.mp3 --json
+clipwise resources upload overlays ./overlay.webm --type underlay --json
+clipwise resources generate avatars --prompt "Female presenter in a studio" --video-format ugc_video --json
+clipwise resources generate background_images --prompt "Luxury bathroom counter" --video-format ugc_product_background --json
+
+clipwise uploads create ./input.mp4 --purpose video --json
+clipwise uploads list --page 1 --limit 20 --json
+
+clipwise products list --page 1 --limit 20 --json
+clipwise products create --name "Serum" --image-id UPLOAD_ID --product-type skincare --json
+
+clipwise voices list --json
+
+clipwise generate --format smart --prompt "..." --json
+clipwise generate --format video_to_text --video ./input.mp4 --json
+clipwise generate --format inventory_shoot --mode product_shoot --product-image ./product.png --reference-image POSE_ID --variations 4 --json
+clipwise status gen_... --json
+clipwise wait gen_... --timeout 1800 --poll-interval 5 --json
+clipwise cancel gen_... --json
+```
+
+Local file arguments are uploaded first when possible, then replaced with the
+uploaded resource id in the generation request.
+
+Standalone resource generation is available for `avatars` and
+`background_images`. Background music generation remains tied to an existing
+video job in the Clipwise workflow; use `generate` and let the backend auto-pick
+or create music when that format supports it.

clipwise-0.1.0b1/LICENSE

@@ -0,0 +1,2 @@
+MIT
+

clipwise-0.1.0b1/LLM_USAGE.md

@@ -0,0 +1,35 @@
+# LLM Usage Guide
+
+1. Run `clipwise formats list --json` before selecting a format unless the user
+   already provided an exact format slug or template name.
+2. Use `description`, `what_it_does`, `required_inputs`, `optional_inputs`,
+   and `resource_requirements` from the format response.
+3. For resource-backed inputs, list or upload the resource first:
+   `clipwise resources list RESOURCE_TYPE --page 1 --limit 20 --json` or
+   `clipwise resources upload RESOURCE_TYPE FILE --json`.
+4. For standalone generated assets, use
+   `clipwise resources generate avatars --prompt "..." --json` or
+   `clipwise resources generate background_images --prompt "..." --json`.
+5. Start video jobs with `clipwise generate ... --json`.
+6. Poll with `clipwise status JOB_ID --json` or `clipwise wait JOB_ID --json`.
+7. Do not call Clipwise frontend endpoints. This CLI uses only `/api/sdk/v1/*`.
+
+Important resource mappings:
+
+- `inventory_shoot --mode product_shoot` maps to `ugc_product_background`.
+- `inventory_shoot --mode model_shoot` maps to `ugc_model_shoot`.
+- `--reference-image` for inventory shoots maps to the backend `pose` field.
+- Inventory shoot references can be selected from
+  `clipwise resources list poses --video-format ugc_product_background --page 1 --limit 20`, passed
+  as a pose id, or uploaded from a local file with `--reference-image ./pose.png`.
+- Use `--page` and `--limit` for resource, upload, and product list commands;
+  SDK list responses include a `pagination` object when the backend can page.
+- Product images can be uploaded with `resources upload product_images FILE`.
+- Reference ad videos can be uploaded with `resources upload reference_ads FILE --type video`.
+- Background music files can be uploaded with
+  `resources upload background_music FILE`.
+- Overlay and underlay videos can be listed with `resources list overlays` and
+  uploaded with `resources upload overlays FILE --type overlay|underlay`.
+- Standalone resource generation currently supports `avatars` and
+  `background_images`; background music generation is workflow-scoped and should
+  be left to the selected video format.

clipwise-0.1.0b1/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: clipwise
+Version: 0.1.0b1
+Summary: Python SDK and CLI for Clipwise generation APIs
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.8
+Description-Content-Type: text/markdown
+
+# Clipwise Python SDK and CLI
+
+Install in development:
+
+```bash
+cd backend_clipwise/clipwise_cli
+pip install -e .
+```
+
+Configure:
+
+```bash
+export CLIPWISE_API_KEY="cw_live_..."
+export CLIPWISE_BASE_URL="https://app.clipwise.ai"
+```
+
+Python:
+
+```python
+from clipwise import Clipwise
+
+client = Clipwise()
+formats = client.formats.list(kind="all", platform="all")
+job = client.generations.create(format="smart", prompt="Create a founder launch video")
+result = client.generations.wait(job["id"])
+print(result["generation"]["outputs"])
+```
+
+CLI:
+
+```bash
+clipwise formats list --json
+clipwise resources list poses --video-format ugc_product_background --json
+clipwise resources upload background_music ./track.mp3 --json
+clipwise resources upload overlays ./overlay.webm --type underlay --json
+clipwise resources generate avatars --prompt "Friendly skincare presenter" --video-format ugc_video --json
+clipwise resources generate background_images --prompt "Luxury bathroom counter" --video-format ugc_product_background --json
+clipwise generate --format smart --prompt "Create a 30 second founder launch video" --json
+clipwise wait gen_abc123 --json
+```
+
+The package only talks to `/api/sdk/v1/*` endpoints. It does not import Django
+or use internal frontend endpoints.

clipwise-0.1.0b1/README.md

@@ -0,0 +1,43 @@
+# Clipwise Python SDK and CLI
+
+Install in development:
+
+```bash
+cd backend_clipwise/clipwise_cli
+pip install -e .
+```
+
+Configure:
+
+```bash
+export CLIPWISE_API_KEY="cw_live_..."
+export CLIPWISE_BASE_URL="https://app.clipwise.ai"
+```
+
+Python:
+
+```python
+from clipwise import Clipwise
+
+client = Clipwise()
+formats = client.formats.list(kind="all", platform="all")
+job = client.generations.create(format="smart", prompt="Create a founder launch video")
+result = client.generations.wait(job["id"])
+print(result["generation"]["outputs"])
+```
+
+CLI:
+
+```bash
+clipwise formats list --json
+clipwise resources list poses --video-format ugc_product_background --json
+clipwise resources upload background_music ./track.mp3 --json
+clipwise resources upload overlays ./overlay.webm --type underlay --json
+clipwise resources generate avatars --prompt "Friendly skincare presenter" --video-format ugc_video --json
+clipwise resources generate background_images --prompt "Luxury bathroom counter" --video-format ugc_product_background --json
+clipwise generate --format smart --prompt "Create a 30 second founder launch video" --json
+clipwise wait gen_abc123 --json
+```
+
+The package only talks to `/api/sdk/v1/*` endpoints. It does not import Django
+or use internal frontend endpoints.

clipwise-0.1.0b1/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "clipwise"
+version = "0.1.0b1"
+description = "Python SDK and CLI for Clipwise generation APIs"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "httpx>=0.27",
+    "typing-extensions>=4.8",
+]
+
+[project.scripts]
+clipwise = "clipwise.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clipwise"]

clipwise-0.1.0b1/src/clipwise/__init__.py

@@ -0,0 +1,5 @@
+from .client import Clipwise
+from .errors import ClipwiseError
+
+__all__ = ["Clipwise", "ClipwiseError"]
+

clipwise-0.1.0b1/src/clipwise/cli.py

@@ -0,0 +1,373 @@
+import argparse
+import json
+import sys
+
+from .client import Clipwise
+from .config import clear_api_key, get_api_key, write_config
+from .errors import ClipwiseError
+
+
+def app():
+    return main()
+
+
+def main(argv=None):
+    if argv is None:
+        argv = sys.argv[1:]
+    json_flag = "--json" in argv
+    if json_flag:
+        argv = [item for item in argv if item != "--json"]
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    args.json = bool(args.json or json_flag)
+    try:
+        payload = dispatch(args)
+        if payload is not None:
+            print_payload(payload, as_json=getattr(args, "json", False))
+        return 0
+    except ClipwiseError as exc:
+        error = {
+            "success": False,
+            "error": {
+                "code": exc.code,
+                "message": str(exc),
+                "details": exc.details,
+            },
+            "request_id": exc.request_id,
+        }
+        if getattr(args, "json", False):
+            print(json.dumps(error, indent=2, default=str), file=sys.stderr)
+        else:
+            print(f"{exc.code}: {exc}", file=sys.stderr)
+        return 2
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(prog="clipwise")
+    parser.add_argument("--api-key", default=None)
+    parser.add_argument("--base-url", default=None)
+    parser.add_argument("--timeout", type=float, default=30)
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    auth = subparsers.add_parser("auth")
+    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
+    set_key = auth_sub.add_parser("set-key")
+    set_key.add_argument("key")
+    auth_sub.add_parser("show")
+    auth_sub.add_parser("clear")
+
+    formats = subparsers.add_parser("formats")
+    fmt_sub = formats.add_subparsers(dest="formats_command", required=True)
+    fmt_list = fmt_sub.add_parser("list")
+    fmt_list.add_argument("--kind", default="all", choices=["all", "format", "tool"])
+    fmt_list.add_argument("--platform", default="all", choices=["all", "clipwise", "video_company"])
+    fmt_list.add_argument("--include-inactive", action="store_true")
+    fmt_show = fmt_sub.add_parser("show")
+    fmt_show.add_argument("format")
+
+    resources = subparsers.add_parser("resources")
+    res_sub = resources.add_subparsers(dest="resources_command", required=True)
+    res_sub.add_parser("types")
+    res_list = res_sub.add_parser("list")
+    res_list.add_argument("resource_type")
+    add_resource_filters(res_list)
+    add_pagination_args(res_list)
+    res_show = res_sub.add_parser("show")
+    res_show.add_argument("resource_type")
+    res_show.add_argument("resource_id")
+    res_upload = res_sub.add_parser("upload")
+    res_upload.add_argument("resource_type")
+    res_upload.add_argument("file")
+    add_resource_filters(res_upload)
+    res_generate = res_sub.add_parser("generate")
+    res_generate.add_argument("resource_type")
+    res_generate.add_argument("--prompt", required=True)
+    add_resource_filters(res_generate)
+
+    uploads = subparsers.add_parser("uploads")
+    upload_sub = uploads.add_subparsers(dest="uploads_command", required=True)
+    upload_create = upload_sub.add_parser("create")
+    upload_create.add_argument("file")
+    upload_create.add_argument("--purpose", default="image")
+    upload_create.add_argument("--type", default=None)
+    upload_create.add_argument("--product-type", default=None)
+    upload_list = upload_sub.add_parser("list")
+    add_pagination_args(upload_list)
+
+    products = subparsers.add_parser("products")
+    product_sub = products.add_subparsers(dest="products_command", required=True)
+    product_list = product_sub.add_parser("list")
+    add_pagination_args(product_list)
+    product_create = product_sub.add_parser("create")
+    product_create.add_argument("--name")
+    product_create.add_argument("--image-id", action="append", dest="image_ids")
+    product_create.add_argument("--url")
+    product_create.add_argument("--product-type")
+    product_create.add_argument("--description", default="")
+    product_update = product_sub.add_parser("update")
+    product_update.add_argument("product_id")
+    product_update.add_argument("--name")
+    product_update.add_argument("--description")
+    product_update.add_argument("--product-type")
+    product_delete = product_sub.add_parser("delete")
+    product_delete.add_argument("product_id")
+
+    voices = subparsers.add_parser("voices")
+    voice_sub = voices.add_subparsers(dest="voices_command", required=True)
+    voice_sub.add_parser("list")
+    voice_clone = voice_sub.add_parser("clone")
+    voice_clone.add_argument("file")
+    voice_clone.add_argument("--name")
+    voice_clone.add_argument("--language")
+    voice_clone.add_argument("--description")
+
+    generate = subparsers.add_parser("generate")
+    add_generation_args(generate)
+
+    status = subparsers.add_parser("status")
+    status.add_argument("generation_id")
+
+    wait = subparsers.add_parser("wait")
+    wait.add_argument("generation_id")
+    wait.add_argument("--timeout", type=int, default=1800)
+    wait.add_argument("--poll-interval", type=int, default=5)
+
+    cancel = subparsers.add_parser("cancel")
+    cancel.add_argument("generation_id")
+
+    return parser
+
+
+def add_resource_filters(parser):
+    parser.add_argument("--collection", default=None)
+    parser.add_argument("--video-format", default=None)
+    parser.add_argument("--product-type", default=None)
+    parser.add_argument("--type", default=None)
+    parser.add_argument("--file-type", default=None)
+
+
+def add_pagination_args(parser):
+    parser.add_argument("--page", type=int, default=None)
+    parser.add_argument("--limit", type=int, default=None)
+
+
+def add_generation_args(parser):
+    parser.add_argument("--format", default="smart")
+    parser.add_argument("--mode")
+    parser.add_argument("--prompt")
+    parser.add_argument("--script")
+    parser.add_argument("--language")
+    parser.add_argument("--aspect-ratio")
+    parser.add_argument("--duration")
+    parser.add_argument("--image")
+    parser.add_argument("--images")
+    parser.add_argument("--video")
+    parser.add_argument("--audio")
+    parser.add_argument("--avatar")
+    parser.add_argument("--voice")
+    parser.add_argument("--background-image")
+    parser.add_argument("--reference-image")
+    parser.add_argument("--reference-video")
+    parser.add_argument("--product-id")
+    parser.add_argument("--product-image")
+    parser.add_argument("--product-images")
+    parser.add_argument("--product-type")
+    parser.add_argument("--product-description")
+    parser.add_argument("--ad-format")
+    parser.add_argument("--variations", type=int)
+    parser.add_argument("--metadata")
+    parser.add_argument("--idempotency-key")
+    parser.add_argument("--wait", action="store_true")
+    parser.add_argument("--poll-interval", type=int, default=5)
+
+
+def client_from_args(args):
+    return Clipwise(api_key=args.api_key, base_url=args.base_url, timeout=args.timeout)
+
+
+def dispatch(args):
+    if args.command == "auth":
+        return dispatch_auth(args)
+    client = client_from_args(args)
+    if args.command == "formats":
+        if args.formats_command == "list":
+            return client.formats.list(kind=args.kind, platform=args.platform, include_inactive=args.include_inactive)
+        return client.formats.retrieve(args.format)
+    if args.command == "resources":
+        return dispatch_resources(client, args)
+    if args.command == "uploads":
+        if args.uploads_command == "create":
+            return client.uploads.create(args.file, purpose=args.purpose, type=args.type, product_type=args.product_type)
+        return client.uploads.list(**pagination_filters(args))
+    if args.command == "products":
+        return dispatch_products(client, args)
+    if args.command == "voices":
+        if args.voices_command == "list":
+            return client.voices.list()
+        return client.voices.clone(args.file, name=args.name, language=args.language, description=args.description)
+    if args.command == "generate":
+        payload = build_generation_payload(args)
+        created = client.generations.create(idempotency_key=args.idempotency_key, **payload)
+        if args.wait:
+            return client.generations.wait(created["id"], interval=args.poll_interval)
+        return created
+    if args.command == "status":
+        return client.generations.retrieve(args.generation_id)
+    if args.command == "wait":
+        return client.generations.wait(args.generation_id, timeout=args.timeout, interval=args.poll_interval)
+    if args.command == "cancel":
+        return client.generations.cancel(args.generation_id)
+    return None
+
+
+def dispatch_auth(args):
+    if args.auth_command == "set-key":
+        write_config({"api_key": args.key})
+        return {"success": True, "message": "API key saved"}
+    if args.auth_command == "show":
+        key = get_api_key() or ""
+        return {"success": True, "configured": bool(key), "key_prefix": key[:18] if key else None}
+    if args.auth_command == "clear":
+        clear_api_key()
+        return {"success": True, "message": "API key cleared"}
+    return None
+
+
+def dispatch_resources(client, args):
+    if args.resources_command == "types":
+        return client.resources.types()
+    if args.resources_command == "list":
+        return client.resources.list(args.resource_type, **resource_filters(args))
+    if args.resources_command == "show":
+        return client.resources.retrieve(args.resource_type, args.resource_id)
+    if args.resources_command == "upload":
+        return client.resources.upload(args.resource_type, args.file, **resource_filters(args))
+    if args.resources_command == "generate":
+        return client.resources.generate(args.resource_type, args.prompt, **resource_filters(args))
+    return None
+
+
+def dispatch_products(client, args):
+    if args.products_command == "list":
+        return client.products.list(**pagination_filters(args))
+    if args.products_command == "create":
+        return client.products.create(
+            name=args.name,
+            image_ids=args.image_ids or [],
+            url=args.url,
+            product_type=args.product_type,
+            description=args.description,
+        )
+    if args.products_command == "update":
+        payload = compact({"name": args.name, "description": args.description, "product_type": args.product_type})
+        return client.products.update(args.product_id, **payload)
+    if args.products_command == "delete":
+        return client.products.delete(args.product_id)
+    return None
+
+
+def resource_filters(args):
+    return compact(
+        {
+            "collection": getattr(args, "collection", None),
+            "video_format": getattr(args, "video_format", None),
+            "product_type": getattr(args, "product_type", None),
+            "type": getattr(args, "type", None),
+            "file_type": getattr(args, "file_type", None),
+            **pagination_filters(args),
+        }
+    )
+
+
+def pagination_filters(args):
+    return compact({"page": getattr(args, "page", None), "limit": getattr(args, "limit", None)})
+
+
+def build_generation_payload(args):
+    payload = compact(
+        {
+            "format": args.format,
+            "mode": args.mode,
+            "prompt": read_text_or_value(args.prompt),
+            "script": read_text_or_value(args.script),
+            "language": args.language,
+            "aspect_ratio": args.aspect_ratio,
+            "duration": args.duration,
+            "image": args.image,
+            "images": split_csv(args.images),
+            "video": args.video,
+            "audio": args.audio,
+            "avatar": args.avatar,
+            "voice": args.voice,
+            "background_image": args.background_image,
+            "reference_image": args.reference_image,
+            "reference_video": args.reference_video,
+            "product_id": args.product_id,
+            "product_image": args.product_image,
+            "product_images": split_csv(args.product_images),
+            "product_type": args.product_type,
+            "product_description": args.product_description,
+            "ad_format": args.ad_format,
+            "variations": args.variations,
+        }
+    )
+    if args.metadata:
+        payload["metadata"] = json.loads(read_text_or_value(args.metadata))
+    return payload
+
+
+def read_text_or_value(value):
+    if not value:
+        return value
+    try:
+        from pathlib import Path
+
+        path = Path(value)
+        if path.exists() and path.is_file():
+            return path.read_text()
+    except Exception:
+        return value
+    return value
+
+
+def split_csv(value):
+    if not value:
+        return None
+    return [item.strip() for item in str(value).split(",") if item.strip()]
+
+
+def compact(payload):
+    return {key: value for key, value in payload.items() if value not in (None, "", [])}
+
+
+def print_payload(payload, *, as_json=False):
+    if as_json:
+        print(json.dumps(payload, indent=2, default=str))
+        return
+    if isinstance(payload, dict):
+        generation = payload.get("generation")
+        if isinstance(generation, dict):
+            print(f"{generation.get('id')}: {generation.get('status')}")
+            outputs = generation.get("outputs") if isinstance(generation.get("outputs"), dict) else {}
+            if outputs.get("video_url"):
+                print(outputs["video_url"])
+            if outputs.get("transcript"):
+                print(outputs["transcript"])
+            return
+        if "formats" in payload:
+            for item in payload.get("formats") or []:
+                print(f"{item.get('slug') or item.get('template_name')}\t{item.get('display_name')}\t{item.get('description')}")
+            return
+        if "items" in payload:
+            for item in payload.get("items") or []:
+                print(f"{item.get('id')}\t{item.get('display_name')}\t{item.get('source_kind')}")
+            return
+        if "id" in payload and "status" in payload:
+            print(f"{payload['id']}: {payload['status']}")
+            return
+    print(json.dumps(payload, indent=2, default=str))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

clipwise-0.1.0b1/src/clipwise/client.py

@@ -0,0 +1,219 @@
+import os
+
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+from .config import get_api_key, get_base_url
+from .errors import ClipwiseError
+from .polling import wait_for_generation
+
+
+class Clipwise:
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 30):
+        self.api_key = api_key or get_api_key()
+        self.base_url = (base_url or get_base_url()).rstrip("/")
+        self.timeout = timeout
+        self.formats = FormatsResource(self)
+        self.resources = ResourcesResource(self)
+        self.uploads = UploadsResource(self)
+        self.products = ProductsResource(self)
+        self.voices = VoicesResource(self)
+        self.generations = GenerationsResource(self)
+
+    def request(self, method: str, path: str, *, params=None, json=None, files=None, data=None, headers=None):
+        if not self.api_key:
+            raise ClipwiseError("Missing API key. Set CLIPWISE_API_KEY or run clipwise auth set-key.", code="invalid_api_key")
+        url = f"{self.base_url}{path}"
+        request_headers = {"Authorization": f"Bearer {self.api_key}"}
+        if headers:
+            request_headers.update(headers)
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.request(
+                method,
+                url,
+                params=params,
+                json=json,
+                files=files,
+                data=data,
+                headers=request_headers,
+            )
+        try:
+            payload = response.json()
+        except Exception:
+            payload = {"error": response.text}
+        if response.status_code >= 400:
+            error = payload.get("error") if isinstance(payload, dict) else {}
+            if isinstance(error, dict):
+                raise ClipwiseError(
+                    error.get("message") or "Clipwise API error",
+                    code=error.get("code"),
+                    status_code=response.status_code,
+                    request_id=payload.get("request_id"),
+                    details=error.get("details") or {},
+                )
+            raise ClipwiseError(str(error or "Clipwise API error"), status_code=response.status_code)
+        return payload
+
+
+class FormatsResource:
+    def __init__(self, client: Clipwise):
+        self.client = client
+
+    def list(self, *, kind="all", platform="all", include_inactive=False):
+        return self.client.request(
+            "GET",
+            "/api/sdk/v1/formats/",
+            params={"kind": kind, "platform": platform, "include_inactive": str(bool(include_inactive)).lower()},
+        )
+
+    def retrieve(self, format_id_or_slug):
+        return self.client.request("GET", f"/api/sdk/v1/formats/{format_id_or_slug}/")
+
+
+class ResourcesResource:
+    def __init__(self, client: Clipwise):
+        self.client = client
+
+    def types(self):
+        return self.client.request("GET", "/api/sdk/v1/resource-types/")
+
+    def list(self, resource_type, **filters):
+        return self.client.request("GET", f"/api/sdk/v1/resources/{resource_type}/", params=filters)
+
+    def retrieve(self, resource_type, resource_id):
+        return self.client.request("GET", f"/api/sdk/v1/resources/{resource_type}/{resource_id}/")
+
+    def upload(self, resource_type, file, **metadata):
+        return _multipart_upload(self.client, f"/api/sdk/v1/resources/{resource_type}/upload/", file, metadata)
+
+    def generate(self, resource_type, prompt, **metadata):
+        payload = {"prompt": prompt, **metadata}
+        return self.client.request("POST", f"/api/sdk/v1/resources/{resource_type}/generate/", json=payload)
+
+    def delete(self, resource_type, resource_id):
+        return self.client.request("DELETE", f"/api/sdk/v1/resources/{resource_type}/{resource_id}/")
+
+
+class UploadsResource:
+    def __init__(self, client: Clipwise):
+        self.client = client
+
+    def create(self, file, *, purpose="image", **metadata):
+        return _multipart_upload(self.client, "/api/sdk/v1/uploads/", file, {"purpose": purpose, **metadata})
+
+    def list(self, **filters):
+        return self.client.request("GET", "/api/sdk/v1/uploads/", params=filters)
+
+    def delete(self, upload_id):
+        return self.client.request("DELETE", f"/api/sdk/v1/resources/generic_uploads/{upload_id}/")
+
+
+class ProductsResource:
+    def __init__(self, client: Clipwise):
+        self.client = client
+
+    def list(self, **filters):
+        return self.client.request("GET", "/api/sdk/v1/products/", params=filters)
+
+    def create(self, *, name=None, image_ids=None, url=None, **metadata):
+        payload = {"name": name, "image_ids": image_ids or [], "url": url, **metadata}
+        return self.client.request("POST", "/api/sdk/v1/products/", json={k: v for k, v in payload.items() if v not in (None, [], "")})
+
+    def update(self, product_id, **metadata):
+        return self.client.request("PATCH", f"/api/sdk/v1/products/{product_id}/", json=metadata)
+
+    def delete(self, product_id):
+        return self.client.request("DELETE", f"/api/sdk/v1/products/{product_id}/")
+
+
+class VoicesResource:
+    def __init__(self, client: Clipwise):
+        self.client = client
+
+    def list(self, **filters):
+        return self.client.resources.list("voices", **filters)
+
+    def clone(self, file, *, name=None, language=None, description=None):
+        return self.client.resources.upload(
+            "voices",
+            file,
+            name=name or "",
+            language=language or "",
+            description=description or "",
+        )
+
+
+class GenerationsResource:
+    def __init__(self, client: Clipwise):
+        self.client = client
+
+    def create(self, *, idempotency_key=None, **params):
+        payload = self._upload_local_files(dict(params))
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return self.client.request("POST", "/api/sdk/v1/generations/", json=payload, headers=headers)
+
+    def retrieve(self, generation_id):
+        return self.client.request("GET", f"/api/sdk/v1/generations/{generation_id}/")
+
+    def wait(self, generation_id, *, timeout=1800, interval=5):
+        return wait_for_generation(self.client, generation_id, timeout=timeout, interval=interval)
+
+    def cancel(self, generation_id):
+        return self.client.request("POST", f"/api/sdk/v1/generations/{generation_id}/cancel/")
+
+    def _upload_local_files(self, params: dict[str, Any]) -> dict[str, Any]:
+        single_mappings = {
+            "video": ("uploads", "video"),
+            "audio": ("uploads", "audio"),
+            "image": ("uploads", "image"),
+            "product_image": ("product_images", "product_image"),
+            "reference_image": ("poses", "pose"),
+            "background_image": ("background_images", "background_image"),
+            "reference_video": ("reference_ads", "video"),
+        }
+        for key, (resource_type, purpose) in single_mappings.items():
+            value = params.get(key)
+            if _is_local_file(value):
+                uploaded = (
+                    self.client.uploads.create(value, purpose=purpose)
+                    if resource_type == "uploads"
+                    else self.client.resources.upload(resource_type, value, type=purpose)
+                )
+                params[key] = _extract_id(uploaded)
+        if isinstance(params.get("product_images"), list):
+            params["product_images"] = [
+                _extract_id(self.client.resources.upload("product_images", item))
+                if _is_local_file(item)
+                else item
+                for item in params["product_images"]
+            ]
+        return params
+
+
+def _multipart_upload(client: Clipwise, path: str, file, metadata: dict):
+    file_path = Path(file)
+    if not file_path.exists():
+        raise ClipwiseError(f"File not found: {file}", code="invalid_upload")
+    data = {key: str(value) for key, value in metadata.items() if value is not None}
+    with file_path.open("rb") as handle:
+        files = {"file": (file_path.name, handle)}
+        return client.request("POST", path, files=files, data=data)
+
+
+def _is_local_file(value) -> bool:
+    return isinstance(value, (str, os.PathLike)) and Path(value).exists()
+
+
+def _extract_id(payload):
+    if not isinstance(payload, dict):
+        return payload
+    for key in ("upload", "resource", "product", "token"):
+        value = payload.get(key)
+        if isinstance(value, dict) and value.get("id"):
+            return value["id"]
+    generation = payload.get("generation")
+    if isinstance(generation, dict) and generation.get("id"):
+        return generation["id"]
+    return payload.get("id") or payload

clipwise-0.1.0b1/src/clipwise/config.py

@@ -0,0 +1,44 @@
+import json
+import os
+
+from pathlib import Path
+
+
+DEFAULT_BASE_URL = "https://app.clipwise.ai"
+CONFIG_PATH = Path(os.environ.get("CLIPWISE_CONFIG_PATH", Path.home() / ".clipwise" / "config.json"))
+
+
+def get_api_key():
+    env_key = os.environ.get("CLIPWISE_API_KEY")
+    if env_key:
+        return env_key
+    config = read_config()
+    return config.get("api_key")
+
+
+def get_base_url():
+    return os.environ.get("CLIPWISE_BASE_URL") or read_config().get("base_url") or DEFAULT_BASE_URL
+
+
+def read_config():
+    if not CONFIG_PATH.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_PATH.read_text())
+    except Exception:
+        return {}
+
+
+def write_config(values):
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    current = read_config()
+    current.update(values)
+    CONFIG_PATH.write_text(json.dumps(current, indent=2, sort_keys=True))
+
+
+def clear_api_key():
+    current = read_config()
+    current.pop("api_key", None)
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(current, indent=2, sort_keys=True))
+

clipwise-0.1.0b1/src/clipwise/errors.py

@@ -0,0 +1,8 @@
+class ClipwiseError(Exception):
+    def __init__(self, message, *, code=None, status_code=None, request_id=None, details=None):
+        super().__init__(message)
+        self.code = code or "clipwise_error"
+        self.status_code = status_code
+        self.request_id = request_id
+        self.details = details or {}
+

clipwise-0.1.0b1/src/clipwise/models.py

@@ -0,0 +1,9 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class ResourceRef:
+    id: str
+    resource_type: str
+    source_kind: Optional[str] = None

clipwise-0.1.0b1/src/clipwise/polling.py

@@ -0,0 +1,19 @@
+import time
+
+
+TERMINAL_STATUSES = {"completed", "failed", "cancelled"}
+
+
+def wait_for_generation(client, generation_id, *, timeout=1800, interval=5):
+    deadline = time.time() + timeout
+    while True:
+        payload = client.generations.retrieve(generation_id)
+        generation = payload.get("generation", payload)
+        if generation.get("status") in TERMINAL_STATUSES:
+            return payload
+        if time.time() >= deadline:
+            from .errors import ClipwiseError
+
+            raise ClipwiseError("Timed out waiting for generation", code="timeout")
+        time.sleep(interval)
+

clipwise-0.1.0b1/src/clipwise/resources/__init__.py

@@ -0,0 +1,2 @@
+"""Resource modules are intentionally thin; use `clipwise.Clipwise`."""
+

clipwise-0.1.0b1/src/clipwise/resources/formats.py

@@ -0,0 +1,4 @@
+from ..client import FormatsResource
+
+__all__ = ["FormatsResource"]
+

clipwise-0.1.0b1/src/clipwise/resources/generations.py

@@ -0,0 +1,4 @@
+from ..client import GenerationsResource
+
+__all__ = ["GenerationsResource"]
+

clipwise-0.1.0b1/src/clipwise/resources/products.py

@@ -0,0 +1,4 @@
+from ..client import ProductsResource
+
+__all__ = ["ProductsResource"]
+

clipwise-0.1.0b1/src/clipwise/resources/resources.py

@@ -0,0 +1,4 @@
+from ..client import ResourcesResource
+
+__all__ = ["ResourcesResource"]
+

clipwise-0.1.0b1/src/clipwise/resources/uploads.py

@@ -0,0 +1,4 @@
+from ..client import UploadsResource
+
+__all__ = ["UploadsResource"]
+

clipwise-0.1.0b1/src/clipwise/resources/voices.py

@@ -0,0 +1,4 @@
+from ..client import VoicesResource
+
+__all__ = ["VoicesResource"]
+