runapi-flux-2 0.1.0__tar.gz

runapi_flux_2-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: runapi-flux-2
+Version: 0.1.0
+Summary: Flux 2 text-to-image and remix-image client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/flux-2
+Project-URL: Documentation, https://runapi.ai/docs#sdk-flux-2
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,flux,flux-2,runapi,sdk,text-to-image
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Flux 2 Python SDK for RunAPI
+
+The flux 2 Python SDK is the language-specific package for Flux 2 on RunAPI. Use this flux 2 package for text-to-image, remix-image, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This flux 2 README is the Python package guide inside the public `flux-2-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/flux-2; for API reference, use https://runapi.ai/docs#flux-2; for SDK docs, use https://runapi.ai/docs#sdk-flux-2.
+
+## Install
+
+```bash
+pip install runapi-flux-2
+```
+
+## Quick start
+
+```python
+from runapi.flux_2 import Flux2Client
+
+client = Flux2Client()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_image.create(
+    model="flux-2-pro-text-to-image",
+    prompt="A cinematic product photo on warm paper",
+    aspect_ratio="1:1",
+)
+status = client.text_to_image.get(task.id)
+
+remix = client.remix_image.create(
+    model="flux-2-pro-remix-image",
+    prompt="Turn this product shot into a warm editorial photo",
+    source_image_urls=["https://example.com/source.jpg"],
+    aspect_ratio="auto",
+)
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_image.run(
+    model="flux-2-pro-text-to-image",
+    prompt="A futuristic cityscape at dusk",
+)
+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, videos, audio, or other files 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.flux_2` error classes when building image jobs or scripts. The available resources are `text_to_image` and `remix_image`. 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/flux-2
+- SDK docs: https://runapi.ai/docs#sdk-flux-2
+- Product docs: https://runapi.ai/docs#flux-2
+- Pricing and rate limits: https://runapi.ai/models/flux-2/pro-text-to-image
+- Provider comparison: https://runapi.ai/providers/black-forest-labs
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/flux-2-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_flux_2-0.1.0/README.md

@@ -0,0 +1,65 @@
+# Flux 2 Python SDK for RunAPI
+
+The flux 2 Python SDK is the language-specific package for Flux 2 on RunAPI. Use this flux 2 package for text-to-image, remix-image, and creative production flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This flux 2 README is the Python package guide inside the public `flux-2-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/flux-2; for API reference, use https://runapi.ai/docs#flux-2; for SDK docs, use https://runapi.ai/docs#sdk-flux-2.
+
+## Install
+
+```bash
+pip install runapi-flux-2
+```
+
+## Quick start
+
+```python
+from runapi.flux_2 import Flux2Client
+
+client = Flux2Client()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_image.create(
+    model="flux-2-pro-text-to-image",
+    prompt="A cinematic product photo on warm paper",
+    aspect_ratio="1:1",
+)
+status = client.text_to_image.get(task.id)
+
+remix = client.remix_image.create(
+    model="flux-2-pro-remix-image",
+    prompt="Turn this product shot into a warm editorial photo",
+    source_image_urls=["https://example.com/source.jpg"],
+    aspect_ratio="auto",
+)
+```
+
+Use `create` when you want to submit a task and return quickly, `get` when you need the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_image.run(
+    model="flux-2-pro-text-to-image",
+    prompt="A futuristic cityscape at dusk",
+)
+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, videos, audio, or other files 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.flux_2` error classes when building image jobs or scripts. The available resources are `text_to_image` and `remix_image`. 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/flux-2
+- SDK docs: https://runapi.ai/docs#sdk-flux-2
+- Product docs: https://runapi.ai/docs#flux-2
+- Pricing and rate limits: https://runapi.ai/models/flux-2/pro-text-to-image
+- Provider comparison: https://runapi.ai/providers/black-forest-labs
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/flux-2-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_flux_2-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-flux-2"
+version = "0.1.0"
+description = "Flux 2 text-to-image and remix-image client for RunAPI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "flux", "flux-2", "text-to-image", "ai", "sdk"]
+dependencies = ["runapi-core"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/flux-2"
+Documentation = "https://runapi.ai/docs#sdk-flux-2"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+runapi-core = { path = "../runapi-core", editable = true }
+
+[dependency-groups]
+dev = ["pytest>=8"]

runapi_flux_2-0.1.0/src/runapi/flux_2/__init__.py

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

runapi_flux_2-0.1.0/src/runapi/flux_2/client.py

@@ -0,0 +1,29 @@
+"""Flux 2 client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.remix_image import RemixImage
+from .resources.text_to_image import TextToImage
+
+
+class Flux2Client:
+    """Flux 2 text-to-image and remix-image client.
+
+    Example::
+
+        client = Flux2Client(api_key="sk-...")
+        result = client.text_to_image.run(
+            model="flux-2-pro-text-to-image", prompt="A futuristic cityscape"
+        )
+    """
+
+    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.text_to_image = TextToImage(http)
+        self.remix_image = RemixImage(http)

runapi_flux_2-0.1.0/src/runapi/flux_2/resources/__init__.py

@@ -0,0 +1,4 @@
+from .remix_image import RemixImage
+from .text_to_image import TextToImage
+
+__all__ = ["TextToImage", "RemixImage"]

runapi_flux_2-0.1.0/src/runapi/flux_2/resources/remix_image.py

@@ -0,0 +1,78 @@
+"""Flux 2 remix-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    OUTPUT_RESOLUTIONS,
+    REMIX_ASPECT_RATIOS,
+    REMIX_MODELS,
+    CompletedRemixImageResponse,
+    RemixImageResponse,
+)
+
+
+class RemixImage(Resource):
+    """Remix one or more source images into a new image with Flux 2 models."""
+
+    ENDPOINT = "/api/v1/flux_2/remix_image"
+
+    RESPONSE_CLASS = RemixImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedRemixImageResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a remix-image task and poll until it completes.
+
+        Args:
+            **params: Remix-image parameters (model, prompt, ...).
+
+        Returns:
+            The completed remix-image response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a remix-image task and return immediately with an id.
+
+        Args:
+            **params: Remix-image parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a remix-image task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current remix-image status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        model = params.get("model")
+        if not model:
+            raise ValidationError("model is required")
+        if model not in REMIX_MODELS:
+            joined = ", ".join(REMIX_MODELS)
+            raise ValidationError(f"Invalid model: {model}. Must be one of: {joined}")
+
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+
+        self._validate_optional(params, "aspect_ratio", REMIX_ASPECT_RATIOS)
+        self._validate_optional(params, "output_resolution", OUTPUT_RESOLUTIONS)
+
+        urls = params.get("source_image_urls")
+        if not urls:
+            raise ValidationError("source_image_urls is required")

runapi_flux_2-0.1.0/src/runapi/flux_2/resources/text_to_image.py

@@ -0,0 +1,74 @@
+"""Flux 2 text-to-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    ASPECT_RATIOS,
+    OUTPUT_RESOLUTIONS,
+    TEXT_TO_IMAGE_MODELS,
+    CompletedTextToImageResponse,
+    TextToImageResponse,
+)
+
+
+class TextToImage(Resource):
+    """Generate images from text prompts with Flux 2 models."""
+
+    ENDPOINT = "/api/v1/flux_2/text_to_image"
+
+    RESPONSE_CLASS = TextToImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToImageResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a text-to-image task and poll until it completes.
+
+        Args:
+            **params: Text-to-image parameters (model, prompt, ...).
+
+        Returns:
+            The completed text-to-image response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a text-to-image task and return immediately with an id.
+
+        Args:
+            **params: Text-to-image parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a text-to-image task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current text-to-image status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if not params.get("model"):
+            raise ValidationError("model is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+
+        model = params.get("model")
+        if model not in TEXT_TO_IMAGE_MODELS:
+            joined = ", ".join(TEXT_TO_IMAGE_MODELS)
+            raise ValidationError(f"Invalid model: {model}. Must be one of: {joined}")
+
+        self._validate_optional(params, "aspect_ratio", ASPECT_RATIOS)
+        self._validate_optional(params, "output_resolution", OUTPUT_RESOLUTIONS)

runapi_flux_2-0.1.0/src/runapi/flux_2/types.py

@@ -0,0 +1,48 @@
+"""Flux 2 model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+MODELS = [
+    "flux-2-pro-text-to-image",
+    "flux-2-pro-remix-image",
+    "flux-2-flex-text-to-image",
+    "flux-2-flex-remix-image",
+]
+TEXT_TO_IMAGE_MODELS = ["flux-2-pro-text-to-image", "flux-2-flex-text-to-image"]
+REMIX_MODELS = ["flux-2-pro-remix-image", "flux-2-flex-remix-image"]
+
+ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3"]
+REMIX_ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "3:2", "2:3", "auto"]
+OUTPUT_RESOLUTIONS = ["1k", "2k"]
+
+
+class Image(BaseModel):
+    url = optional(str)
+
+
+class TextToImageResponse(TaskResponse):
+    """Task status/result for Flux 2 text-to-image."""
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+    images = optional([lambda: Image])
+    error = optional(str)
+
+
+class CompletedTextToImageResponse(TextToImageResponse):
+    """Returned by ``text_to_image.run()`` once polling observes completion.
+
+    ``images`` is required so callers never have to null-check it on success.
+    """
+
+    images = required([lambda: Image])
+
+
+class RemixImageResponse(TextToImageResponse):
+    """Task status/result for Flux 2 remix-image."""
+    pass
+
+
+class CompletedRemixImageResponse(CompletedTextToImageResponse):
+    pass

runapi_flux_2-0.1.0/tests/test_client.py

@@ -0,0 +1,153 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.flux_2 import Flux2Client
+from runapi.flux_2.resources.remix_image import RemixImage
+from runapi.flux_2.resources.text_to_image import TextToImage
+from runapi.flux_2.types import CompletedTextToImageResponse, TextToImageResponse
+
+
+class FakeHttp:
+    """Records (method, path, body) and replays preset responses by call order."""
+
+    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
+
+
+# --- authentication -------------------------------------------------------
+
+
+def test_accepts_api_key_parameter():
+    assert isinstance(Flux2Client(api_key="param-key", http_client=FakeHttp()), Flux2Client)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(Flux2Client(http_client=FakeHttp()), Flux2Client)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(Flux2Client(http_client=FakeHttp()), Flux2Client)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        Flux2Client()
+
+
+# --- transport injection / accessors --------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = Flux2Client(api_key="k", http_client=fake)
+    assert client.text_to_image._http is fake
+    assert client.remix_image._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = Flux2Client(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_image, TextToImage)
+    assert isinstance(client.remix_image, RemixImage)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = Flux2Client(api_key="k", http_client=fake)
+    result = client.text_to_image.create(
+        model="flux-2-pro-text-to-image",
+        prompt="hello",
+        aspect_ratio="1:1",
+        seed=None,
+    )
+    assert fake.calls == [
+        ("post", "/api/v1/flux_2/text_to_image", {"model": "flux-2-pro-text-to-image", "prompt": "hello", "aspect_ratio": "1:1"}),
+    ]
+    assert isinstance(result, TextToImageResponse)
+    assert result.id == "t1"
+
+
+def test_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = Flux2Client(api_key="k", http_client=fake)
+    client.text_to_image.get("t1")
+    assert fake.calls == [("get", "/api/v1/flux_2/text_to_image/t1", None)]
+
+
+def test_run_polls_and_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "images": [{"url": "https://x/y.png"}]},
+    )
+    client = Flux2Client(api_key="k", http_client=fake)
+    result = client.text_to_image.run(model="flux-2-pro-text-to-image", prompt="hi")
+
+    assert isinstance(result, CompletedTextToImageResponse)
+    assert result.images[0].url == "https://x/y.png"
+    assert [call[0] for call in fake.calls] == ["post", "get"]
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_create_requires_model():
+    client = Flux2Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model is required"):
+        client.text_to_image.create(prompt="hi")
+
+
+def test_create_requires_prompt():
+    client = Flux2Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.text_to_image.create(model="flux-2-pro-text-to-image")
+
+
+def test_create_rejects_unknown_model():
+    client = Flux2Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid model"):
+        client.text_to_image.create(model="not-a-model", prompt="hi")
+
+
+def test_create_rejects_invalid_enum():
+    client = Flux2Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid aspect_ratio"):
+        client.text_to_image.create(model="flux-2-pro-text-to-image", prompt="hi", aspect_ratio="99:1")
+
+
+def test_remix_requires_source_image_urls():
+    client = Flux2Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_image_urls is required"):
+        client.remix_image.create(model="flux-2-pro-remix-image", prompt="hi")
+
+
+def test_remix_accepts_auto_aspect_ratio():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = Flux2Client(api_key="k", http_client=fake)
+    client.remix_image.create(
+        model="flux-2-pro-remix-image",
+        prompt="hi",
+        source_image_urls=["https://example.com/a.jpg"],
+        aspect_ratio="auto",
+    )
+    _, path, body = fake.calls[0]
+    assert path == "/api/v1/flux_2/remix_image"
+    assert body["aspect_ratio"] == "auto"