imagepipeline 0.3.0__py3-none-any.whl

imagepipeline/__init__.py

@@ -0,0 +1,7 @@
+"""ImagePipeline Python SDK"""
+
+from .client import ImagePipeline
+from .models import Job, JobStatus, SegmentItem, SegmentResult, UploadResult
+
+__all__ = ["ImagePipeline", "Job", "JobStatus", "UploadResult", "SegmentItem", "SegmentResult"]
+__version__ = "0.3.0"

imagepipeline/_transport.py

@@ -0,0 +1,114 @@
+"""Low-level HTTP transport shared by all resource classes."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, IO, Optional
+
+import requests as _requests
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    JobFailedError,
+    JobTimeoutError,
+    RateLimitError,
+)
+from .models import Job, JobStatus
+
+_DEFAULT_BASE_URL = "https://api.imagepipeline.io"
+_DEFAULT_POLL_INTERVAL = 3  # seconds
+_DEFAULT_TIMEOUT = 300  # seconds
+_SDK_VERSION = "0.3.0"
+
+
+class _Transport:
+    """Wraps requests.Session with auth headers and error handling."""
+
+    def __init__(self, api_key: str, base_url: str, timeout: int):
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = _requests.Session()
+        self._session.headers.update({
+            "X-API-Key": api_key,
+            "Content-Type": "application/json",
+            "User-Agent": f"imagepipeline-python/{_SDK_VERSION}",
+        })
+
+    def post(self, path: str, body: dict) -> dict:
+        url = f"{self._base_url}{path}"
+        resp = self._session.post(url, json=body, timeout=self._timeout)
+        return self._handle(resp)
+
+    def get(self, path: str) -> dict:
+        url = f"{self._base_url}{path}"
+        resp = self._session.get(url, timeout=self._timeout)
+        return self._handle(resp)
+
+    def post_file(self, path: str, file_obj: IO[bytes], filename: str, content_type: str) -> dict:
+        """POST multipart/form-data — used by the upload endpoint."""
+        url = f"{self._base_url}{path}"
+        # Remove Content-Type so requests sets multipart boundary automatically
+        headers = {k: v for k, v in self._session.headers.items() if k.lower() != "content-type"}
+        resp = self._session.post(
+            url,
+            files={"file": (filename, file_obj, content_type)},
+            headers=headers,
+            timeout=self._timeout,
+        )
+        return self._handle(resp)
+
+    def _handle(self, resp: _requests.Response) -> dict:
+        if resp.status_code == 401:
+            raise AuthenticationError("Invalid or missing API key.")
+        if resp.status_code == 429:
+            retry_after = int(resp.headers.get("Retry-After", 60))
+            raise RateLimitError("Rate limit exceeded.", retry_after=retry_after)
+        if resp.status_code == 204:
+            return {}
+        if not resp.ok:
+            try:
+                detail = resp.json().get("detail") or resp.text
+            except Exception:
+                detail = resp.text
+            raise APIError(resp.status_code, detail)
+        return resp.json()
+
+    def submit_and_poll(
+        self,
+        endpoint: str,
+        body: dict,
+        poll_interval: int = _DEFAULT_POLL_INTERVAL,
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> Job:
+        """POST to endpoint, then poll /status/{job_id} until done."""
+        data = self.post(f"/{endpoint}", body)
+        job_id = data["job_id"]
+        return self.poll(endpoint, job_id, poll_interval=poll_interval, timeout=timeout)
+
+    def submit(self, endpoint: str, body: dict) -> Job:
+        """POST to endpoint and return immediately without polling."""
+        data = self.post(f"/{endpoint}", body)
+        return Job(
+            job_id=data["job_id"],
+            status=JobStatus(data.get("status", "queued")),
+            endpoint=endpoint,
+        )
+
+    def poll(
+        self,
+        endpoint: str,
+        job_id: str,
+        poll_interval: int = _DEFAULT_POLL_INTERVAL,
+        timeout: int = _DEFAULT_TIMEOUT,
+    ) -> Job:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            data = self.get(f"/{endpoint}/status/{job_id}")
+            status = JobStatus(data.get("status", "queued"))
+            if status == JobStatus.COMPLETED:
+                return Job._from_status_response(data, endpoint)
+            if status == JobStatus.FAILED:
+                raise JobFailedError(job_id, data.get("error"))
+            time.sleep(poll_interval)
+        raise JobTimeoutError(job_id, timeout)

imagepipeline/client.py

@@ -0,0 +1,88 @@
+"""Top-level ImagePipeline client."""
+
+from __future__ import annotations
+
+from ._transport import _Transport
+from .resources import (
+    BackgroundResource,
+    BrandingResource,
+    EditResource,
+    GenerateResource,
+    IdentityResource,
+    SegmentResource,
+    UploadResource,
+    UpscaleResource,
+)
+
+_DEFAULT_BASE_URL = "https://api.imagepipeline.io"
+
+
+class ImagePipeline:
+    """Client for the ImagePipeline API.
+
+    Usage::
+
+        from imagepipeline import ImagePipeline
+
+        ip = ImagePipeline("ip_live_xxxxxxxxxxxx")
+
+        # Generate an image
+        result = ip.generate.image(prompt="sunset over tokyo", width=1024, height=1024)
+        print(result.url)
+
+        # Upload a local file, then edit it
+        upload = ip.upload.image("product.png")
+        job = ip.edit.image(
+            input_image=[person_url, upload.url],
+            prompt="dress the person in the product from image 2",
+            mask_segment="upper-clothes",
+        )
+
+        # Virtual try-on
+        result = ip.identity.tryon(
+            person_image="https://.../person.jpg",
+            clothing_image="https://.../shirt.jpg",
+            gender="woman",
+        )
+
+        # Segment an image to find label names
+        seg = ip.segment.image("https://.../person.jpg")
+        print(seg.segments)   # [SegmentItem(label='upper-clothes', display='Top / Shirt'), ...]
+
+        # Background change (subject is automatically preserved)
+        result = ip.background.change(
+            input_image="https://.../photo.jpg",
+            prompt="tropical beach at sunset",
+        )
+
+        # Manage identity profiles
+        profile = ip.identity.create_profile(
+            name="Brand Model",
+            prompt_template="{{ user_prompt }}, Caucasian woman, 20s, blue eyes",
+            seed_strategy="fixed",
+            fixed_seed=42,
+        )
+        print(profile["profile_id"])
+
+    Args:
+        api_key: Your API key (starts with ``ip_live_``).
+        base_url: Override the API base URL (useful for staging environments).
+        timeout: HTTP request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = 30,
+    ):
+        self._transport = _Transport(api_key=api_key, base_url=base_url, timeout=timeout)
+
+        self.generate = GenerateResource(self._transport)
+        self.identity = IdentityResource(self._transport)
+        self.edit = EditResource(self._transport)
+        self.background = BackgroundResource(self._transport)
+        self.branding = BrandingResource(self._transport)
+        self.upscale = UpscaleResource(self._transport)
+        self.upload = UploadResource(self._transport)
+        self.segment = SegmentResource(self._transport)

imagepipeline/exceptions.py

@@ -0,0 +1,45 @@
+"""Exceptions raised by the ImagePipeline SDK."""
+
+from __future__ import annotations
+
+
+class ImagePipelineError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class AuthenticationError(ImagePipelineError):
+    """API key is missing or invalid (401)."""
+
+
+class RateLimitError(ImagePipelineError):
+    """Rate limit exceeded (429). Retry after the indicated delay."""
+
+    def __init__(self, message: str, retry_after: int = 60):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class JobFailedError(ImagePipelineError):
+    """The submitted job completed with status 'failed'."""
+
+    def __init__(self, job_id: str, reason: str | None = None):
+        super().__init__(f"Job {job_id} failed: {reason or 'unknown error'}")
+        self.job_id = job_id
+        self.reason = reason
+
+
+class JobTimeoutError(ImagePipelineError):
+    """Polling timed out before the job completed."""
+
+    def __init__(self, job_id: str, timeout: int):
+        super().__init__(f"Job {job_id} did not complete within {timeout}s")
+        self.job_id = job_id
+        self.timeout = timeout
+
+
+class APIError(ImagePipelineError):
+    """Unexpected HTTP error from the API."""
+
+    def __init__(self, status_code: int, message: str):
+        super().__init__(f"HTTP {status_code}: {message}")
+        self.status_code = status_code

imagepipeline/models.py

@@ -0,0 +1,111 @@
+"""Core data models for the ImagePipeline SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class JobStatus(str, Enum):
+    QUEUED = "queued"
+    PENDING = "pending"
+    PROCESSING = "processing"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+@dataclass
+class Job:
+    """Represents a submitted or completed job."""
+
+    job_id: str
+    status: JobStatus
+    endpoint: str
+    result_url: Optional[str] = None
+    error: Optional[str] = None
+
+    # Progress
+    progress: Optional[int] = None
+    result_mime_type: Optional[str] = None
+
+    # Timing
+    queue_wait_seconds: Optional[float] = None
+    inference_time_seconds: Optional[float] = None
+    total_elapsed_seconds: Optional[float] = None
+    estimated_time_seconds: Optional[int] = None
+    processing_time_seconds: Optional[float] = None
+
+    # Queue position (enterprise plans)
+    queue_position: Optional[int] = None
+    queue_metrics: Optional[Dict[str, Any]] = None
+    queue_metrics_hint: Optional[str] = None
+
+    # Failure info
+    failure_reason_code: Optional[str] = None
+    retryable: Optional[bool] = None
+    warnings: Optional[List[str]] = None
+    prompt_hash: Optional[str] = None
+
+    # Billing
+    cost_usd: Optional[float] = None
+    balance_remaining_usd: Optional[float] = None
+
+    # Background removal specific
+    cutout_url: Optional[str] = None
+
+    @property
+    def url(self) -> Optional[str]:
+        """Alias for result_url."""
+        return self.result_url
+
+    @classmethod
+    def _from_status_response(cls, data: dict, endpoint: str) -> "Job":
+        return cls(
+            job_id=data.get("job_id", ""),
+            status=JobStatus(data.get("status", "queued")),
+            endpoint=endpoint,
+            result_url=data.get("result_url"),
+            error=data.get("error"),
+            progress=data.get("progress"),
+            result_mime_type=data.get("result_mime_type"),
+            queue_wait_seconds=data.get("queue_wait_seconds"),
+            inference_time_seconds=data.get("inference_time_seconds"),
+            total_elapsed_seconds=data.get("total_elapsed_seconds"),
+            estimated_time_seconds=data.get("estimated_time_seconds"),
+            processing_time_seconds=data.get("processing_time_seconds"),
+            queue_position=data.get("queue_position"),
+            queue_metrics=data.get("queue_metrics"),
+            queue_metrics_hint=data.get("queue_metrics_hint"),
+            failure_reason_code=data.get("failure_reason_code"),
+            retryable=data.get("retryable"),
+            warnings=data.get("warnings"),
+            prompt_hash=data.get("prompt_hash"),
+            cost_usd=data.get("cost_usd"),
+            balance_remaining_usd=data.get("balance_remaining_usd"),
+            cutout_url=data.get("cutout_url"),
+        )
+
+
+@dataclass
+class UploadResult:
+    """Result of a file upload."""
+    url: str
+    filename: str
+    content_type: str
+    size_bytes: int
+
+
+@dataclass
+class SegmentItem:
+    """A single detected segment from segmentation."""
+    label: str
+    display: str
+
+
+@dataclass
+class SegmentResult:
+    """Result of image segmentation."""
+    preview_url: str
+    segments: List[SegmentItem]

imagepipeline/resources/__init__.py

@@ -0,0 +1,23 @@
+"""Resource sub-package init."""
+
+from .generate import GenerateResource
+from .identity import IdentityResource
+from .misc import (
+    BackgroundResource,
+    BrandingResource,
+    EditResource,
+    SegmentResource,
+    UploadResource,
+    UpscaleResource,
+)
+
+__all__ = [
+    "GenerateResource",
+    "IdentityResource",
+    "EditResource",
+    "BackgroundResource",
+    "BrandingResource",
+    "UpscaleResource",
+    "UploadResource",
+    "SegmentResource",
+]

imagepipeline/resources/generate.py

@@ -0,0 +1,179 @@
+"""Generate namespace: image, video, speech, 3d."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .._transport import _Transport
+from ..models import Job
+
+
+class GenerateResource:
+    def __init__(self, transport: _Transport):
+        self._t = transport
+
+    def image(
+        self,
+        *,
+        prompt: str,
+        width: int = 1024,
+        height: int = 1024,
+        seed: int = -1,
+        output_format: str = "webp",
+        num_inference_steps: Optional[int] = None,
+        guidance_scale: Optional[float] = None,
+        enhance_prompt: bool = False,
+        logo_url: Optional[str] = None,
+        profile_id: Optional[str] = None,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+    ) -> Job:
+        """Generate an image from a text prompt using Z-Image Turbo.
+
+        Args:
+            prompt: Text description of the image to generate.
+            width: Output width in pixels (max 1024).
+            height: Output height in pixels (max 1024).
+            seed: Reproducibility seed (-1 for random).
+            output_format: ``'webp'`` (default), ``'jpeg'``, or ``'png'``.
+            num_inference_steps: Diffusion steps (default 8). Higher = slower but sharper.
+            guidance_scale: CFG scale. Leave unset to use the model default (0.0 for Z-Image Turbo).
+            enhance_prompt: Run the prompt through a lightweight AI enhancer before generation.
+                            Expands terse prompts into detailed visual descriptions. Adds ~1–2 s.
+            logo_url: Public URL of your company logo (PNG/WebP). Stamped at bottom-right at 50% opacity.
+            profile_id: Identity profile ID — applies the profile's prompt template and quality settings.
+            callback_url: Webhook URL. We POST a ``WebhookEvent`` on completion.
+            wait: If True (default), poll until complete and return a finished Job.
+                  If False, return immediately with a QUEUED Job.
+        """
+        body: dict = {
+            "prompt": prompt,
+            "width": width,
+            "height": height,
+            "seed": seed,
+            "output_format": output_format,
+            "enhance_prompt": enhance_prompt,
+        }
+        if num_inference_steps is not None:
+            body["num_inference_steps"] = num_inference_steps
+        if guidance_scale is not None:
+            body["guidance_scale"] = guidance_scale
+        if logo_url:
+            body["logo_url"] = logo_url
+        if profile_id:
+            body["profile_id"] = profile_id
+        if callback_url:
+            body["callback_url"] = callback_url
+        endpoint = "generate/image/v1"
+        return self._t.submit_and_poll(endpoint, body) if wait else self._t.submit(endpoint, body)
+
+    def video(
+        self,
+        *,
+        input_image: str,
+        prompt: str = "make this image come alive, cinematic motion, smooth animation",
+        width: int = 896,
+        height: int = 512,
+        duration_seconds: float = 2.0,
+        seed: int = 42,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+    ) -> Job:
+        """Generate a short video from an input image (image-to-video).
+
+        Args:
+            input_image: Public URL of the image to animate.
+            prompt: Animation style description.
+            width: Output width in pixels (max 1536, divisible by 32).
+            height: Output height in pixels (max 1536, divisible by 32).
+            duration_seconds: Video length in seconds (0.1–10.0).
+            seed: Reproducibility seed.
+            callback_url: Webhook URL. We POST a ``WebhookEvent`` on completion.
+            wait: Poll until complete if True.
+        """
+        body: dict = {
+            "input_image": input_image,
+            "prompt": prompt,
+            "width": width,
+            "height": height,
+            "duration_seconds": duration_seconds,
+            "seed": seed,
+        }
+        if callback_url:
+            body["callback_url"] = callback_url
+        endpoint = "generate/video/v1"
+        return self._t.submit_and_poll(endpoint, body) if wait else self._t.submit(endpoint, body)
+
+    def speech(
+        self,
+        *,
+        text: str,
+        language_id: str = "en",
+        target_voice_path: Optional[str] = None,
+        max_new_tokens: int = 256,
+        exaggeration: float = 0.5,
+        apply_watermark: bool = True,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+    ) -> Job:
+        """Convert text to speech.
+
+        Args:
+            text: Text to synthesise (max 5000 chars).
+            language_id: Language code e.g. ``'en'``, ``'es'``, ``'fr'``.
+            target_voice_path: URL of a reference voice sample for voice cloning.
+            max_new_tokens: Maximum tokens to generate (max 1024).
+            exaggeration: Voice expressiveness (0.0–1.0).
+            apply_watermark: Apply audio watermark.
+            callback_url: Webhook URL. We POST a ``WebhookEvent`` on completion.
+            wait: Poll until complete if True.
+        """
+        body: dict = {
+            "text": text,
+            "language_id": language_id,
+            "max_new_tokens": max_new_tokens,
+            "exaggeration": exaggeration,
+            "apply_watermark": apply_watermark,
+        }
+        if target_voice_path:
+            body["target_voice_path"] = target_voice_path
+        if callback_url:
+            body["callback_url"] = callback_url
+        endpoint = "generate/speech/v1"
+        return self._t.submit_and_poll(endpoint, body) if wait else self._t.submit(endpoint, body)
+
+    def generate_3d(
+        self,
+        *,
+        image_path: str,
+        mode: str = "generate_and_paint",
+        mesh_save_name: Optional[str] = None,
+        painted_save_name: Optional[str] = None,
+        auto_unload: bool = True,
+        callback_url: Optional[str] = None,
+        wait: bool = True,
+    ) -> Job:
+        """Convert an image to a 3D mesh (Pro plan required).
+
+        Args:
+            image_path: Public URL of the image to convert.
+            mode: ``'generate'`` | ``'paint'`` | ``'generate_and_paint'``.
+            mesh_save_name: Optional filename for the output mesh.
+            painted_save_name: Optional filename for the textured mesh.
+            auto_unload: Unload model from GPU after generation.
+            callback_url: Webhook URL. We POST a ``WebhookEvent`` on completion.
+            wait: Poll until complete if True.
+        """
+        body: dict = {
+            "image_path": image_path,
+            "mode": mode,
+            "auto_unload": auto_unload,
+        }
+        if mesh_save_name:
+            body["mesh_save_name"] = mesh_save_name
+        if painted_save_name:
+            body["painted_save_name"] = painted_save_name
+        if callback_url:
+            body["callback_url"] = callback_url
+        endpoint = "generate/3d/v1"
+        return self._t.submit_and_poll(endpoint, body) if wait else self._t.submit(endpoint, body)