fittins 1.0.0__py3-none-any.whl

fittins/__init__.py

@@ -0,0 +1,19 @@
+"""Official Python library for the Fittins AI API."""
+
+from . import types
+from ._client import Fittins
+from ._version import __version__
+from .errors import APIConnectionError, APIError, FittinsError, WaitTimeoutError, WebhookVerificationError
+from .webhooks import verify_webhook
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "Fittins",
+    "FittinsError",
+    "WaitTimeoutError",
+    "WebhookVerificationError",
+    "__version__",
+    "types",
+    "verify_webhook",
+]

fittins/_client.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import http.client
+import json
+import os
+import random
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import TYPE_CHECKING, Any, BinaryIO, Callable, Dict, Iterator, List, Mapping, Optional, Tuple, TypedDict, Union
+
+from ._version import __version__
+from .errors import APIConnectionError, APIError, FittinsError, WaitTimeoutError, parse_api_error
+from .types import (
+    Account,
+    CreateImageParams,
+    CreateLocationParams,
+    CreateModelParams,
+    CreateVideoParams,
+    Deleted,
+    Generation,
+    GenerationStatus,
+    GenerationType,
+    Location,
+    Model,
+    Upload,
+    Usage,
+    WebhookEndpoint,
+    WebhookEventType,
+)
+
+if TYPE_CHECKING:
+    from typing_extensions import Literal, Unpack
+
+DEFAULT_BASE_URL = "https://api.fittins.ai/v1"
+DEFAULT_TIMEOUT = 120.0
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_WAIT_TIMEOUT = 20 * 60.0
+DEFAULT_WAIT_INTERVAL = 5.0
+# A longer Retry-After than this goes back to the caller instead of being waited out.
+MAX_RETRY_AFTER_SECONDS = 60.0
+RETRY_BASE = 0.5
+RETRY_MAX = 8.0
+TRANSIENT_STATUS = {500, 502, 503, 504}
+FINISHED = {"succeeded", "failed", "canceled"}
+NETWORK_ERRORS = (urllib.error.URLError, http.client.HTTPException, ConnectionError, TimeoutError, ssl.SSLError, OSError)
+
+FileInput = Union[str, "os.PathLike[str]", bytes, bytearray, BinaryIO]
+
+
+class ListResponse(TypedDict):
+    object: str
+    data: List[Any]
+    has_more: bool
+    next_cursor: Optional[str]
+
+
+def _backoff(attempt: int) -> float:
+    ceiling = min(RETRY_MAX, RETRY_BASE * 2**attempt)
+    return ceiling / 2 + random.random() * (ceiling / 2)
+
+
+def _retry_delay(error: APIError, repeatable: bool, attempt: int) -> Optional[float]:
+    if error.status != 429 and not (repeatable and error.status in TRANSIENT_STATUS):
+        return None
+    if error.retry_after is None:
+        return _backoff(attempt)
+    return None if error.retry_after > MAX_RETRY_AFTER_SECONDS else error.retry_after
+
+
+def _segment(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+def _multipart(filename: str, content: bytes, content_type: str) -> Tuple[bytes, str]:
+    boundary = uuid.uuid4().hex
+    safe_name = filename.replace("\\", "_").replace('"', "_").replace("\r", "_").replace("\n", "_")
+    head = (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="file"; filename="{safe_name}"\r\n'
+        f"Content-Type: {content_type}\r\n\r\n"
+    ).encode("utf-8")
+    return head + content + f"\r\n--{boundary}--\r\n".encode("ascii"), f"multipart/form-data; boundary={boundary}"
+
+
+def _read_file(file: FileInput, filename: Optional[str]) -> Tuple[bytes, str]:
+    if isinstance(file, (bytes, bytearray)):
+        return bytes(file), filename or "product"
+    if isinstance(file, (str, os.PathLike)):
+        with open(file, "rb") as handle:
+            return handle.read(), filename or os.path.basename(os.fspath(file))
+    name = getattr(file, "name", None)
+    return file.read(), filename or (os.path.basename(name) if isinstance(name, str) else "product")
+
+
+class _Images:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def create(self, *, idempotency_key: Optional[str] = None, **params: "Unpack[CreateImageParams]") -> Generation:
+        """Create an on-model photo. Answers at once with a queued generation."""
+        return self._client._create("/images", params, idempotency_key)
+
+
+class _Videos:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def create(self, *, idempotency_key: Optional[str] = None, **params: "Unpack[CreateVideoParams]") -> Generation:
+        """Create a fashion video. Answers at once with a queued generation."""
+        return self._client._create("/videos", params, idempotency_key)
+
+
+class _Generations:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        status: Optional[GenerationStatus] = None,
+        type: Optional[GenerationType] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> ListResponse:
+        query = {"status": status, "type": type, "limit": limit, "cursor": cursor}
+        return self._client._json("GET", "/generations", query=query, repeatable=True)
+
+    def list_all(
+        self,
+        *,
+        status: Optional[GenerationStatus] = None,
+        type: Optional[GenerationType] = None,
+        limit: Optional[int] = None,
+    ) -> Iterator[Generation]:
+        """Every generation matching the filters, across pages, newest first."""
+        cursor: Optional[str] = None
+        while True:
+            page = self.list(status=status, type=type, limit=limit, cursor=cursor)
+            yield from page["data"]
+            if not page["has_more"] or not page["next_cursor"]:
+                return
+            cursor = page["next_cursor"]
+
+    def get(self, id: str) -> Generation:
+        return self._client._json("GET", f"/generations/{_segment(id)}", repeatable=True)
+
+    def delete(self, id: str) -> Union[Generation, Deleted]:
+        """Cancel a queued generation, or delete a finished one with its files."""
+        return self._client._json("DELETE", f"/generations/{_segment(id)}")
+
+    def wait(self, id: str, *, timeout: float = DEFAULT_WAIT_TIMEOUT, interval: float = DEFAULT_WAIT_INTERVAL) -> Generation:
+        """Checks until the generation succeeded, failed or was canceled, and returns it."""
+        deadline = time.monotonic() + timeout
+        while True:
+            generation = self.get(id)
+            if generation["status"] in FINISHED:
+                return generation
+            left = deadline - time.monotonic()
+            if left <= 0:
+                raise WaitTimeoutError(id, generation["status"], timeout)
+            self._client._sleep(min(interval, left))
+
+
+class _Uploads:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def create(self, file: FileInput, *, filename: Optional[str] = None, content_type: str = "application/octet-stream") -> Upload:
+        """Upload a product photo: a path, bytes or an open file. PNG, JPEG, WebP or HEIC, up to 10 MB."""
+        content, name = _read_file(file, filename)
+        body, header = _multipart(name, content, content_type)
+        return self._client._json("POST", "/uploads", raw=body, content_type=header)
+
+
+class _Files:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def download(self, file_id: str) -> bytes:
+        """The full-quality file: a PNG or an MP4."""
+        return self._client._send("GET", f"/files/{_segment(file_id)}/content", repeatable=True)
+
+
+class _Models:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def list(self, *, source: "Optional[Literal['library', 'custom']]" = None) -> ListResponse:
+        return self._client._json("GET", "/models", query={"source": source}, repeatable=True)
+
+    def get(self, id: str) -> Model:
+        return self._client._json("GET", f"/models/{_segment(id)}", repeatable=True)
+
+    def create(self, *, idempotency_key: Optional[str] = None, **params: "Unpack[CreateModelParams]") -> Generation:
+        """Create a custom model from a description or a reference photo."""
+        return self._client._create("/models", params, idempotency_key)
+
+
+class _Locations:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def list(self, *, source: "Optional[Literal['library', 'custom']]" = None) -> ListResponse:
+        return self._client._json("GET", "/locations", query={"source": source}, repeatable=True)
+
+    def get(self, id: str) -> Location:
+        return self._client._json("GET", f"/locations/{_segment(id)}", repeatable=True)
+
+    def create(self, *, idempotency_key: Optional[str] = None, **params: "Unpack[CreateLocationParams]") -> Generation:
+        """Create a custom location from a description or a reference photo."""
+        return self._client._create("/locations", params, idempotency_key)
+
+
+class _WebhookEndpoints:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def create(self, *, url: str, events: Optional[List[WebhookEventType]] = None) -> WebhookEndpoint:
+        """The answer holds the signing secret, shown only once."""
+        body: Dict[str, Any] = {"url": url}
+        if events is not None:
+            body["events"] = events
+        return self._client._json("POST", "/webhook_endpoints", body=body)
+
+    def list(self) -> ListResponse:
+        return self._client._json("GET", "/webhook_endpoints", repeatable=True)
+
+    def delete(self, id: str) -> Deleted:
+        return self._client._json("DELETE", f"/webhook_endpoints/{_segment(id)}")
+
+    def rotate_secret(self, id: str) -> WebhookEndpoint:
+        """The answer holds the new secret, shown only once. The old one keeps signing for 24 hours."""
+        return self._client._json("POST", f"/webhook_endpoints/{_segment(id)}/rotate_secret")
+
+
+class _Usage:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def get(self, *, from_: Optional[str] = None, to: Optional[str] = None) -> Usage:
+        """Dates are YYYY-MM-DD."""
+        return self._client._json("GET", "/usage", query={"from": from_, "to": to}, repeatable=True)
+
+
+class _Account:
+    def __init__(self, client: "Fittins") -> None:
+        self._client = client
+
+    def get(self) -> Account:
+        return self._client._json("GET", "/account", repeatable=True)
+
+
+class Fittins:
+    """Client for the Fittins AI API. ``api_key`` defaults to FITTINS_API_KEY."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        key = api_key or os.environ.get("FITTINS_API_KEY")
+        if not key:
+            raise FittinsError("Missing API key. Pass api_key or set FITTINS_API_KEY. Keys are in Profile → API keys on fittins.ai.")
+        self.__api_key = key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._timeout = timeout
+        self._sleep: Callable[[float], None] = time.sleep
+
+        self.images = _Images(self)
+        self.videos = _Videos(self)
+        self.generations = _Generations(self)
+        self.uploads = _Uploads(self)
+        self.files = _Files(self)
+        self.models = _Models(self)
+        self.locations = _Locations(self)
+        self.webhook_endpoints = _WebhookEndpoints(self)
+        self.usage = _Usage(self)
+        self.account = _Account(self)
+
+    def __repr__(self) -> str:
+        return f"Fittins(base_url={self._base_url!r})"
+
+    def _create(self, path: str, params: Mapping[str, Any], idempotency_key: Optional[str]) -> Any:
+        return self._json("POST", path, body=dict(params), idempotency_key=idempotency_key or str(uuid.uuid4()), repeatable=True)
+
+    def _json(self, method: str, path: str, **call: Any) -> Any:
+        return json.loads(self._send(method, path, **call).decode("utf-8"))
+
+    def _attempt(self, request: urllib.request.Request) -> Tuple[int, Mapping[str, str], bytes]:
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                return response.status, response.headers, response.read()
+        except urllib.error.HTTPError as error:
+            with error:
+                return error.code, error.headers, error.read()
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        raw: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        repeatable: bool = False,
+    ) -> bytes:
+        url = f"{self._base_url}{path}"
+        pairs = [(name, value) for name, value in (query or {}).items() if value is not None]
+        if pairs:
+            url = f"{url}?{urllib.parse.urlencode(pairs)}"
+
+        headers = {"Authorization": f"Bearer {self.__api_key}", "User-Agent": f"fittins-python/{__version__}"}
+        data = raw
+        if body is not None:
+            data = json.dumps(body, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        elif content_type is not None:
+            headers["Content-Type"] = content_type
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                status, response_headers, content = self._attempt(request)
+            except NETWORK_ERRORS as error:
+                if repeatable and attempt < self._max_retries:
+                    self._sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise APIConnectionError(f"No answer from the Fittins API for {method} {path}.") from error
+
+            if 200 <= status < 300:
+                return content
+
+            api_error = parse_api_error(status, response_headers, content)
+            delay = _retry_delay(api_error, repeatable, attempt)
+            if delay is None or attempt >= self._max_retries:
+                raise api_error
+            self._sleep(delay)
+            attempt += 1

fittins/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

fittins/errors.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional
+
+
+class FittinsError(Exception):
+    """Base class for everything this library raises."""
+
+
+class APIError(FittinsError):
+    """The API answered with an error. Branch on ``code``; ``message`` is for people."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        type: str,
+        message: str,
+        param: Optional[str] = None,
+        request_id: Optional[str] = None,
+        doc_url: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.type = type
+        self.message = message
+        self.param = param
+        self.request_id = request_id
+        self.doc_url = doc_url
+        self.retry_after = retry_after
+
+
+class APIConnectionError(FittinsError):
+    """The request never got an answer: network failure or timeout."""
+
+
+class WaitTimeoutError(FittinsError):
+    """``generations.wait`` ran out of time. The generation may still finish."""
+
+    def __init__(self, generation_id: str, last_status: str, timeout: float) -> None:
+        super().__init__(f"Generation {generation_id} was still {last_status} after {round(timeout)} seconds.")
+        self.generation_id = generation_id
+        self.last_status = last_status
+
+
+class WebhookVerificationError(FittinsError):
+    """A webhook failed verification. Answer with a 400 and ignore it."""
+
+
+def parse_api_error(status: int, headers: Mapping[str, str], raw: bytes) -> APIError:
+    error: dict[str, Any] = {}
+    try:
+        parsed = json.loads(raw.decode("utf-8"))
+        if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict):
+            error = parsed["error"]
+    except ValueError:
+        pass  # Not JSON: a gateway answered instead of the API. Handled by the defaults below.
+
+    def text(key: str) -> Optional[str]:
+        value = error.get(key)
+        return value if isinstance(value, str) else None
+
+    retry_after: Optional[float] = None
+    header = headers.get("Retry-After")
+    if header is not None:
+        try:
+            retry_after = float(header)
+        except ValueError:
+            retry_after = None
+
+    return APIError(
+        status=status,
+        code=text("code") or "unexpected_response",
+        type=text("type") or "api_error",
+        message=text("message") or f"The API answered with HTTP {status}.",
+        param=text("param"),
+        request_id=text("request_id") or headers.get("X-Request-Id"),
+        doc_url=text("doc_url"),
+        retry_after=retry_after,
+    )

fittins/types.py

@@ -0,0 +1,332 @@
+# Generated by sdks/generate.mjs from the OpenAPI file. Do not edit: run `node sdks/generate.mjs`.
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Literal, Optional, TypedDict, Union
+
+
+GenerationStatus = Literal["queued", "running", "succeeded", "failed", "canceled"]
+
+
+GenerationType = Literal["image", "video", "model", "location"]
+
+
+ImageTier = Literal["turbo", "default", "premium", "ultra"]
+
+
+ImageQuality = Literal["1k", "2k", "4k", "8k"]
+
+
+VideoQuality = Literal["1k", "2k", "4k"]
+
+
+ImageAspectRatio = Literal["1:1", "9:16", "16:9", "3:4", "4:3", "3:2", "2:3"]
+
+
+VideoAspectRatio = Literal["1:1", "16:9", "9:16"]
+
+
+VideoDuration = Literal[5, 10]
+
+
+WebhookEventType = Literal["generation.succeeded", "generation.failed"]
+
+
+ErrorCode = Literal["invalid_request", "invalid_image", "invalid_api_key", "insufficient_credits", "spending_cap_reached", "api_not_in_plan", "not_in_plan", "custom_limit_reached", "storage_full", "not_found", "method_not_allowed", "idempotency_conflict", "generation_running", "content_flagged", "protected_content", "rate_limited", "concurrency_limit", "generation_failed", "internal_error"]
+
+
+class GenerationOutput(TypedDict, total=False):
+    file_id: str
+    url: str
+    url_expires_at: str
+    format: Literal["png", "mp4"]
+    width: Union[int, None]
+    height: Union[int, None]
+    quality: "ImageQuality"
+    title: Union[str, None]
+    alt_text: Union[str, None]
+    # Videos.
+    duration_seconds: Union[int, None]
+    # Videos.
+    has_sound: bool
+
+
+class GenerationCredits(TypedDict, total=False):
+    estimated: int
+    charged: int
+
+
+class GenerationError(TypedDict, total=False):
+    code: "ErrorCode"
+    message: str
+
+
+class Generation(TypedDict, total=False):
+    id: str
+    object: Literal["generation"]
+    type: "GenerationType"
+    status: "GenerationStatus"
+    created_at: str
+    started_at: Union[str, None]
+    completed_at: Union[str, None]
+    input: Dict[str, Any]
+    output: Union[None, "GenerationOutput"]
+    credits: "GenerationCredits"
+    project_id: Union[str, None]
+    metadata: Dict[str, str]
+    error: Union[None, "GenerationError"]
+    livemode: bool
+
+
+class ImageFromUrl(TypedDict, total=False):
+    url: str
+
+
+class ImageFromUpload(TypedDict, total=False):
+    upload_id: str
+
+
+ImageRef = Union["ImageFromUrl", "ImageFromUpload"]
+
+
+class Model(TypedDict, total=False):
+    id: str
+    object: Literal["model"]
+    source: Literal["library", "custom"]
+    name: str
+    image_url: Union[str, None]
+    created_at: Union[str, None]
+
+
+class Location(TypedDict, total=False):
+    id: str
+    object: Literal["location"]
+    source: Literal["library", "custom"]
+    name: str
+    image_url: Union[str, None]
+    created_at: Union[str, None]
+
+
+class Upload(TypedDict, total=False):
+    id: str
+    object: Literal["upload"]
+    filename: str
+    content_type: str
+    size_bytes: int
+    width: Union[int, None]
+    height: Union[int, None]
+    created_at: str
+
+
+class AccountPlan(TypedDict, total=False):
+    id: str
+    name: str
+    billing_cycle: Optional[Literal["monthly", "annual"]]
+    renews_at: Union[str, None]
+
+
+class AccountCredits(TypedDict, total=False):
+    balance: int
+    # Held by running and queued generations.
+    reserved: int
+    available: int
+
+
+class AccountFeatures(TypedDict, total=False):
+    image_tiers: List[str]
+    image_qualities: List[str]
+    video_tiers: List[str]
+    video_qualities: List[str]
+    custom_models_max: int
+    custom_locations_max: int
+
+
+class AccountLimits(TypedDict, total=False):
+    concurrent_generations: int
+    queue_max: int
+    requests_per_minute: int
+    creates_per_minute: int
+
+
+class AccountStorage(TypedDict, total=False):
+    used_bytes: int
+    limit_bytes: int
+
+
+class Account(TypedDict, total=False):
+    object: Literal["account"]
+    plan: "AccountPlan"
+    credits: "AccountCredits"
+    features: "AccountFeatures"
+    limits: "AccountLimits"
+    storage: "AccountStorage"
+
+
+class UsageTotals(TypedDict, total=False):
+    requests: int
+    generations: int
+    credits: int
+    failures: int
+
+
+class UsageKey(TypedDict, total=False):
+    name: str
+    last4: Union[str, None]
+    mode: Union[str, None]
+    requests: int
+    generations: int
+    credits: int
+    failures: int
+
+
+class UsageDay(TypedDict, total=False):
+    date: str
+    requests: int
+    generations: int
+    credits: int
+    failures: int
+    keys: List["UsageKey"]
+
+
+Usage = TypedDict("Usage", {
+    "object": Literal["usage"],
+    "from": str,
+    "to": str,
+    "totals": "UsageTotals",
+    "days": List["UsageDay"],
+}, total=False)
+
+
+class Deleted(TypedDict, total=False):
+    id: str
+    object: str
+    deleted: Literal[True]
+
+
+class WebhookEndpointLastDelivery(TypedDict, total=False):
+    at: Union[str, None]
+    status: str
+    http_status: Union[int, None]
+
+
+class WebhookEndpoint(TypedDict, total=False):
+    id: str
+    object: Literal["webhook_endpoint"]
+    url: str
+    events: List["WebhookEventType"]
+    status: Literal["enabled", "paused"]
+    livemode: bool
+    created_at: str
+    last_delivery: Union[None, "WebhookEndpointLastDelivery"]
+    # Only when created or rotated.
+    secret: str
+
+
+class WebhookEventData(TypedDict, total=False):
+    object: "Generation"
+
+
+class WebhookEvent(TypedDict, total=False):
+    id: str
+    object: Literal["event"]
+    type: "WebhookEventType"
+    created_at: str
+    livemode: bool
+    data: "WebhookEventData"
+
+
+class ErrorError(TypedDict, total=False):
+    type: Literal["invalid_request_error", "authentication_error", "credits_error", "permission_error", "not_found_error", "idempotency_error", "conflict_error", "content_error", "rate_limit_error", "generation_error", "api_error"]
+    code: "ErrorCode"
+    message: str
+    param: Union[str, None]
+    request_id: str
+    doc_url: str
+
+
+class Error(TypedDict, total=False):
+    error: "ErrorError"
+
+
+class _CreateImageParamsRequired(TypedDict):
+    # 1 to 3 photos of the product: { "url": "https://…" } or { "upload_id": "upl_…" }. Flat lays, hanger and ghost-mannequin shots and packshots all work. Different angles of one item are fine; another colour of the same item goes in a separate generation.
+    product_images: List["ImageRef"]
+    # A library model (mdl_lib_…) or one of your custom models (mdl_own_…). List them with GET /v1/models.
+    model_id: str
+    # 3 to 1500 characters: pose, framing, light, mood, setting.
+    prompt: str
+
+
+class CreateImageParams(_CreateImageParamsRequired, total=False):
+    # A library or custom location (loc_lib_…, loc_own_…). Leave it out to describe the setting in the prompt.
+    location_id: Union[str, None]
+    aspect_ratio: "ImageAspectRatio"
+    tier: "ImageTier"
+    quality: "ImageQuality"
+    # Your own references, returned unchanged: up to 20 keys (letters, digits, - or _, up to 40 characters), values up to 500 characters. metadata.sku (or reference) is shown on the result in My Generations.
+    metadata: Dict[str, str]
+
+
+class _CreateVideoParamsRequired(TypedDict):
+    # 1 to 3 photos of the product: { "url": "https://…" } or { "upload_id": "upl_…" }. Flat lays, hanger and ghost-mannequin shots and packshots all work. Different angles of one item are fine; another colour of the same item goes in a separate generation.
+    product_images: List["ImageRef"]
+    # A library model (mdl_lib_…) or one of your custom models (mdl_own_…). List them with GET /v1/models.
+    model_id: str
+    # 3 to 1500 characters: the motion and setting, for example "model walks towards the camera".
+    prompt: str
+
+
+class CreateVideoParams(_CreateVideoParamsRequired, total=False):
+    # A library or custom location (loc_lib_…, loc_own_…). Leave it out to describe the setting in the prompt.
+    location_id: Union[str, None]
+    aspect_ratio: "VideoAspectRatio"
+    duration_seconds: "VideoDuration"
+    tier: "ImageTier"
+    quality: "VideoQuality"
+    # AI sound effects (ambient and foley, not voiceover or music). 10 credits.
+    sound: bool
+    # Your own references, returned unchanged: up to 20 keys (letters, digits, - or _, up to 40 characters), values up to 500 characters. metadata.sku (or reference) is shown on the result in My Generations.
+    metadata: Dict[str, str]
+
+
+class CreateModelParams(TypedDict, total=False):
+    # 3 to 1500 characters describing the model or place. Needed unless you send reference_image.
+    description: str
+    reference_image: "ImageRef"
+    # Up to 60 characters. Without one, we name it.
+    name: str
+    # Your own references, returned unchanged: up to 20 keys (letters, digits, - or _, up to 40 characters), values up to 500 characters. metadata.sku (or reference) is shown on the result in My Generations.
+    metadata: Dict[str, str]
+
+
+class CreateLocationParams(TypedDict, total=False):
+    # 3 to 1500 characters describing the model or place. Needed unless you send reference_image.
+    description: str
+    reference_image: "ImageRef"
+    # Up to 60 characters. Without one, we name it.
+    name: str
+    # Your own references, returned unchanged: up to 20 keys (letters, digits, - or _, up to 40 characters), values up to 500 characters. metadata.sku (or reference) is shown on the result in My Generations.
+    metadata: Dict[str, str]
+
+
+class _CreateWebhookEndpointParamsRequired(TypedDict):
+    url: str
+
+
+class CreateWebhookEndpointParams(_CreateWebhookEndpointParamsRequired, total=False):
+    events: List["WebhookEventType"]
+
+
+class ListGenerationsParams(TypedDict, total=False):
+    status: "GenerationStatus"
+    type: "GenerationType"
+    limit: int
+    cursor: str
+
+
+class ListModelsParams(TypedDict, total=False):
+    source: Literal["library", "custom"]
+
+
+class ListLocationsParams(TypedDict, total=False):
+    source: Literal["library", "custom"]

fittins/webhooks.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Optional, Union
+
+from .errors import WebhookVerificationError
+from .types import WebhookEvent
+
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def verify_webhook(
+    raw_body: Union[str, bytes],
+    signature_header: Optional[str],
+    secret: str,
+    *,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> WebhookEvent:
+    """Checks a delivery's ``Fittins-Signature`` header and returns the event.
+
+    Pass the body exactly as received, before any JSON parsing. Raises
+    WebhookVerificationError when the signature or the time is wrong.
+    """
+    if isinstance(raw_body, str):
+        body = raw_body.encode("utf-8")
+    elif isinstance(raw_body, (bytes, bytearray)):
+        body = bytes(raw_body)
+    else:
+        raise WebhookVerificationError("Pass the raw request body as a string or bytes, before any JSON parsing.")
+    if not secret:
+        raise WebhookVerificationError("Missing the endpoint's signing secret.")
+    if not signature_header:
+        raise WebhookVerificationError("Missing the Fittins-Signature header.")
+
+    fields = [part.split("=", 1) if "=" in part else [part, ""] for part in signature_header.split(",")]
+    fields = [[name.strip(), value.strip()] for name, value in fields]
+    timestamp = next((value for name, value in fields if name == "t"), "")
+    signatures = [value for name, value in fields if name == "v1"]
+    if not (timestamp.isascii() and timestamp.isdigit()) or not signatures:
+        raise WebhookVerificationError("The Fittins-Signature header is not valid.")
+
+    signed = timestamp.encode("ascii") + b"." + body
+    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+    matched = False
+    for signature in signatures:
+        if hmac.compare_digest(signature.lower().encode("utf-8"), expected.encode("ascii")):
+            matched = True
+    if not matched:
+        raise WebhookVerificationError("The signature does not match. Check the secret and that the body was not changed.")
+
+    current = time.time() if now is None else now
+    if abs(current - int(timestamp)) > tolerance_seconds:
+        raise WebhookVerificationError("The delivery is too old, or this server's clock is wrong.")
+
+    try:
+        return json.loads(body.decode("utf-8"))
+    except ValueError as error:
+        raise WebhookVerificationError("The delivery is not valid JSON.") from error

fittins-1.0.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: fittins
+Version: 1.0.0
+Summary: Official Python library for the Fittins AI API: premium AI fashion photos and videos from your product photos.
+Author-email: Fittins AI <support@fittins.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://fittins.ai
+Project-URL: Documentation, https://fittins.ai/docs/api
+Project-URL: Support, https://fittins.ai/support
+Keywords: fittins,ai,fashion,on-model,virtual-try-on,product-photos,fashion-video,api,sdk
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Fittins AI for Python
+
+The official library for the [Fittins AI API](https://fittins.ai/docs/api). Fittins AI is a premium AI fashion generation service: studio-quality on-model photos up to 8K and fashion videos up to 4K, made from your product photos.
+
+The API is included in the Pro, Business and Enterprise plans and uses the same credits as the website. Create a key in **Profile → API keys** on [fittins.ai](https://fittins.ai).
+
+```bash
+pip install fittins
+```
+
+Needs Python 3.10 or later, and has no dependencies. Use it on your server: never put an API key in a web page or an app.
+
+## Create a photo
+
+```python
+from fittins import Fittins
+
+fittins = Fittins()  # reads FITTINS_API_KEY
+
+generation = fittins.images.create(
+    product_images=[{"url": "https://cdn.mystore.com/p/dress.jpg"}],
+    model_id="mdl_lib_DM5rQvl3KtlR7nqumd6I",
+    prompt="full body, soft studio light, front view",
+    aspect_ratio="3:4",
+    quality="4k",
+    metadata={"sku": "DRESS-RED-M"},
+)
+
+done = fittins.generations.wait(generation["id"])
+
+if done["status"] == "succeeded":
+    print(done["output"]["url"])  # a download link, valid for 24 hours
+else:
+    print(done["error"]["code"], done["error"]["message"])
+```
+
+## What's included
+
+| | |
+|---|---|
+| `images.create` · `videos.create` | Start a photo or a video |
+| `generations.get` · `list` · `list_all` · `wait` · `delete` | Follow, list and delete results |
+| `uploads.create` | Upload a product photo (a path, bytes or an open file) |
+| `files.download` | Get a result's bytes |
+| `models` · `locations` | `list`, `get`, and `create` a custom one |
+| `webhook_endpoints` | `create`, `list`, `delete`, `rotate_secret` |
+| `usage.get` · `account.get` | Calls and credits per day, and plan and balance |
+
+Answers are plain dictionaries, with type hints in `fittins.types`. Field names are the same as in the [API reference](https://fittins.ai/docs/api).
+
+## Retries and safe creates
+
+Failed requests are sent up to 2 more times, with a growing pause. After a 429, the library waits for the time in `Retry-After`.
+
+Each create gets an `Idempotency-Key` that its retries reuse, so a retry can't charge twice. To protect against your own job running twice, pass a key you can repeat:
+
+```python
+fittins.images.create(idempotency_key=f"photo-{sku}", **params)
+```
+
+Uploads, webhook endpoint changes and deletes are only retried after a 429, because sending them twice could do the work twice.
+
+Set your own limits with `Fittins(max_retries=4, timeout=60.0)`.
+
+## Errors
+
+```python
+from fittins import APIError
+
+try:
+    fittins.images.create(**params)
+except APIError as error:
+    if error.code == "insufficient_credits":
+        ...  # error.status, error.code, error.message, error.param, error.request_id
+    else:
+        raise
+```
+
+`APIConnectionError` means no answer arrived. `WaitTimeoutError` means `generations.wait` ran out of time; the generation may still finish. A generation that fails after being accepted isn't raised: check `status` and `error`.
+
+## Webhooks
+
+```python
+import os
+
+from flask import Flask, request
+from fittins import WebhookVerificationError, verify_webhook
+
+app = Flask(__name__)
+
+@app.post("/webhooks/fittins")
+def fittins_webhook():
+    try:
+        event = verify_webhook(
+            request.get_data(),
+            request.headers.get("Fittins-Signature"),
+            os.environ["FITTINS_WEBHOOK_SECRET"],
+        )
+    except WebhookVerificationError:
+        return "", 400
+    if event["type"] == "generation.succeeded":
+        print(event["data"]["object"]["output"]["url"])
+    return "", 200
+```
+
+Pass the body exactly as received, before any JSON parsing.
+
+## Testing without credits
+
+Keys that start with `fit_test_` run the checks on your request and return a sample result, without using the AI or any credits.
+
+## More
+
+[API documentation](https://fittins.ai/docs/api) · [Support](https://fittins.ai/support)

fittins-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+fittins/__init__.py,sha256=D9cSQiBgpkAH9yIgD0_CdAXA_S60Eb3wCEa7zMPFNeo,484
+fittins/_client.py,sha256=0DE3lNMyFtcc05I1EUR8CLoN2fmMXzlxTs6dpwgu8Tk,13555
+fittins/_version.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+fittins/errors.py,sha256=6Tzc9WaZZL0hzijz2uDW-bnfaX6ikA60oUBlREpGCPc,2665
+fittins/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fittins/types.py,sha256=6DjS20bsth8_2dPcVhcExL1Drx0PJRMUkxcoO3zHAhk,9759
+fittins/webhooks.py,sha256=pogoucU2bAyOAJlYqRq6lBXQneUh3XbCBxAdOqCGuQk,2495
+fittins-1.0.0.dist-info/licenses/LICENSE,sha256=X572e2sNZA9cP1R0bomRhHQINYjn9nDUIo9z-aHI-bg,1067
+fittins-1.0.0.dist-info/METADATA,sha256=bFo7Usjci1rPRX1_sftfWq11g97VZmWzIvhDg4_yS2I,4628
+fittins-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+fittins-1.0.0.dist-info/top_level.txt,sha256=sTyUqSDpFpCyzKK9_ARezR8uxnJEB1TVjpcwAq5tjG4,8
+fittins-1.0.0.dist-info/RECORD,,

fittins-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fittins-1.0.0.dist-info/licenses/LICENSE

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

fittins-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fittins