cutpro 0.1.0__py3-none-any.whl

cutpro/__init__.py

@@ -0,0 +1,44 @@
+from ._client import AsyncCutPro, CutPro, CutProError, Transport, __version__, proxy_request, urllib_transport, verify_webhook
+from .types import (
+    AspectRatio,
+    CreateGenerationRequest,
+    Generation,
+    GenerationFile,
+    GenerationMode,
+    GenerationOutput,
+    GenerationRequest,
+    Media,
+    Model,
+    ModelList,
+    PriceList,
+    PublicModel,
+    PublicPrice,
+    Quote,
+    Voice,
+)
+
+__all__ = [
+    "AspectRatio",
+    "AsyncCutPro",
+    "CreateGenerationRequest",
+    "CutPro",
+    "CutProError",
+    "Generation",
+    "GenerationFile",
+    "GenerationMode",
+    "GenerationOutput",
+    "GenerationRequest",
+    "Media",
+    "Model",
+    "ModelList",
+    "PriceList",
+    "PublicModel",
+    "PublicPrice",
+    "Quote",
+    "Transport",
+    "Voice",
+    "__version__",
+    "proxy_request",
+    "urllib_transport",
+    "verify_webhook",
+]

cutpro/_client.py

@@ -0,0 +1,430 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import hmac
+import json
+import mimetypes
+import os
+import re
+import shutil
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, Mapping, Optional, Tuple, Union
+
+from .types import (
+    CreateGenerationRequest,
+    DownloadLink,
+    Generation,
+    GenerationRequest,
+    Media,
+    ModelEndpoint,
+    ModelKind,
+    ModelList,
+    PriceList,
+    Quote,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+__version__ = "0.1.0"
+
+API_ORIGIN = "https://api.cut.pro"
+API_PATH = "/api/v1"
+PRICES_PATH = "/public/generations/models"
+MAX_SERVER_WAIT_SECONDS = 60
+DEFAULT_WAIT_TIMEOUT = 600.0
+# Longer than the 60 seconds a create or a get may be held by the server.
+DEFAULT_TIMEOUT = 90.0
+MAX_RETRIES = 2
+RETRY_BASE_SECONDS = 0.5
+RETRYABLE = frozenset({408, 425, 429, 500, 502, 503, 504})
+WEBHOOK_TOLERANCE_SECONDS = 300
+DOWNLOAD_CHUNK_BYTES = 1 << 20
+# The proxy only forwards JSON requests; uploads go from your server with the client.
+MAX_PROXY_BODY_BYTES = 1 << 20
+LOCAL_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+# What `proxy_request()` forwards: everything a browser app needs to price, start and follow a generation, nothing that reads the account.
+PROXIED = (
+    ("GET", re.compile(r"^/models(/featured)?$")),
+    ("GET", re.compile(r"^/prices$")),
+    ("POST", re.compile(r"^/generations(/quote)?$")),
+    ("GET", re.compile(r"^/generations/[\w-]+$")),
+)
+
+Transport = Callable[[str, str, Dict[str, str], Optional[bytes], float], Tuple[int, Mapping[str, str], bytes]]
+"""(method, url, headers, body, timeout) -> (status, response headers, body). Swap it to use another HTTP library or to stub the API in tests."""
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    # A redirect would carry the key to wherever it points, so it is answered as the error it is instead.
+    def redirect_request(self, *args: Any, **kwargs: Any) -> None:
+        return None
+
+
+_opener = urllib.request.build_opener(_NoRedirect)
+
+
+def urllib_transport(method: str, url: str, headers: Dict[str, str], body: Optional[bytes], timeout: float) -> Tuple[int, Mapping[str, str], bytes]:
+    request = urllib.request.Request(url, data=body, headers=headers, method=method)
+    try:
+        with _opener.open(request, timeout=timeout) as response:
+            return int(response.status), dict(response.headers), response.read()
+    except urllib.error.HTTPError as error:
+        return error.code, dict(error.headers or {}), error.read()
+
+
+class CutProError(Exception):
+    """An API error: `code` is stable (switch on it), `status` is the HTTP status, or 0 when the client raised it."""
+
+    def __init__(self, code: str, status: int, extra: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(f"{status} {code}" if status else code)
+        self.code = code
+        self.status = status
+        self.extra = extra
+
+
+def _secure_base(base_url: str) -> str:
+    parsed = urllib.parse.urlsplit(base_url)
+    if parsed.scheme != "https" and not (parsed.scheme == "http" and parsed.hostname in LOCAL_HOSTS):
+        raise CutProError("INSECURE_BASE_URL", 0, {"base_url": base_url})
+    return base_url.rstrip("/")
+
+
+def _retry_after(headers: Mapping[str, str], attempt: int) -> float:
+    value = next((v for k, v in headers.items() if k.lower() == "retry-after"), "")
+    try:
+        return min(max(float(value), 0.0), 30.0)
+    except ValueError:
+        return RETRY_BASE_SECONDS * 2**attempt
+
+
+def _quote_id(id: str) -> str:
+    return urllib.parse.quote(id, safe="")
+
+
+class CutPro:
+    """Synchronous client. Thread safe: it keeps no connection state."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = MAX_RETRIES,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self._api_key = api_key if api_key is not None else os.environ.get("CUTPRO_API_KEY")
+        self._direct = base_url is None
+        self.base_url = _secure_base(base_url or f"{API_ORIGIN}{API_PATH}")
+        self.workspace_id = workspace_id
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.transport = transport or urllib_transport
+        self.models = Models(self)
+        self.generations = Generations(self)
+        self.media = MediaLibrary(self)
+
+    def __repr__(self) -> str:
+        return f"CutPro(base_url={self.base_url!r}, api_key={'set' if self._api_key else 'missing'})"
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Union[str, int, None]]] = None,
+        json_body: Optional[Mapping[str, Any]] = None,
+        body: Optional[bytes] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        auth: bool = True,
+        retry: bool = True,
+        timeout: Optional[float] = None,
+    ) -> Any:
+        # The public price list lives outside /api/v1; a proxy serves it at /prices.
+        url = f"{API_ORIGIN}{PRICES_PATH}" if path == "/prices" and self._direct else f"{self.base_url}{path}"
+        params = {key: str(value) for key, value in (query or {}).items() if value is not None}
+        if params:
+            url = f"{url}?{urllib.parse.urlencode(params)}"
+        sent = {"Accept": "application/json", "User-Agent": f"cutpro-python/{__version__}", **(headers or {})}
+        if auth and self._api_key:
+            sent["X-Api-Key"] = self._api_key
+        if auth and self.workspace_id:
+            sent["X-Workspace-Id"] = self.workspace_id
+        if json_body is not None:
+            sent["Content-Type"] = "application/json"
+            body = json.dumps(json_body).encode()
+
+        attempt = 0
+        while True:
+            try:
+                status, response_headers, raw = self.transport(method, url, sent, body, timeout or self.timeout)
+            except (OSError, TimeoutError):
+                if not retry or attempt >= self.max_retries:
+                    raise
+                time.sleep(RETRY_BASE_SECONDS * 2**attempt)
+                attempt += 1
+                continue
+            if status in RETRYABLE and retry and attempt < self.max_retries:
+                time.sleep(_retry_after(response_headers, attempt))
+                attempt += 1
+                continue
+            break
+        try:
+            payload = json.loads(raw) if raw else None
+        except ValueError:
+            payload = None
+        if status >= 400:
+            error = payload if isinstance(payload, dict) else {}
+            code = error.get("code")
+            raise CutProError(code if isinstance(code, str) else "UNEXPECTED_RESPONSE", status, error.get("extra"))
+        return payload
+
+
+class Models:
+    def __init__(self, client: CutPro) -> None:
+        self._client = client
+
+    def list(self, *, kind: Optional[ModelKind] = None, endpoint: Optional[ModelEndpoint] = None, q: Optional[str] = None, id: Optional[str] = None) -> ModelList:
+        """Every model with its modes, resolutions, seconds, voices and prices in credits, dollars and reais."""
+        return self._client._request("GET", "/models", query={"kind": kind, "endpoint": endpoint, "q": q, "id": id})
+
+    def featured(self, *, kind: Optional[ModelKind] = None, endpoint: Optional[ModelEndpoint] = None) -> ModelList:
+        """Only the strongest models of each kind."""
+        return self._client._request("GET", "/models/featured", query={"kind": kind, "endpoint": endpoint})
+
+    def prices(self) -> PriceList:
+        """Public price list of the image, video and voice models in credits, dollars and reais. Needs no key."""
+        return self._client._request("GET", "/prices", auth=False)
+
+
+class Generations:
+    def __init__(self, client: CutPro) -> None:
+        self._client = client
+
+    def quote(self, **request: Unpack[GenerationRequest]) -> Quote:
+        """The exact total of a request, in credits. Free, generates nothing."""
+        return self._client._request("POST", "/generations/quote", json_body=request)
+
+    def create(self, *, idempotency_key: Optional[str] = None, wait: Optional[int] = None, **request: Unpack[CreateGenerationRequest]) -> Generation:
+        """Starts a generation. Without `credits`, it quotes first and agrees to that total. Safe to retry: the idempotency key never charges twice."""
+        credits = request.pop("credits", None)
+        webhook_url = request.pop("webhook_url", None)
+        if credits is None:
+            credits = int(self._client._request("POST", "/generations/quote", json_body=request)["credits"])
+        body: Dict[str, Any] = {**request, "credits": credits}
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return self._client._request(
+            "POST",
+            "/generations",
+            query={"wait": wait},
+            json_body=body,
+            headers={"Idempotency-Key": idempotency_key or str(uuid.uuid4())},
+            timeout=self._client.timeout + (wait or 0),
+        )
+
+    def get(self, id: str, *, wait: Optional[int] = None) -> Generation:
+        return self._client._request("GET", f"/generations/{_quote_id(id)}", query={"wait": wait}, timeout=self._client.timeout + (wait or 0))
+
+    def wait(self, id: str, *, interval: float = 1.0, timeout: float = DEFAULT_WAIT_TIMEOUT) -> Generation:
+        """Polls until the generation is `ready` or `failed` and returns it either way. Each poll is held by the server for up to 60 seconds."""
+        deadline = time.monotonic() + timeout
+        while True:
+            generation = self.get(id, wait=min(MAX_SERVER_WAIT_SECONDS, max(0, int(deadline - time.monotonic()))))
+            if generation["status"] != "processing":
+                return generation
+            if time.monotonic() + interval >= deadline:
+                raise CutProError("WAIT_TIMEOUT", 0, {"id": id})
+            time.sleep(interval)
+
+    def generate(self, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = DEFAULT_WAIT_TIMEOUT, **request: Unpack[CreateGenerationRequest]) -> Generation:
+        """Quotes, creates and waits. Raises `CutProError` with the generation's `error_code` when it fails."""
+        started = self.create(idempotency_key=idempotency_key, wait=min(MAX_SERVER_WAIT_SECONDS, int(timeout)), **request)
+        generation = self.wait(started["id"], interval=interval, timeout=timeout) if started["status"] == "processing" else started
+        if generation["status"] == "failed":
+            raise CutProError(generation["error_code"] or "GENERATION_FAILED", 0, {"id": generation["id"]})
+        return generation
+
+    def download(self, id: str) -> DownloadLink:
+        """Full quality link, valid for 6 hours. After downloading, the credits can no longer be asked back."""
+        return self._client._request("GET", f"/generations/{_quote_id(id)}/download")
+
+    def download_to(self, id: str, path: Union[str, Path]) -> Path:
+        """Streams the full quality file to `path` without holding it in memory, and returns the path."""
+        url = self.download(id)["url"]
+        if urllib.parse.urlsplit(url).scheme != "https":
+            raise CutProError("INSECURE_DOWNLOAD_URL", 0, {"id": id})
+        target = Path(path)
+        partial = target.with_name(f"{target.name}.part")
+        with urllib.request.urlopen(url, timeout=self._client.timeout) as response, partial.open("wb") as file:
+            shutil.copyfileobj(response, file, DOWNLOAD_CHUNK_BYTES)
+        partial.replace(target)
+        return target
+
+    def webhook_secret(self) -> str:
+        """The secret that signs this key's webhooks, for `verify_webhook()`. Keep it on the server."""
+        return str(self._client._request("GET", "/generations/webhook-secret")["secret"])
+
+
+class MediaLibrary:
+    def __init__(self, client: CutPro) -> None:
+        self._client = client
+
+    def upload(
+        self,
+        data: Union[bytes, str, Path, None] = None,
+        *,
+        filename: Optional[str] = None,
+        content_type: Optional[str] = None,
+        url: Optional[str] = None,
+    ) -> Media:
+        """Uploads an image, video or sound (bytes or a file path, up to 100 MB), or reads one from a public `url`, for `image_ids`, `audio_ids` or `video_id`."""
+        if url is not None:
+            return self._client._request("POST", "/generations/media", json_body={"url": url})
+        if data is None:
+            raise ValueError("Pass the file bytes, a file path or url=.")
+        if not isinstance(data, bytes):
+            path = Path(data)
+            filename = filename or path.name
+            data = path.read_bytes()
+        name = (filename or "upload").replace('"', "").replace("\r", "").replace("\n", "")
+        kind = content_type or mimetypes.guess_type(name)[0] or "application/octet-stream"
+        boundary = uuid.uuid4().hex
+        body = (
+            f'--{boundary}\r\nContent-Disposition: form-data; name="file"; filename="{name}"\r\nContent-Type: {kind}\r\n\r\n'.encode()
+            + data
+            + f"\r\n--{boundary}--\r\n".encode()
+        )
+        return self._client._request(
+            "POST", "/generations/media", body=body, headers={"Content-Type": f"multipart/form-data; boundary={boundary}"}, retry=False
+        )
+
+
+class AsyncCutPro:
+    """Asyncio client with the same methods as `CutPro`. Each call runs in a worker thread and waiting never blocks the event loop."""
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        self.sync = CutPro(api_key, **options)
+        self.models = _AsyncModels(self.sync)
+        self.generations = _AsyncGenerations(self.sync)
+        self.media = _AsyncMedia(self.sync)
+
+    def __repr__(self) -> str:
+        return f"Async{self.sync!r}"
+
+
+class _AsyncModels:
+    def __init__(self, client: CutPro) -> None:
+        self._sync = client.models
+
+    async def list(self, **filters: Any) -> ModelList:
+        return await asyncio.to_thread(self._sync.list, **filters)
+
+    async def featured(self, **filters: Any) -> ModelList:
+        return await asyncio.to_thread(self._sync.featured, **filters)
+
+    async def prices(self) -> PriceList:
+        return await asyncio.to_thread(self._sync.prices)
+
+
+class _AsyncGenerations:
+    def __init__(self, client: CutPro) -> None:
+        self._sync = client.generations
+
+    async def quote(self, **request: Unpack[GenerationRequest]) -> Quote:
+        return await asyncio.to_thread(lambda: self._sync.quote(**request))
+
+    async def create(self, *, idempotency_key: Optional[str] = None, wait: Optional[int] = None, **request: Unpack[CreateGenerationRequest]) -> Generation:
+        return await asyncio.to_thread(lambda: self._sync.create(idempotency_key=idempotency_key, wait=wait, **request))
+
+    async def get(self, id: str, *, wait: Optional[int] = None) -> Generation:
+        return await asyncio.to_thread(self._sync.get, id, wait=wait)
+
+    async def wait(self, id: str, *, interval: float = 1.0, timeout: float = DEFAULT_WAIT_TIMEOUT) -> Generation:
+        deadline = time.monotonic() + timeout
+        while True:
+            generation = await self.get(id, wait=min(MAX_SERVER_WAIT_SECONDS, max(0, int(deadline - time.monotonic()))))
+            if generation["status"] != "processing":
+                return generation
+            if time.monotonic() + interval >= deadline:
+                raise CutProError("WAIT_TIMEOUT", 0, {"id": id})
+            await asyncio.sleep(interval)
+
+    async def generate(self, *, idempotency_key: Optional[str] = None, interval: float = 1.0, timeout: float = DEFAULT_WAIT_TIMEOUT, **request: Unpack[CreateGenerationRequest]) -> Generation:
+        started = await self.create(idempotency_key=idempotency_key, wait=min(MAX_SERVER_WAIT_SECONDS, int(timeout)), **request)
+        generation = await self.wait(started["id"], interval=interval, timeout=timeout) if started["status"] == "processing" else started
+        if generation["status"] == "failed":
+            raise CutProError(generation["error_code"] or "GENERATION_FAILED", 0, {"id": generation["id"]})
+        return generation
+
+    async def download(self, id: str) -> DownloadLink:
+        return await asyncio.to_thread(self._sync.download, id)
+
+    async def download_to(self, id: str, path: Union[str, Path]) -> Path:
+        return await asyncio.to_thread(self._sync.download_to, id, path)
+
+    async def webhook_secret(self) -> str:
+        return await asyncio.to_thread(self._sync.webhook_secret)
+
+
+class _AsyncMedia:
+    def __init__(self, client: CutPro) -> None:
+        self._sync = client.media
+
+    async def upload(self, data: Union[bytes, str, Path, None] = None, **options: Any) -> Media:
+        return await asyncio.to_thread(lambda: self._sync.upload(data, **options))
+
+
+def verify_webhook(raw_body: Union[bytes, str], signature: Optional[str], secret: str, *, tolerance: int = WEBHOOK_TOLERANCE_SECONDS) -> bool:
+    """True when `CutPro-Signature` signs this exact raw body with your secret and is under five minutes old. Pass the body before any JSON parsing."""
+    parts = dict(part.split("=", 1) for part in (signature or "").split(",") if "=" in part)
+    try:
+        timestamp = int(parts.get("t", ""))
+    except ValueError:
+        return False
+    if abs(time.time() - timestamp) > tolerance:
+        return False
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, parts.get("v1", ""))
+
+
+def proxy_request(
+    method: str,
+    path: str,
+    *,
+    body: Optional[bytes] = None,
+    headers: Optional[Mapping[str, str]] = None,
+    query: str = "",
+    api_key: Optional[str] = None,
+    transport: Optional[Transport] = None,
+) -> Tuple[int, bytes]:
+    """
+    Forwards a browser app's call from your own route to Cut.Pro with the key added on the server, so the page never sees it.
+    `path` is what follows your route's prefix, such as `/generations/quote`. Check your own session before calling it: every forwarded call spends your credits.
+    Returns (status, JSON body) for FastAPI, Flask, Django or any framework.
+    """
+    key = api_key or os.environ.get("CUTPRO_API_KEY")
+    if not key:
+        return 500, b'{"code":"API_KEY_MISSING"}'
+    if not any(allowed == method and pattern.match(path) for allowed, pattern in PROXIED):
+        return 404, b'{"code":"NOT_FOUND"}'
+    if body is not None and len(body) > MAX_PROXY_BODY_BYTES:
+        return 413, b'{"code":"PAYLOAD_TOO_LARGE"}'
+    target = f"{API_ORIGIN}{PRICES_PATH}" if path == "/prices" else f"{API_ORIGIN}{API_PATH}{path}"
+    if query:
+        target = f"{target}?{query.lstrip('?')}"
+    sent = {"Accept": "application/json", "X-Api-Key": key}
+    for name, value in (headers or {}).items():
+        if name.lower() in ("content-type", "idempotency-key"):
+            sent[name] = value
+    status, _, raw = (transport or urllib_transport)(method, target, sent, body if method != "GET" else None, DEFAULT_TIMEOUT)
+    return status, raw

cutpro/types.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from typing import Dict, List, Literal, Optional, TypedDict, Union
+
+GenerationKind = Literal["image", "video", "speech", "music", "audio", "avatar", "model3d", "tool", "videoedit", "story"]
+ModelKind = Literal["image", "video", "speech", "music", "audio", "avatar", "model3d", "tool", "videoedit", "story", "text", "embedding"]
+ModelEndpoint = Literal["generations", "chat_completions", "embeddings"]
+GenerationMode = Literal["text", "image", "frames", "references", "edit", "control"]
+AspectRatio = Literal["21:9", "16:9", "3:2", "4:3", "5:4", "1:1", "4:5", "3:4", "2:3", "9:16"]
+Preset = Literal["fast", "balanced", "best"]
+GenerationStatus = Literal["processing", "ready", "failed"]
+OptionValue = Union[str, int, float, bool, List[str]]
+
+
+class GenerationRequest(TypedDict, total=False):
+    kind: Literal["image", "video", "speech"]
+    model: str
+    preset: Preset
+    mode: GenerationMode
+    resolution: str
+    prompt: str
+    options: Dict[str, OptionValue]
+    seconds: int
+    aspect_ratio: AspectRatio
+    audio: bool
+    voice: str
+    image_ids: List[str]
+    image_urls: List[str]
+    audio_ids: List[str]
+    audio_urls: List[str]
+    video_id: str
+    orientation: Literal["image", "video"]
+    seed: int
+
+
+class CreateGenerationRequest(GenerationRequest, total=False):
+    credits: int
+    webhook_url: str
+
+
+class Quote(TypedDict):
+    credits: float
+    model: str
+    kind: GenerationKind
+    mode: Optional[GenerationMode]
+    resolution: Optional[str]
+    seconds: Optional[float]
+    aspect_ratio: Optional[AspectRatio]
+    audio: Optional[bool]
+    warnings: List[str]
+
+
+class GenerationOutput(TypedDict):
+    image_id: Optional[str]
+    video_id: Optional[str]
+    audio_id: Optional[str]
+    url: str
+    thumbnail_url: Optional[str]
+
+
+class GenerationFile(TypedDict):
+    kind: Literal["image", "video", "audio", "file"]
+    url: str
+    media_type: Optional[str]
+    bytes: int
+    media_id: Optional[str]
+    file_name: Optional[str]
+
+
+class Generation(TypedDict):
+    id: str
+    kind: GenerationKind
+    status: GenerationStatus
+    model: str
+    model_name: str
+    mode: Optional[GenerationMode]
+    resolution: Optional[str]
+    seconds: Optional[float]
+    aspect_ratio: Optional[AspectRatio]
+    voice: Optional[str]
+    prompt: Optional[str]
+    audio: Optional[bool]
+    voice_name: Optional[str]
+    image_ids: List[str]
+    audio_ids: List[str]
+    video_id: Optional[str]
+    seed: Optional[int]
+    credits_charged: float
+    error_code: Optional[str]
+    edit_id: Optional[str]
+    output: Optional[GenerationOutput]
+    outputs: List[GenerationFile]
+    text: Optional[str]
+    options: Optional[Dict[str, OptionValue]]
+    expected_seconds: Optional[float]
+    feedback: Optional[Literal["up", "down"]]
+    feedback_reason: Optional[str]
+    refund_status: Optional[Literal["requested", "approved", "denied"]]
+    downloaded: bool
+    removed: bool
+    created_at: str
+
+
+class ModelPricing(TypedDict):
+    unit: str
+    credits: float
+    mode: Optional[GenerationMode]
+    resolution: Optional[str]
+    silent_credits: Optional[float]
+
+
+class Voice(TypedDict):
+    id: str
+    name: str
+    style: Optional[str]
+    gender: Optional[Literal["female", "male"]]
+    age: Optional[Literal["young", "mature"]]
+    language: Optional[str]
+    preview_url: Optional[str]
+    portrait_url: Optional[str]
+
+
+class Model(TypedDict):
+    id: str
+    name: str
+    maker: str
+    kind: ModelKind
+    endpoint: ModelEndpoint
+    featured: bool
+    pricing: List[ModelPricing]
+    priced_by_request: bool
+    modes: List[GenerationMode]
+    resolutions: List[str]
+    seconds: List[float]
+    aspect_ratios: List[AspectRatio]
+    audio: Optional[Literal["always", "optional"]]
+    max_images: int
+    max_audios: int
+    max_video_seconds: Optional[float]
+    voices: List[Voice]
+    typical_seconds: Optional[float]
+    success_rate: Optional[float]
+
+
+class PresetModel(TypedDict):
+    id: Preset
+    model: str
+    resolution: str
+
+
+class Presets(TypedDict):
+    video: List[PresetModel]
+    image: List[PresetModel]
+    speech: List[PresetModel]
+
+
+class ModelList(TypedDict):
+    models: List[Model]
+    presets: Presets
+    prompt_max: int
+    max_running: int
+    improve_credits: float
+
+
+class Money(TypedDict):
+    credits: float
+    usd: float
+    brl: float
+
+
+class PublicPrice(Money):
+    mode: str
+    resolution: str
+    silent: Optional[Money]
+    lowest: bool
+
+
+class PublicModel(TypedDict):
+    id: str
+    name: str
+    maker: str
+    kind: Literal["video", "image", "speech"]
+    unit: Literal["second", "image", "1k_characters"]
+    modes: List[str]
+    resolutions: List[str]
+    seconds: List[int]
+    aspect_ratios: List[str]
+    audio: Optional[str]
+    max_images: int
+    max_video_seconds: Optional[float]
+    prices: List[PublicPrice]
+
+
+class CreditPrice(TypedDict):
+    usd: float
+    brl: float
+
+
+class PriceList(TypedDict):
+    updated_at: str
+    credit: CreditPrice
+    models: List[PublicModel]
+
+
+class Media(TypedDict):
+    id: str
+    kind: Literal["image", "video", "audio"]
+    seconds: Optional[float]
+
+
+class DownloadLink(TypedDict):
+    url: str

cutpro-0.1.0.dist-info/METADATA

@@ -0,0 +1,263 @@
+Metadata-Version: 2.5
+Name: cutpro
+Version: 0.1.0
+Summary: Cut.Pro API client for Python: Seedance, Wan, Kling, Veo, Nano Banana, Seedream, GPT Image and Gemini TTS with one key, priced per second, image or 1,000 characters
+Project-URL: Homepage, https://cut.pro/docs/en/generations
+Project-URL: Source, https://github.com/getcutpro/sdk-python
+Project-URL: Issues, https://github.com/getcutpro/sdk-python/issues
+Project-URL: Prices, https://cut.pro/en/models
+Author: Cut.Pro
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,api,cutpro,gemini-tts,gpt-image,image-generation,image-to-video,kling,nano-banana,sdk,seedance,seedance-api,seedream,text-to-speech,text-to-video,veo,video-generation,wan
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Cut.Pro Python SDK: Seedance, Wan, Kling, Veo and Nano Banana API in Python
+
+[![PyPI](https://img.shields.io/pypi/v/cutpro)](https://pypi.org/project/cutpro/) [![license](https://img.shields.io/pypi/l/cutpro)](LICENSE)
+
+One API key for video, image and voice models: Seedance 2.5, Wan 3, Kling O3, Veo 3.1, Gemini Omni Flash, Nano Banana Pro, Seedream 5, Qwen Image, GPT Image, Grok Imagine, MiniMax and Gemini TTS voices. Priced per second of video, per image or per 1,000 characters of voice, in reais and dollars: see the [live price list](https://cut.pro/en/models). Pay with Pix or card; companies get an invoice.
+
+Python 3.9 to 3.13, standard library only (no dependencies), fully typed (`py.typed`), sync and asyncio. A pure wheel, so it installs the same way in any environment:
+
+```bash
+pip install cutpro          # pip, virtualenv, Anaconda and Miniconda environments
+uv add cutpro               # uv
+poetry add cutpro           # Poetry
+pdm add cutpro              # PDM
+pipenv install cutpro       # Pipenv
+```
+
+## Quickstart
+
+Create a key at [cut.pro/studio/me/api-keys](https://cut.pro/studio/me/api-keys) and set `CUTPRO_API_KEY`. Every account starts with free credits.
+
+```python
+from cutpro import CutPro
+
+cutpro = CutPro()  # reads CUTPRO_API_KEY
+
+video = cutpro.generations.generate(
+    model="bytedance/seedance-2.5",
+    prompt="a golden retriever surfing a wave at sunset, cinematic",
+    seconds=5,
+    resolution="720p",
+    aspect_ratio="16:9",
+)
+print(video["output"]["url"], video["credits_charged"], "credits")
+```
+
+`generate()` quotes the request, starts it with the quoted total and waits until it is ready. Each step is also its own call.
+
+## Seedance API in Python, step by step
+
+```python
+import uuid
+
+quote = cutpro.generations.quote(model="bytedance/seedance-2.5", prompt="a dog surfing", seconds=5)
+print(quote["credits"], "credits")  # show the price and wait for a yes
+
+started = cutpro.generations.create(
+    model="bytedance/seedance-2.5",
+    prompt="a dog surfing",
+    seconds=5,
+    credits=quote["credits"],
+    idempotency_key=str(uuid.uuid4()),
+)
+
+done = cutpro.generations.wait(started["id"], timeout=600)
+if done["status"] == "ready":
+    print(done["output"]["url"])
+```
+
+- `create()` without `credits` quotes first and agrees to that total. With `credits`, the price is checked on the server: if it changed, nothing is charged and you get `PRICE_CHANGED` with the new total in `extra["credits"]`.
+- `idempotency_key`: repeating the same request with the same key within 24 hours never charges twice.
+- `webhook_url="https://..."` gets a signed POST when the generation ends, instead of waiting.
+
+## Wan 3 image to video
+
+```python
+clip = cutpro.generations.generate(
+    model="alibaba/wan-3",
+    mode="image",
+    image_urls=["https://your-cdn.com/product.jpg"],
+    prompt="the camera slowly orbits the product, soft studio light",
+    seconds=5,
+    resolution="720p",
+)
+```
+
+Local file? `media = cutpro.media.upload(open("product.jpg", "rb").read(), filename="product.jpg", content_type="image/jpeg")` and send `image_ids=[media["id"]]`.
+
+## Nano Banana Pro image with references
+
+```python
+image = cutpro.generations.generate(
+    model="google/nano-banana-pro",
+    mode="references",
+    image_urls=["https://your-cdn.com/person.jpg", "https://your-cdn.com/jacket.jpg"],
+    prompt="the person from the first image wearing the jacket from the second, street photo",
+    aspect_ratio="4:5",
+)
+```
+
+## Gemini TTS voice
+
+```python
+voices = cutpro.models.list(id="google/gemini-3.1-flash-tts")["models"][0]["voices"]
+print([voice["id"] for voice in voices])
+
+voice = cutpro.generations.generate(model="google/gemini-3.1-flash-tts", voice="Kore", prompt="Welcome to Cut.Pro. Your video is ready.")
+print(voice["output"]["url"])  # MP3
+```
+
+## Models and prices
+
+```python
+catalog = cutpro.models.list(kind="video", endpoint="generations")
+featured = cutpro.models.featured(kind="image")
+
+# Public price list, no key needed: credits, dollars and reais per unit.
+prices = CutPro().models.prices()
+```
+
+| Kind | Model ids |
+|---|---|
+| Video | [`bytedance/seedance-2.5`](https://cut.pro/en/models/seedance-2-5), [`bytedance/seedance-2`](https://cut.pro/en/models/seedance-2), [`alibaba/wan-3`](https://cut.pro/en/models/wan-3), [`kling/kling-o3-pro`](https://cut.pro/en/models/kling-o3-pro), [`kling/kling-3-pro`](https://cut.pro/en/models/kling-3-pro), [`google/veo-3.1`](https://cut.pro/en/models/veo-3-1), [`google/gemini-omni-flash-1.1`](https://cut.pro/en/models/gemini-omni-flash-1-1), [`xai/grok-imagine-video-1.5`](https://cut.pro/en/models/grok-imagine-video-1-5), [`minimax/h3`](https://cut.pro/en/models/h3) |
+| Image | [`google/nano-banana-pro`](https://cut.pro/en/models/nano-banana-pro), [`bytedance/seedream-5-pro`](https://cut.pro/en/models/seedream-5-pro), [`alibaba/qwen-image-3-pro`](https://cut.pro/en/models/qwen-image-3-pro), [`openai/gpt-image-2.5`](https://cut.pro/en/models/gpt-image-2-5), [`xai/grok-imagine-image-2`](https://cut.pro/en/models/grok-imagine-image-2) |
+| Voice | [`google/gemini-3.1-flash-tts`](https://cut.pro/en/models/gemini-3-1-flash-tts), [`minimax/speech-2.8-hd`](https://cut.pro/en/models/speech-2-8-hd) |
+
+The full catalog is in `models.list()` and at [cut.pro/en/models](https://cut.pro/en/models). Prices change: read them from the API, never hard-code them.
+
+## Errors
+
+```python
+from cutpro import CutProError
+
+try:
+    cutpro.generations.generate(model="bytedance/seedance-2.5", prompt="a dog surfing", seconds=3)
+except CutProError as error:
+    if error.code == "INSUFFICIENT_CREDITS":
+        print("Top up at", error.extra["top_up_url"])
+    elif error.code == "SECONDS_INVALID":
+        print("Allowed seconds:", error.extra["allowed"])
+    else:
+        raise
+```
+
+`code` is stable, `status` is the HTTP status and `extra` has what to act on. `status` is `0` for errors raised by the client: `WAIT_TIMEOUT`, `INSECURE_BASE_URL`, `INSECURE_DOWNLOAD_URL`, or a generation that ended `failed` (its `error_code` becomes `code`, and the credits come back on their own). Full list in the [error catalog](https://cut.pro/docs/en/errors).
+
+## asyncio
+
+`AsyncCutPro` has the same methods. Waiting never blocks the event loop, so FastAPI, aiohttp or a Jupyter notebook can run many generations at once.
+
+```python
+import asyncio
+from cutpro import AsyncCutPro
+
+async def main() -> None:
+    cutpro = AsyncCutPro()
+    videos = await asyncio.gather(*(cutpro.generations.generate(model="bytedance/seedance-2-fast", prompt=p, seconds=5) for p in ["a dog surfing", "a cat skating"]))
+    print([video["output"]["url"] for video in videos])
+
+asyncio.run(main())
+```
+
+## Download to a file
+
+```python
+cutpro.generations.download_to(video["id"], "dog.mp4")  # streams to disk, never holds the whole file in memory
+```
+
+## Webhooks
+
+```python
+from cutpro import verify_webhook
+
+secret = cutpro.generations.webhook_secret()  # store it with your other secrets
+
+# In your webhook route, with the raw body before any JSON parsing:
+if not verify_webhook(raw_body, headers.get("CutPro-Signature"), secret):
+    return 401
+```
+
+It checks the HMAC of the exact body, refuses signatures older than five minutes and compares in constant time.
+
+## A browser app on your Python server
+
+The key spends credits, so it never goes to a page. `proxy_request` forwards only what a generation needs (models, prices, quote, create, get) with the key added on your server. With FastAPI:
+
+```python
+from fastapi import FastAPI, Request, Response
+from cutpro import proxy_request
+
+app = FastAPI()
+
+@app.api_route("/api/cutpro/{path:path}", methods=["GET", "POST"])
+async def cutpro_proxy(path: str, request: Request) -> Response:
+    if not is_signed_in(request):  # whoever reaches this route spends your credits
+        return Response(status_code=401)
+    status, body = proxy_request(request.method, f"/{path}", body=await request.body(), headers=dict(request.headers), query=request.url.query)
+    return Response(body, status_code=status, media_type="application/json")
+```
+
+The page uses the JavaScript SDK with `new CutPro({ baseURL: "/api/cutpro" })`.
+
+## Options
+
+```python
+CutPro(
+    api_key="...",          # defaults to CUTPRO_API_KEY
+    workspace_id="...",     # only for a key that reaches more than one workspace
+    base_url="https://api.cut.pro/api/v1",
+    timeout=90.0,           # seconds per HTTP request
+    max_retries=2,
+    transport=my_transport, # (method, url, headers, body, timeout) -> (status, headers, body): plug in httpx or requests, or stub it in tests
+)
+```
+
+## Security and reliability
+
+- The key only travels in the `X-Api-Key` header, never in a URL, and redirects are refused so it never follows one to another host. `repr(client)` never shows it.
+- `base_url` must be `https`, except on localhost.
+- `generations.create` sends an `Idempotency-Key` (a fresh UUID unless you pass one), so a retry or a repeated call never charges twice.
+- Network errors, `429` and `5xx` are retried twice with backoff, honoring `Retry-After`; uploads are never retried.
+- Waiting uses the server's long poll instead of hammering it.
+
+## Links
+
+- [Generation guide](https://cut.pro/docs/en/generations) and [API reference](https://cut.pro/docs/reference)
+- [Node SDK](https://github.com/getcutpro/sdk-js), [Vercel AI SDK provider](https://github.com/getcutpro/ai-sdk-provider), [n8n node](https://github.com/getcutpro/n8n-nodes-cutpro), [examples](https://github.com/getcutpro/examples)
+
+## Em português
+
+Instala igual com pip, uv, Poetry, PDM, Pipenv e em ambientes Anaconda ou Miniconda (`pip install cutpro`). Tem cliente síncrono e assíncrono (`AsyncCutPro`), verificação de webhook e proxy para usar no navegador sem expor a chave.
+
+SDK oficial da Cut.Pro para Python: uma chave de API para Seedance 2.5, Wan 3, Kling O3, Veo 3.1, Nano Banana Pro, Seedream 5, GPT Image, Grok Imagine, MiniMax e vozes do Gemini TTS. Preço por segundo de vídeo, por imagem ou por 1.000 caracteres de voz, em reais: veja a [tabela de preços ao vivo](https://cut.pro/pt-BR/models). Pague com Pix ou cartão, com nota fiscal para empresas. Toda conta começa com créditos grátis.
+
+```python
+from cutpro import CutPro
+
+cutpro = CutPro()  # lê CUTPRO_API_KEY
+voz = cutpro.generations.generate(model="google/gemini-3.1-flash-tts", voice="Kore", prompt="Olá! Seu vídeo está pronto.")
+print(voz["output"]["url"])
+```
+
+Crie a chave em [cut.pro/studio/me/api-keys](https://cut.pro/studio/me/api-keys). Guia em português: [cut.pro/docs/generations](https://cut.pro/docs/generations). Páginas dos modelos: [Seedance 2.5](https://cut.pro/pt-BR/models/seedance-2-5), [Wan 3](https://cut.pro/pt-BR/models/wan-3), [Nano Banana Pro](https://cut.pro/pt-BR/models/nano-banana-pro), [Gemini 3.1 Flash TTS](https://cut.pro/pt-BR/models/gemini-3-1-flash-tts).
+
+## License
+
+MIT

cutpro-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cutpro/__init__.py,sha256=omgfoWGG85ZKipYLHqRu1L_UHoSozYLZrGnsrxiX8wk,860
+cutpro/_client.py,sha256=oe-_xxDhXhMDcqXP2zuJyzoMjG5lK7LuTA9J1vcvdWs,19307
+cutpro/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cutpro/types.py,sha256=raxX-mUBz6GGdKROwC5vEe8i6at6_mVy6od5_iEEmTU,5156
+cutpro-0.1.0.dist-info/METADATA,sha256=GioTrhejP7d4gkG5OBjOkAftJqQcRnLpeMotGv32BzI,12205
+cutpro-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+cutpro-0.1.0.dist-info/licenses/LICENSE,sha256=uYa0hjp2TQGA9FHrifYlkOIzz6hHpNZnwzc1HXYKg2U,1064
+cutpro-0.1.0.dist-info/RECORD,,

cutpro-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cutpro-0.1.0.dist-info/licenses/LICENSE

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