fotor-sdk 0.1.0__py3-none-any.whl

fotor_sdk/__init__.py

@@ -0,0 +1,34 @@
+"""Fotor OpenAPI SDK -- lightweight, standalone, async-first."""
+
+__version__ = "0.1.0"
+
+from .client import FotorClient, FotorAPIError
+from .models import TaskResult, TaskSpec, TaskStatus
+from .runner import TaskRunner
+from .tasks import (
+    text2image,
+    image2image,
+    image_upscale,
+    background_remove,
+    text2video,
+    single_image2video,
+    start_end_frame2video,
+    multiple_image2video,
+)
+
+__all__ = [
+    "FotorClient",
+    "FotorAPIError",
+    "TaskResult",
+    "TaskSpec",
+    "TaskStatus",
+    "TaskRunner",
+    "text2image",
+    "image2image",
+    "image_upscale",
+    "background_remove",
+    "text2video",
+    "single_image2video",
+    "start_end_frame2video",
+    "multiple_image2video",
+]

fotor_sdk/client.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Callable
+
+import aiohttp
+
+from .models import TaskResult, TaskStatus
+
+logger = logging.getLogger("fotor_sdk")
+
+_OK_CODE = "000"
+_TASK_STATUS_PATH = "/v1/aiart/tasks"
+
+_DEFAULT_ENDPOINT = "https://api.fotor.com"
+_DEFAULT_POLL_INTERVAL = 2.0
+_DEFAULT_MAX_POLL_SECONDS = 1200
+
+
+class FotorAPIError(Exception):
+    """Raised when the Fotor API returns an error response."""
+
+    def __init__(self, message: str, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+
+class FotorClient:
+    """Lightweight async client for the Fotor OpenAPI.
+
+    Only requires an API key; no S3, no credit checks, no model config.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        endpoint: str = _DEFAULT_ENDPOINT,
+        poll_interval: float = _DEFAULT_POLL_INTERVAL,
+        max_poll_seconds: float = _DEFAULT_MAX_POLL_SECONDS,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._endpoint = endpoint.rstrip("/")
+        self._poll_interval = poll_interval
+        self._max_poll_seconds = max_poll_seconds
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {self._api_key}",
+        }
+
+    # ------------------------------------------------------------------
+    # Core async methods
+    # ------------------------------------------------------------------
+
+    async def create_task(self, path: str, payload: dict[str, Any]) -> str:
+        """Submit a task and return the ``task_id``."""
+        url = f"{self._endpoint}{path}"
+        logger.debug("POST %s  payload=%s", url, payload)
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url,
+                headers=self._headers(),
+                json=payload,
+                timeout=aiohttp.ClientTimeout(total=30),
+            ) as resp:
+                if resp.status != 200:
+                    body = await resp.text()
+                    raise FotorAPIError(
+                        f"HTTP {resp.status} from {url}: {body}", code=str(resp.status)
+                    )
+                data = await resp.json()
+
+        if data.get("code") != _OK_CODE:
+            raise FotorAPIError(data.get("msg", "unknown error"), code=data.get("code"))
+
+        task_id = data.get("data", {}).get("taskId")
+        if not task_id:
+            raise FotorAPIError("API response missing data.taskId")
+        logger.info("Task created: %s", task_id)
+        return task_id
+
+    async def get_task_status(self, task_id: str) -> TaskResult:
+        """Query current status of *task_id* and return a ``TaskResult``."""
+        url = f"{self._endpoint}{_TASK_STATUS_PATH}/{task_id}"
+        logger.debug("GET %s", url)
+
+        async with aiohttp.ClientSession() as session:
+            async with session.get(
+                url,
+                headers=self._headers(),
+                timeout=aiohttp.ClientTimeout(total=15),
+            ) as resp:
+                if resp.status != 200:
+                    return TaskResult(task_id=task_id, status=TaskStatus.FAILED,
+                                     error=f"HTTP {resp.status}")
+                data = await resp.json()
+
+        if data.get("code") != _OK_CODE:
+            return TaskResult(task_id=task_id, status=TaskStatus.FAILED,
+                              error=data.get("msg", "bad code"))
+
+        task_data = data.get("data", {})
+        api_status = task_data.get("status", -1)
+
+        if api_status == TaskStatus.COMPLETED:
+            return TaskResult(
+                task_id=task_id,
+                status=TaskStatus.COMPLETED,
+                result_url=task_data.get("resultUrl"),
+            )
+        if api_status == TaskStatus.FAILED:
+            error_msg = "NSFW_CONTENT" if task_data.get("hasHsfw") else task_data.get("msg", "task failed")
+            return TaskResult(task_id=task_id, status=TaskStatus.FAILED, error=error_msg)
+        return TaskResult(task_id=task_id, status=TaskStatus.IN_PROGRESS)
+
+    async def wait_for_task(
+        self,
+        task_id: str,
+        on_poll: Callable[[TaskResult], None] | None = None,
+    ) -> TaskResult:
+        """Poll *task_id* until it completes, fails, or times out.
+
+        *on_poll* is invoked after every poll cycle with the latest
+        ``TaskResult`` so callers can implement progress UIs.
+        """
+        start = time.monotonic()
+        while True:
+            result = await self.get_task_status(task_id)
+            result.elapsed_seconds = time.monotonic() - start
+
+            if on_poll is not None:
+                on_poll(result)
+
+            if result.status in (TaskStatus.COMPLETED, TaskStatus.FAILED):
+                return result
+
+            if result.elapsed_seconds >= self._max_poll_seconds:
+                result.status = TaskStatus.TIMEOUT
+                result.error = f"polling timed out after {self._max_poll_seconds}s"
+                return result
+
+            await asyncio.sleep(self._poll_interval)
+
+    async def submit_and_wait(
+        self,
+        path: str,
+        payload: dict[str, Any],
+        on_poll: Callable[[TaskResult], None] | None = None,
+    ) -> TaskResult:
+        """Convenience: create a task then poll until done."""
+        start = time.monotonic()
+        task_id = await self.create_task(path, payload)
+        result = await self.wait_for_task(task_id, on_poll=on_poll)
+        result.elapsed_seconds = time.monotonic() - start
+        return result
+
+    # ------------------------------------------------------------------
+    # Sync wrappers
+    # ------------------------------------------------------------------
+
+    def create_task_sync(self, path: str, payload: dict[str, Any]) -> str:
+        return asyncio.run(self.create_task(path, payload))
+
+    def wait_for_task_sync(self, task_id: str) -> TaskResult:
+        return asyncio.run(self.wait_for_task(task_id))
+
+    def submit_and_wait_sync(self, path: str, payload: dict[str, Any]) -> TaskResult:
+        return asyncio.run(self.submit_and_wait(path, payload))

fotor_sdk/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any
+
+
+class TaskStatus(IntEnum):
+    UNKNOWN = -1
+    IN_PROGRESS = 0
+    COMPLETED = 1
+    FAILED = 2
+    TIMEOUT = 3
+    CANCELLED = 4
+
+
+@dataclass
+class TaskResult:
+    task_id: str
+    status: TaskStatus = TaskStatus.UNKNOWN
+    result_url: str | None = None
+    error: str | None = None
+    elapsed_seconds: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def success(self) -> bool:
+        return self.status == TaskStatus.COMPLETED and self.result_url is not None
+
+    def __repr__(self) -> str:
+        status_name = self.status.name
+        if self.success:
+            return f"TaskResult(task_id={self.task_id!r}, status={status_name}, url={self.result_url!r})"
+        return f"TaskResult(task_id={self.task_id!r}, status={status_name}, error={self.error!r})"
+
+
+@dataclass
+class TaskSpec:
+    """Describes a single task to be submitted to the runner."""
+    task_type: str
+    params: dict[str, Any] = field(default_factory=dict)
+    tag: str = ""

fotor_sdk/runner.py

@@ -0,0 +1,159 @@
+"""Parallel task runner with concurrency control and status monitoring."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Callable
+
+from .client import FotorClient
+from .models import TaskResult, TaskSpec, TaskStatus
+from . import tasks as _tasks
+
+logger = logging.getLogger("fotor_sdk")
+
+# Map task_type strings to the async functions in tasks.py
+_TASK_DISPATCH: dict[str, Callable[..., Any]] = {
+    "text2image": _tasks.text2image,
+    "image2image": _tasks.image2image,
+    "image_upscale": _tasks.image_upscale,
+    "background_remove": _tasks.background_remove,
+    "text2video": _tasks.text2video,
+    "single_image2video": _tasks.single_image2video,
+    "start_end_frame2video": _tasks.start_end_frame2video,
+    "multiple_image2video": _tasks.multiple_image2video,
+}
+
+
+class _ProgressTracker:
+    """Thread-safe progress state shared across concurrent tasks."""
+
+    def __init__(self, total: int, on_progress: Callable[..., None] | None):
+        self.total = total
+        self.completed = 0
+        self.failed = 0
+        self.in_progress = total
+        self._on_progress = on_progress
+        self._lock = asyncio.Lock()
+
+    async def mark_done(self, result: TaskResult) -> None:
+        async with self._lock:
+            self.in_progress -= 1
+            if result.status == TaskStatus.COMPLETED:
+                self.completed += 1
+            else:
+                self.failed += 1
+            if self._on_progress:
+                self._on_progress(
+                    total=self.total,
+                    completed=self.completed,
+                    failed=self.failed,
+                    in_progress=self.in_progress,
+                    latest=result,
+                )
+
+    def summary(self) -> dict[str, int]:
+        return {
+            "total": self.total,
+            "completed": self.completed,
+            "failed": self.failed,
+        }
+
+
+class TaskRunner:
+    """Execute many Fotor tasks in parallel with bounded concurrency.
+
+    Usage::
+
+        client = FotorClient(api_key="...")
+        runner = TaskRunner(client, max_concurrent=5)
+
+        specs = [
+            TaskSpec("text2image", {"prompt": "A cat", "model_id": "seedream-4-5-251128"}),
+            TaskSpec("text2video", {"prompt": "Ocean", "model_id": "kling-v3", "duration": 5}),
+        ]
+        results = await runner.run(specs, on_progress=print)
+    """
+
+    def __init__(self, client: FotorClient, max_concurrent: int = 5):
+        self._client = client
+        self._semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def _execute_one(
+        self,
+        spec: TaskSpec,
+        tracker: _ProgressTracker,
+        on_task_poll: Callable[[TaskResult], None] | None,
+    ) -> TaskResult:
+        fn = _TASK_DISPATCH.get(spec.task_type)
+        if fn is None:
+            result = TaskResult(
+                task_id="",
+                status=TaskStatus.FAILED,
+                error=f"Unknown task_type: {spec.task_type!r}. "
+                      f"Available: {list(_TASK_DISPATCH)}",
+            )
+            await tracker.mark_done(result)
+            return result
+
+        async with self._semaphore:
+            start = time.monotonic()
+            try:
+                result = await fn(self._client, on_poll=on_task_poll, **spec.params)
+                result.metadata["tag"] = spec.tag
+            except Exception as exc:
+                result = TaskResult(
+                    task_id="",
+                    status=TaskStatus.FAILED,
+                    error=str(exc),
+                    elapsed_seconds=time.monotonic() - start,
+                    metadata={"tag": spec.tag},
+                )
+            await tracker.mark_done(result)
+            return result
+
+    async def run(
+        self,
+        specs: list[TaskSpec],
+        on_progress: Callable[..., None] | None = None,
+        on_task_poll: Callable[[TaskResult], None] | None = None,
+    ) -> list[TaskResult]:
+        """Run all *specs* in parallel (up to ``max_concurrent``).
+
+        Parameters
+        ----------
+        specs:
+            List of :class:`TaskSpec` describing what to execute.
+        on_progress:
+            Called after each task finishes with keyword args
+            ``total``, ``completed``, ``failed``, ``in_progress``, ``latest``.
+        on_task_poll:
+            Called during polling of each individual task (per-poll-cycle).
+
+        Returns
+        -------
+        list[TaskResult]
+            Results in the same order as *specs*.
+        """
+        if not specs:
+            return []
+
+        tracker = _ProgressTracker(len(specs), on_progress)
+        coros = [self._execute_one(spec, tracker, on_task_poll) for spec in specs]
+        results = await asyncio.gather(*coros, return_exceptions=False)
+
+        summary = tracker.summary()
+        logger.info(
+            "Batch complete: %d/%d succeeded, %d failed",
+            summary["completed"], summary["total"], summary["failed"],
+        )
+        return list(results)
+
+    def run_sync(
+        self,
+        specs: list[TaskSpec],
+        on_progress: Callable[..., None] | None = None,
+    ) -> list[TaskResult]:
+        """Synchronous wrapper around :meth:`run`."""
+        return asyncio.run(self.run(specs, on_progress=on_progress))

fotor_sdk/tasks.py

@@ -0,0 +1,248 @@
+"""High-level task helpers that build payloads and call :class:`FotorClient`.
+
+Each function accepts plain Python arguments (no Pydantic models required),
+constructs the correct API payload, submits the task, and polls until done.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .client import FotorClient
+from .models import TaskResult
+
+# ---------------------------------------------------------------------------
+# API path constants (mirrors openapi/urls.py)
+# ---------------------------------------------------------------------------
+_IMAGE_GENERATION = "/v1/aiart/imagegeneration"
+_IMG_UPSCALER = "/v1/aiart/imgupscale"
+_BG_REMOVER = "/v1/aiart/backgroundremover"
+_TXT2VIDEO = "/v1/aiart/text2video"
+_IMG2VIDEO = "/v1/aiart/img2video"
+_STARTEND2VIDEO = "/v1/aiart/startend2video"
+_CHARACTER2VIDEO = "/v1/aiart/character2video"
+
+# Default image sizes per aspect ratio.
+# The API requires at least 3,686,400 total pixels (1920×1920 for 1:1).
+_DEFAULT_SIZES: dict[str, tuple[int, int]] = {
+    "1:1": (1920, 1920),
+    "16:9": (2560, 1440),
+    "9:16": (1440, 2560),
+    "4:3": (2240, 1680),
+    "3:4": (1680, 2240),
+    "3:2": (2400, 1600),
+    "2:3": (1600, 2400),
+    "21:9": (2940, 1260),
+}
+
+
+def _resolve_size(
+    aspect_ratio: str, resolution: str
+) -> tuple[int, int]:
+    w, h = _DEFAULT_SIZES.get(aspect_ratio, (1920, 1920))
+    if resolution == "2k":
+        w, h = w * 2, h * 2
+    elif resolution == "4k":
+        w, h = w * 4, h * 4
+    return w, h
+
+
+# ---------------------------------------------------------------------------
+# Image tasks
+# ---------------------------------------------------------------------------
+
+async def text2image(
+    client: FotorClient,
+    *,
+    prompt: str,
+    model_id: str,
+    aspect_ratio: str = "auto",
+    resolution: str = "auto",
+    on_poll: Callable[[TaskResult], None] | None = None,
+    **extra: Any,
+) -> TaskResult:
+    """Generate an image from a text prompt."""
+    w, h = _resolve_size(aspect_ratio, resolution)
+    payload: dict[str, Any] = {
+        "width": w,
+        "height": h,
+        "content": [{"type": "text", "text": prompt}],
+        "quality": "medium",
+        **extra,
+    }
+    path = f"{_IMAGE_GENERATION}/{model_id}"
+    return await client.submit_and_wait(path, payload, on_poll=on_poll)
+
+
+async def image2image(
+    client: FotorClient,
+    *,
+    prompt: str,
+    model_id: str,
+    image_urls: list[str],
+    aspect_ratio: str = "auto",
+    resolution: str = "auto",
+    on_poll: Callable[[TaskResult], None] | None = None,
+    **extra: Any,
+) -> TaskResult:
+    """Generate an image from text + reference image(s)."""
+    if not image_urls:
+        raise ValueError("image_urls must contain at least one URL")
+    w, h = _resolve_size(aspect_ratio, resolution)
+    content: list[dict[str, str]] = [{"type": "text", "text": prompt}]
+    for url in image_urls:
+        content.append({"type": "image_url", "url": url.strip()})
+    payload: dict[str, Any] = {
+        "width": w,
+        "height": h,
+        "content": content,
+        "quality": "medium",
+        **extra,
+    }
+    path = f"{_IMAGE_GENERATION}/{model_id}"
+    return await client.submit_and_wait(path, payload, on_poll=on_poll)
+
+
+async def image_upscale(
+    client: FotorClient,
+    *,
+    image_url: str,
+    upscale_ratio: float = 2.0,
+    on_poll: Callable[[TaskResult], None] | None = None,
+) -> TaskResult:
+    """Upscale an image by 2x or 4x."""
+    payload = {
+        "upscaling_resize": upscale_ratio,
+        "userImageUrl": image_url,
+        "max_image_width": 2048,
+        "max_image_height": 2048,
+    }
+    return await client.submit_and_wait(_IMG_UPSCALER, payload, on_poll=on_poll)
+
+
+async def background_remove(
+    client: FotorClient,
+    *,
+    image_url: str,
+    on_poll: Callable[[TaskResult], None] | None = None,
+) -> TaskResult:
+    """Remove the background from an image."""
+    payload = {
+        "userImageUrl": image_url,
+        "action": "auto",
+    }
+    return await client.submit_and_wait(_BG_REMOVER, payload, on_poll=on_poll)
+
+
+# ---------------------------------------------------------------------------
+# Video tasks
+# ---------------------------------------------------------------------------
+
+def _video_payload(
+    prompt: str,
+    duration: int,
+    resolution: str,
+    aspect_ratio: str,
+    audio_enable: bool,
+    image_urls: list[str] | None = None,
+    **extra: Any,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "prompt": prompt,
+        "duration": duration,
+        "resolution": resolution,
+        "aspect_ratio": aspect_ratio if aspect_ratio != "auto" else "",
+        "scenes": "normal",
+        "enableAudio": audio_enable,
+    }
+    if image_urls is not None:
+        payload["imageUrls"] = image_urls
+    payload.update(extra)
+    return payload
+
+
+async def text2video(
+    client: FotorClient,
+    *,
+    prompt: str,
+    model_id: str,
+    duration: int = 5,
+    resolution: str = "1080p",
+    aspect_ratio: str = "16:9",
+    audio_enable: bool = False,
+    on_poll: Callable[[TaskResult], None] | None = None,
+    **extra: Any,
+) -> TaskResult:
+    """Generate a video from a text prompt."""
+    payload = _video_payload(prompt, duration, resolution, aspect_ratio, audio_enable, **extra)
+    path = f"{_TXT2VIDEO}/{model_id}"
+    return await client.submit_and_wait(path, payload, on_poll=on_poll)
+
+
+async def single_image2video(
+    client: FotorClient,
+    *,
+    prompt: str,
+    model_id: str,
+    image_url: str,
+    duration: int = 5,
+    resolution: str = "1080p",
+    aspect_ratio: str = "auto",
+    audio_enable: bool = False,
+    on_poll: Callable[[TaskResult], None] | None = None,
+    **extra: Any,
+) -> TaskResult:
+    """Animate a single image into a video."""
+    payload = _video_payload(
+        prompt, duration, resolution, aspect_ratio, audio_enable,
+        image_urls=[image_url], **extra,
+    )
+    path = f"{_IMG2VIDEO}/{model_id}"
+    return await client.submit_and_wait(path, payload, on_poll=on_poll)
+
+
+async def start_end_frame2video(
+    client: FotorClient,
+    *,
+    prompt: str,
+    model_id: str,
+    start_image_url: str,
+    end_image_url: str,
+    duration: int = 5,
+    resolution: str = "1080p",
+    aspect_ratio: str = "auto",
+    audio_enable: bool = False,
+    on_poll: Callable[[TaskResult], None] | None = None,
+    **extra: Any,
+) -> TaskResult:
+    """Generate a video from start and end frame images."""
+    payload = _video_payload(
+        prompt, duration, resolution, aspect_ratio, audio_enable,
+        image_urls=[start_image_url, end_image_url], **extra,
+    )
+    path = f"{_STARTEND2VIDEO}/{model_id}"
+    return await client.submit_and_wait(path, payload, on_poll=on_poll)
+
+
+async def multiple_image2video(
+    client: FotorClient,
+    *,
+    prompt: str,
+    model_id: str,
+    image_urls: list[str],
+    duration: int = 5,
+    resolution: str = "1080p",
+    aspect_ratio: str = "auto",
+    audio_enable: bool = False,
+    on_poll: Callable[[TaskResult], None] | None = None,
+    **extra: Any,
+) -> TaskResult:
+    """Generate a video from multiple reference images."""
+    if not image_urls or len(image_urls) < 2:
+        raise ValueError("image_urls must contain at least 2 URLs")
+    payload = _video_payload(
+        prompt, duration, resolution, aspect_ratio, audio_enable,
+        image_urls=image_urls, **extra,
+    )
+    path = f"{_CHARACTER2VIDEO}/{model_id}"
+    return await client.submit_and_wait(path, payload, on_poll=on_poll)

fotor_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: fotor-sdk
+Version: 0.1.0
+Summary: Lightweight async Python SDK for the Fotor OpenAPI
+Project-URL: Homepage, https://github.com/zeng121/fotor-sdk
+Project-URL: Documentation, https://github.com/zeng121/fotor-sdk#readme
+Project-URL: Issues, https://github.com/zeng121/fotor-sdk/issues
+License-Expression: MIT
+Keywords: ai,async,fotor,image-generation,video-generation
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# fotor-sdk
+
+Lightweight, async-first Python SDK for the [Fotor OpenAPI](https://api.fotor.com).
+Generate images and videos with a single API key -- no MCP server, no S3, no
+internal services required.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+### Single Task
+
+```python
+import asyncio
+import os
+from fotor_sdk import FotorClient, text2image
+
+async def main():
+    client = FotorClient(api_key=os.environ["FOTOR_OPENAPI_KEY"])
+    result = await text2image(
+        client,
+        prompt="A diamond kitten on velvet, studio lighting",
+        model_id="seedream-4-5-251128",
+        resolution="2k",
+        aspect_ratio="1:1",
+    )
+    print(result.result_url)
+
+asyncio.run(main())
+```
+
+### Parallel Batch with Progress
+
+```python
+import asyncio
+import os
+from fotor_sdk import FotorClient, TaskRunner, TaskSpec
+
+async def main():
+    client = FotorClient(api_key=os.environ["FOTOR_OPENAPI_KEY"])
+    runner = TaskRunner(client, max_concurrent=5)
+
+    specs = [
+        TaskSpec("text2image", {"prompt": "A cat", "model_id": "seedream-4-5-251128"}, tag="cat"),
+        TaskSpec("text2image", {"prompt": "A dog", "model_id": "seedream-4-5-251128"}, tag="dog"),
+        TaskSpec("text2video", {"prompt": "Sunset", "model_id": "kling-v3", "duration": 5}, tag="sunset"),
+    ]
+
+    def on_progress(total, completed, failed, in_progress, latest):
+        print(f"  {completed + failed}/{total} done, latest: {latest.metadata.get('tag')}")
+
+    results = await runner.run(specs, on_progress=on_progress)
+    for r in results:
+        print(f"{r.metadata.get('tag')}: {r.status.name} -> {r.result_url}")
+
+asyncio.run(main())
+```
+
+## Configuration
+
+| Environment Variable | Required | Default | Description |
+|---|---|---|---|
+| `FOTOR_OPENAPI_KEY` | Yes | -- | Your Fotor OpenAPI key |
+| `FOTOR_OPENAPI_ENDPOINT` | No | `https://api.fotor.com` | API base URL |
+
+## Available Task Functions
+
+| Function | Description |
+|---|---|
+| `text2image()` | Generate image from text |
+| `image2image()` | Edit / multi-reference generation |
+| `image_upscale()` | 2x or 4x upscale |
+| `background_remove()` | Remove background |
+| `text2video()` | Generate video from text |
+| `single_image2video()` | Animate a single image |
+| `start_end_frame2video()` | Interpolate between two frames |
+| `multiple_image2video()` | Video from multiple images |
+
+## Core Classes
+
+### FotorClient
+
+```python
+FotorClient(
+    api_key: str,
+    endpoint: str = "https://api.fotor.com",
+    poll_interval: float = 2.0,
+    max_poll_seconds: float = 1200,
+)
+```
+
+**Methods:**
+- `await create_task(path, payload) -> task_id`
+- `await get_task_status(task_id) -> TaskResult`
+- `await wait_for_task(task_id) -> TaskResult`
+- `await submit_and_wait(path, payload) -> TaskResult`
+- `submit_and_wait_sync(path, payload) -> TaskResult`
+
+### TaskRunner
+
+```python
+TaskRunner(client: FotorClient, max_concurrent: int = 5)
+```
+
+- `await run(specs, on_progress=None) -> list[TaskResult]`
+- `run_sync(specs, on_progress=None) -> list[TaskResult]`
+
+### TaskResult
+
+```python
+TaskResult(task_id, status, result_url, error, elapsed_seconds, metadata)
+result.success  # True when COMPLETED with a result_url
+```
+
+### TaskSpec
+
+```python
+TaskSpec(task_type: str, params: dict, tag: str = "")
+```
+
+## Error Handling
+
+```python
+from fotor_sdk import FotorAPIError
+
+try:
+    result = await text2image(client, prompt="...", model_id="bad-model")
+except FotorAPIError as e:
+    print(f"API error: {e}  code={e.code}")
+```
+
+For batch runs, failed tasks appear in results with `status=FAILED` and the
+`error` field populated. The runner never raises on individual task failures.
+
+## License
+
+MIT

fotor_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fotor_sdk/__init__.py,sha256=63CfGXev2WrgsBj0BBwsMAPgn_8gc5wnh6nEDyj2FIU,720
+fotor_sdk/client.py,sha256=PUIa8Z8tSygRo9MmkXzW19lh9_WpVbPLqKSULZhb1Nk,6289
+fotor_sdk/models.py,sha256=EHAW3jSJrkjcyptsOM2wXLsuod9SzUxLDVnU-_0ZjHU,1123
+fotor_sdk/runner.py,sha256=mxdmc0IGt_-xscCfbmgLWRQCYTHub8L2yg1GcCpgRjA,5295
+fotor_sdk/tasks.py,sha256=QCstuMlVEqDIDHAvWyyPd2atYGeTPh7UYJOI08hi5AA,7481
+fotor_sdk-0.1.0.dist-info/METADATA,sha256=L5r4mvlMRRdZ3uvoCzSYlKETxH0kULULf2d7YFMMNxM,4687
+fotor_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+fotor_sdk-0.1.0.dist-info/RECORD,,

fotor_sdk-0.1.0.dist-info/WHEEL

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