runapi-recraft 0.1.0__tar.gz

runapi_recraft-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Build artifacts
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Bytecode
+__pycache__/
+*.py[cod]
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+uv.lock
+
+# Test / type caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store

runapi_recraft-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: runapi-recraft
+Version: 0.1.0
+Summary: Recraft image upscale and background-removal client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/recraft
+Project-URL: Documentation, https://runapi.ai/docs#sdk-recraft
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,recraft,remove-background,runapi,sdk,upscale-image
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Recraft Python SDK for RunAPI
+
+The Recraft Python SDK is the language-specific package for Recraft on RunAPI.
+Use it for image upscale and background-removal flows when your application needs
+JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+For model details, use https://runapi.ai/models/recraft; for API reference, use
+https://runapi.ai/docs#recraft; for SDK docs, use https://runapi.ai/docs#sdk-recraft.
+
+## Install
+
+```bash
+pip install runapi-recraft
+```
+
+## Quick start
+
+```python
+from runapi.recraft import RecraftClient
+
+client = RecraftClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.upscale_image.create(
+    model="recraft-crisp-upscale",
+    source_image_url="https://example.com/source.jpg",
+)
+status = client.upscale_image.get(task.id)
+
+removed = client.remove_background.create(
+    model="recraft-remove-background",
+    source_image_url="https://example.com/source.jpg",
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task
+state, and `run` to create and poll until completion:
+
+```python
+result = client.upscale_image.run(
+    model="recraft-crisp-upscale",
+    source_image_url="https://example.com/source.jpg",
+)
+print(result.images[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a
+worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images in
+your own durable storage within 7 days; do not treat returned URLs as long-term
+assets.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.recraft` error
+classes when building image jobs or scripts. The available resources are
+`upscale_image` and `remove_background`. Keep `RUNAPI_API_KEY` in the environment
+or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/recraft
+- SDK docs: https://runapi.ai/docs#sdk-recraft
+- Product docs: https://runapi.ai/docs#recraft
+- Pricing and rate limits: https://runapi.ai/models/recraft
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_recraft-0.1.0/README.md

@@ -0,0 +1,70 @@
+# Recraft Python SDK for RunAPI
+
+The Recraft Python SDK is the language-specific package for Recraft on RunAPI.
+Use it for image upscale and background-removal flows when your application needs
+JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+For model details, use https://runapi.ai/models/recraft; for API reference, use
+https://runapi.ai/docs#recraft; for SDK docs, use https://runapi.ai/docs#sdk-recraft.
+
+## Install
+
+```bash
+pip install runapi-recraft
+```
+
+## Quick start
+
+```python
+from runapi.recraft import RecraftClient
+
+client = RecraftClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.upscale_image.create(
+    model="recraft-crisp-upscale",
+    source_image_url="https://example.com/source.jpg",
+)
+status = client.upscale_image.get(task.id)
+
+removed = client.remove_background.create(
+    model="recraft-remove-background",
+    source_image_url="https://example.com/source.jpg",
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task
+state, and `run` to create and poll until completion:
+
+```python
+result = client.upscale_image.run(
+    model="recraft-crisp-upscale",
+    source_image_url="https://example.com/source.jpg",
+)
+print(result.images[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a
+worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images in
+your own durable storage within 7 days; do not treat returned URLs as long-term
+assets.
+
+## Language notes
+
+Pass parameters as keyword arguments and catch the `runapi.recraft` error
+classes when building image jobs or scripts. The available resources are
+`upscale_image` and `remove_background`. Keep `RUNAPI_API_KEY` in the environment
+or your secret manager; never commit API keys or callback secrets.
+
+## Links
+
+- Model page: https://runapi.ai/models/recraft
+- SDK docs: https://runapi.ai/docs#sdk-recraft
+- Product docs: https://runapi.ai/docs#recraft
+- Pricing and rate limits: https://runapi.ai/models/recraft
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_recraft-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-recraft"
+version = "0.1.0"
+description = "Recraft image upscale and background-removal client for RunAPI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "recraft", "upscale-image", "remove-background", "ai", "sdk"]
+dependencies = ["runapi-core"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/recraft"
+Documentation = "https://runapi.ai/docs#sdk-recraft"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+runapi-core = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.runapi]
+slug = "recraft"

runapi_recraft-0.1.0/src/runapi/recraft/__init__.py

@@ -0,0 +1,24 @@
+"""Recraft client for RunAPI."""
+
+from runapi.core import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    TaskFailedError,
+    TaskTimeoutError,
+    ValidationError,
+)
+
+from .client import RecraftClient
+
+__all__ = [
+    "RecraftClient",
+    "AuthenticationError",
+    "RateLimitError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ValidationError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]

runapi_recraft-0.1.0/src/runapi/recraft/client.py

@@ -0,0 +1,30 @@
+"""Recraft client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.remove_background import RemoveBackground
+from .resources.upscale_image import UpscaleImage
+
+
+class RecraftClient:
+    """Recraft image upscale and background-removal client.
+
+    Example::
+
+        client = RecraftClient(api_key="sk-...")
+        result = client.upscale_image.run(
+            model="recraft-crisp-upscale",
+            source_image_url="https://example.com/source.jpg",
+        )
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        resolved_api_key = resolve_api_key(api_key)
+        client_options = ClientOptions(api_key=resolved_api_key, **options)
+        http = client_options.http_client or HttpClient(client_options)
+        self.upscale_image = UpscaleImage(http)
+        self.remove_background = RemoveBackground(http)

runapi_recraft-0.1.0/src/runapi/recraft/contract_gen.py

@@ -0,0 +1,22 @@
+CONTRACT = {
+    "remove-background": {
+        "models": ["recraft-remove-background"],
+        "fields_by_model": {
+            "recraft-remove-background": {
+                "source_image_url": {
+                    "required": True
+                }
+            }
+        }
+    },
+    "upscale-image": {
+        "models": ["recraft-crisp-upscale"],
+        "fields_by_model": {
+            "recraft-crisp-upscale": {
+                "source_image_url": {
+                    "required": True
+                }
+            }
+        }
+    }
+}

runapi_recraft-0.1.0/src/runapi/recraft/resources/__init__.py

@@ -0,0 +1,4 @@
+from .remove_background import RemoveBackground
+from .upscale_image import UpscaleImage
+
+__all__ = ["UpscaleImage", "RemoveBackground"]

runapi_recraft-0.1.0/src/runapi/recraft/resources/remove_background.py

@@ -0,0 +1,58 @@
+"""Recraft remove-background resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runapi.core import Resource
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedImageTaskResponse,
+    ImageTaskResponse,
+)
+
+
+class RemoveBackground(Resource):
+    """Remove image backgrounds with Recraft models."""
+
+    ENDPOINT = "/api/v1/recraft/remove_background"
+
+    RESPONSE_CLASS = ImageTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedImageTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Run a remove-background task and poll until it completes.
+
+        Args:
+            **params: remove-background parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) remove-background response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a remove-background task and return immediately with an id.
+
+        Args:
+            **params: remove-background parameters (model, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_contract(CONTRACT["remove-background"], compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a remove-background task.
+
+        Args:
+            id: The task id returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")

runapi_recraft-0.1.0/src/runapi/recraft/resources/upscale_image.py

@@ -0,0 +1,58 @@
+"""Recraft upscale-image resource."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from runapi.core import Resource
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedImageTaskResponse,
+    ImageTaskResponse,
+)
+
+
+class UpscaleImage(Resource):
+    """Upscale images with Recraft models."""
+
+    ENDPOINT = "/api/v1/recraft/upscale_image"
+
+    RESPONSE_CLASS = ImageTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedImageTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Run an image upscale task and poll until it completes.
+
+        Args:
+            **params: image upscale parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) image upscale response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create an image upscale task and return immediately with an id.
+
+        Args:
+            **params: image upscale parameters (model, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_contract(CONTRACT["upscale-image"], compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of an image upscale task.
+
+        Args:
+            id: The task id returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")

runapi_recraft-0.1.0/src/runapi/recraft/types.py

@@ -0,0 +1,24 @@
+"""Recraft model lists and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+
+class Image(BaseModel):
+    url = optional(str)
+
+
+class ImageTaskResponse(TaskResponse):
+    """Recraft image task status response."""
+
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+    images = optional([lambda: Image])
+    error = optional(str)
+
+
+class CompletedImageTaskResponse(ImageTaskResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    images = required([lambda: Image])

runapi_recraft-0.1.0/tests/test_client.py

@@ -0,0 +1,156 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.recraft import RecraftClient
+from runapi.recraft.resources.remove_background import RemoveBackground
+from runapi.recraft.resources.upscale_image import UpscaleImage
+from runapi.recraft.types import CompletedImageTaskResponse, ImageTaskResponse
+
+
+class FakeHttp:
+    def __init__(self, *responses):
+        self._responses = list(responses)
+        self.calls = []
+
+    def request(self, method, path, body=None, options=None):
+        self.calls.append((method, path, body))
+        if self._responses:
+            return self._responses.pop(0)
+        return {"id": "task_1", "status": "pending"}
+
+
+@pytest.fixture(autouse=True)
+def reset_config(monkeypatch):
+    monkeypatch.delenv("RUNAPI_API_KEY", raising=False)
+    monkeypatch.setattr(config, "api_key", None)
+    yield
+
+
+# --- auth -----------------------------------------------------------------
+
+
+def test_accepts_api_key_parameter():
+    assert isinstance(RecraftClient(api_key="k", http_client=FakeHttp()), RecraftClient)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(RecraftClient(http_client=FakeHttp()), RecraftClient)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(RecraftClient(http_client=FakeHttp()), RecraftClient)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        RecraftClient()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = RecraftClient(api_key="k", http_client=fake)
+    assert client.upscale_image._http is fake
+    assert client.remove_background._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = RecraftClient(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.upscale_image, UpscaleImage)
+    assert isinstance(client.remove_background, RemoveBackground)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_upscale_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = RecraftClient(api_key="k", http_client=fake)
+    result = client.upscale_image.create(
+        model="recraft-crisp-upscale",
+        source_image_url="https://x/a.png",
+        callback_url=None,
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/recraft/upscale_image",
+            {"model": "recraft-crisp-upscale", "source_image_url": "https://x/a.png"},
+        ),
+    ]
+    assert isinstance(result, ImageTaskResponse)
+
+
+def test_upscale_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = RecraftClient(api_key="k", http_client=fake)
+    client.upscale_image.get("t1")
+    assert fake.calls == [("get", "/api/v1/recraft/upscale_image/t1", None)]
+
+
+def test_remove_background_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = RecraftClient(api_key="k", http_client=fake)
+    client.remove_background.create(
+        model="recraft-remove-background",
+        source_image_url="https://x/a.png",
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/recraft/remove_background",
+            {"model": "recraft-remove-background", "source_image_url": "https://x/a.png"},
+        ),
+    ]
+
+
+def test_remove_background_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = RecraftClient(api_key="k", http_client=fake)
+    client.remove_background.get("t1")
+    assert fake.calls == [("get", "/api/v1/recraft/remove_background/t1", None)]
+
+
+def test_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "images": [{"url": "https://x/y.png"}]},
+    )
+    client = RecraftClient(api_key="k", http_client=fake)
+    result = client.upscale_image.run(
+        model="recraft-crisp-upscale", source_image_url="https://x/a.png"
+    )
+    assert isinstance(result, CompletedImageTaskResponse)
+    assert result.images[0].url == "https://x/y.png"
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_upscale_requires_model():
+    client = RecraftClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: recraft-crisp-upscale"):
+        client.upscale_image.create(source_image_url="https://x/a.png")
+
+
+def test_upscale_requires_source_image_url():
+    client = RecraftClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_image_url is required"):
+        client.upscale_image.create(model="recraft-crisp-upscale")
+
+
+def test_upscale_rejects_unknown_model():
+    client = RecraftClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: recraft-crisp-upscale"):
+        client.upscale_image.create(model="nope", source_image_url="https://x/a.png")
+
+
+def test_remove_background_rejects_unknown_model():
+    client = RecraftClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: recraft-remove-background"):
+        client.remove_background.create(model="nope", source_image_url="https://x/a.png")