fotor-sdk 0.1.0__tar.gz

fotor_sdk-0.1.0/.env.example

@@ -0,0 +1 @@
+FOTOR_OPENAPI_KEY="your-api-key"

fotor_sdk-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+.env
+
+__pycache__/
+*.py[cod]
+*.pyo
+
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+*.so
+
+.venv/
+venv/
+env/
+
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+*.log

fotor_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,141 @@
+# 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/examples/parallel_generate.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Example: run multiple Fotor image/video tasks in parallel with live progress.
+
+Usage:
+    export FOTOR_OPENAPI_KEY="your-api-key"
+    python fotor_sdk/scripts/parallel_generate.py
+
+Optionally set FOTOR_OPENAPI_ENDPOINT to point at a different API host.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+
+from fotor_sdk import (
+    FotorClient,
+    TaskRunner,
+    TaskSpec,
+    TaskResult,
+    TaskStatus,
+    text2image,
+)
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(levelname)-7s  %(message)s",
+    datefmt="%H:%M:%S",
+)
+log = logging.getLogger("example")
+
+
+# ---------------------------------------------------------------------------
+# 1. Single task -- simplest usage
+# ---------------------------------------------------------------------------
+
+async def single_task_demo(client: FotorClient) -> None:
+    log.info("=== Single task demo ===")
+    result = await text2image(
+        client,
+        prompt="A diamond kitten on a velvet cushion, studio lighting, 4K",
+        model_id="seedream-4-5-251128",
+        resolution="1k",
+        aspect_ratio="1:1",
+        on_poll=lambda r: log.info("  polling %s  status=%s  %.1fs",
+                                   r.task_id, r.status.name, r.elapsed_seconds),
+    )
+    log.info("Result: %s", result)
+
+
+# ---------------------------------------------------------------------------
+# 2. Parallel batch -- the main use-case
+# ---------------------------------------------------------------------------
+
+def progress_callback(
+    total: int,
+    completed: int,
+    failed: int,
+    in_progress: int,
+    latest: TaskResult,
+) -> None:
+    bar_len = 30
+    done_ratio = (completed + failed) / total if total else 0
+    filled = int(bar_len * done_ratio)
+    bar = "#" * filled + "-" * (bar_len - filled)
+    tag = latest.metadata.get("tag", latest.task_id)
+    status = "OK" if latest.success else latest.status.name
+    print(
+        f"\r[{bar}] {completed + failed}/{total}  "
+        f"(ok={completed} fail={failed} run={in_progress})  "
+        f"latest: {tag} -> {status}     ",
+        end="",
+        flush=True,
+    )
+
+
+async def batch_demo(client: FotorClient) -> None:
+    log.info("=== Parallel batch demo ===")
+
+    specs = [
+        TaskSpec(
+            task_type="text2image",
+            params={
+                "prompt": "A cyberpunk city skyline at sunset, neon lights, 8K",
+                "model_id": "seedream-4-5-251128",
+                "resolution": "1k",
+                "aspect_ratio": "16:9",
+            },
+            tag="cyberpunk-city",
+        ),
+        TaskSpec(
+            task_type="text2image",
+            params={
+                "prompt": "A serene Japanese garden in autumn, koi pond, golden leaves",
+                "model_id": "seedream-4-5-251128",
+                "resolution": "1k",
+                "aspect_ratio": "1:1",
+            },
+            tag="zen-garden",
+        ),
+        TaskSpec(
+            task_type="text2video",
+            params={
+                "prompt": "Ocean waves crashing on a rocky shore, cinematic drone shot",
+                "model_id": "kling-v3",
+                "duration": 5,
+                "resolution": "1080p",
+                "aspect_ratio": "16:9",
+            },
+            tag="ocean-waves",
+        ),
+    ]
+
+    runner = TaskRunner(client, max_concurrent=5)
+    start = time.monotonic()
+    results = await runner.run(specs, on_progress=progress_callback)
+    print()  # newline after progress bar
+
+    elapsed = time.monotonic() - start
+    log.info("Batch finished in %.1fs", elapsed)
+    for r in results:
+        tag = r.metadata.get("tag", r.task_id)
+        if r.success:
+            log.info("  [OK]   %-20s -> %s  (%.1fs)", tag, r.result_url, r.elapsed_seconds)
+        else:
+            log.info("  [FAIL] %-20s -> %s  (%.1fs)", tag, r.error, r.elapsed_seconds)
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+async def main() -> None:
+    api_key = os.environ.get("FOTOR_OPENAPI_KEY", "")
+    endpoint = os.environ.get("FOTOR_OPENAPI_ENDPOINT", "https://api.fotor.com")
+
+    if not api_key:
+        print("ERROR: set FOTOR_OPENAPI_KEY environment variable first", file=sys.stderr)
+        sys.exit(1)
+
+    client = FotorClient(api_key=api_key, endpoint=endpoint)
+
+    await single_task_demo(client)
+    await batch_demo(client)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())