runapi-gpt-image-2.5 0.1.1__tar.gz

runapi_gpt_image_2_5-0.1.1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: runapi-gpt-image-2.5
+Version: 0.1.1
+Summary: RunAPI GPT Image 2.5 SDK for text-to-image and image editing workflows in JavaScript, Python, Ruby, Go, Java, and PHP
+Project-URL: Homepage, https://runapi.ai/models/gpt-image-2.5
+Project-URL: Documentation, https://runapi.ai/docs/resources/sdks
+Project-URL: Source, https://github.com/runapi-ai/gpt-image-2.5-sdk
+Project-URL: Issues, https://github.com/runapi-ai/gpt-image-2.5-sdk/issues
+Project-URL: Changelog, https://github.com/runapi-ai/gpt-image-2.5-sdk/blob/main/CHANGELOG.md
+Project-URL: Release Notes, https://github.com/runapi-ai/gpt-image-2.5-sdk/releases/tag/python%2Fv0.1.1
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: api,golang,gpt-image-2-5,gpt-image-2-5-api,gradle,image-api,image-generation,java,maven,python,ruby,runapi,runapi-ai,sdk,text-to-image,typescript
+Requires-Python: >=3.9
+Requires-Dist: runapi-core>=0.8.2
+Description-Content-Type: text/markdown
+
+# GPT Image 2.5 Python SDK for RunAPI
+
+The GPT Image 2.5 Python SDK provides text-to-image and image editing clients. Requests select `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst`.
+
+## Install
+
+```bash
+pip install runapi-gpt-image-2.5
+```
+
+## Quick start
+
+```python
+from runapi.gpt_image_2_5 import GptImage25Client
+
+client = GptImage25Client()
+task = client.text_to_image.create(
+    model="gpt-image-2.5-flare",
+    prompt="A precise product render on white marble",
+    aspect_ratio="1:1",
+    output_resolution="1k",
+)
+status = client.text_to_image.get(task.id)
+
+edit = client.edit_image.create(
+    model="gpt-image-2.5-sunburst",
+    prompt="Change the background to a botanical studio",
+    source_image_urls=["https://cdn.runapi.ai/public/samples/image.jpg"],
+)
+```
+
+Use `create` to submit, `get` to fetch task status, and `run` to create and poll until completion. Keep `RUNAPI_API_KEY` in the environment or a secret manager.
+
+RunAPI-generated file URLs are temporary. Store generated files in durable storage within 7 days.
+
+## Links
+
+- Model overview: https://runapi.ai/models/gpt-image-2.5
+- Flare: https://runapi.ai/models/gpt-image-2.5/flare
+- Sunburst: https://runapi.ai/models/gpt-image-2.5/sunburst
+- API reference: https://runapi.ai/docs/api/gpt-image-2-5/text-to-image
+- SDK docs: https://runapi.ai/docs/resources/sdks
+- Repository: https://github.com/runapi-ai/gpt-image-2.5-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_gpt_image_2_5-0.1.1/README.md

@@ -0,0 +1,47 @@
+# GPT Image 2.5 Python SDK for RunAPI
+
+The GPT Image 2.5 Python SDK provides text-to-image and image editing clients. Requests select `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst`.
+
+## Install
+
+```bash
+pip install runapi-gpt-image-2.5
+```
+
+## Quick start
+
+```python
+from runapi.gpt_image_2_5 import GptImage25Client
+
+client = GptImage25Client()
+task = client.text_to_image.create(
+    model="gpt-image-2.5-flare",
+    prompt="A precise product render on white marble",
+    aspect_ratio="1:1",
+    output_resolution="1k",
+)
+status = client.text_to_image.get(task.id)
+
+edit = client.edit_image.create(
+    model="gpt-image-2.5-sunburst",
+    prompt="Change the background to a botanical studio",
+    source_image_urls=["https://cdn.runapi.ai/public/samples/image.jpg"],
+)
+```
+
+Use `create` to submit, `get` to fetch task status, and `run` to create and poll until completion. Keep `RUNAPI_API_KEY` in the environment or a secret manager.
+
+RunAPI-generated file URLs are temporary. Store generated files in durable storage within 7 days.
+
+## Links
+
+- Model overview: https://runapi.ai/models/gpt-image-2.5
+- Flare: https://runapi.ai/models/gpt-image-2.5/flare
+- Sunburst: https://runapi.ai/models/gpt-image-2.5/sunburst
+- API reference: https://runapi.ai/docs/api/gpt-image-2-5/text-to-image
+- SDK docs: https://runapi.ai/docs/resources/sdks
+- Repository: https://github.com/runapi-ai/gpt-image-2.5-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_gpt_image_2_5-0.1.1/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-gpt-image-2.5"
+version = "0.1.1"
+description = "RunAPI GPT Image 2.5 SDK for text-to-image and image editing workflows in JavaScript, Python, Ruby, Go, Java, and PHP"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "runapi-ai", "gpt-image-2-5", "api", "sdk", "typescript", "python", "ruby", "golang", "java", "maven", "gradle", "image-generation", "text-to-image", "image-api", "gpt-image-2-5-api"]
+dependencies = ["runapi-core>=0.8.2"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/gpt-image-2.5"
+Documentation = "https://runapi.ai/docs/resources/sdks"
+Source = "https://github.com/runapi-ai/gpt-image-2.5-sdk"
+Issues = "https://github.com/runapi-ai/gpt-image-2.5-sdk/issues"
+Changelog = "https://github.com/runapi-ai/gpt-image-2.5-sdk/blob/main/CHANGELOG.md"
+"Release Notes" = "https://github.com/runapi-ai/gpt-image-2.5-sdk/releases/tag/python%2Fv0.1.1"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.runapi]
+slug = "gpt-image-2.5"

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/__init__.py

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

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/client.py

@@ -0,0 +1,28 @@
+"""GPT Image 2.5 client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ProviderClient
+
+from .resources.edit_image import EditImage
+from .resources.text_to_image import TextToImage
+
+
+class GptImage25Client(ProviderClient):
+    """GPT Image 2.5 text-to-image and edit-image client.
+
+    Example::
+
+        client = GptImage25Client(api_key="sk-...")
+        result = client.text_to_image.run(
+            model="gpt-image-2.5-flare", prompt="A futuristic cityscape at night"
+        )
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        super().__init__(api_key, **options)
+        http = self._http
+        self.text_to_image = TextToImage(http)
+        self.edit_image = EditImage(http)

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/contract_gen.py

@@ -0,0 +1,134 @@
+CONTRACT = {
+    "edit-image": {
+        "models": ["gpt-image-2.5-flare", "gpt-image-2.5-sunburst"],
+        "fields_by_model": {
+            "gpt-image-2.5-flare": {
+                "aspect_ratio": {
+                    "enum": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"]
+                },
+                "output_resolution": {
+                    "enum": ["1k", "2k", "4k"]
+                },
+                "prompt": {
+                    "required": True
+                },
+                "source_image_urls": {
+                    "required": True,
+                    "max_items": 16
+                }
+            },
+            "gpt-image-2.5-sunburst": {
+                "aspect_ratio": {
+                    "enum": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"]
+                },
+                "output_resolution": {
+                    "enum": ["1k", "2k", "4k"]
+                },
+                "prompt": {
+                    "required": True
+                },
+                "source_image_urls": {
+                    "required": True,
+                    "max_items": 16
+                }
+            }
+        },
+        "rules": [{
+            "when": {
+                "aspect_ratio": "1:1",
+                "output_resolution": "4k"
+            },
+            "forbidden": ["aspect_ratio"]
+        }, {
+            "when": {
+                "aspect_ratio": "auto",
+                "output_resolution": "4k"
+            },
+            "forbidden": ["aspect_ratio"]
+        }, {
+            "when": {
+                "aspect_ratio": {
+                    "present": False
+                },
+                "output_resolution": "4k"
+            },
+            "forbidden": ["output_resolution"]
+        }, {
+            "when": {
+                "aspect_ratio": "auto",
+                "output_resolution": "2k"
+            },
+            "forbidden": ["aspect_ratio"]
+        }, {
+            "when": {
+                "aspect_ratio": {
+                    "present": False
+                },
+                "output_resolution": "2k"
+            },
+            "forbidden": ["output_resolution"]
+        }]
+    },
+    "text-to-image": {
+        "models": ["gpt-image-2.5-flare", "gpt-image-2.5-sunburst"],
+        "fields_by_model": {
+            "gpt-image-2.5-flare": {
+                "aspect_ratio": {
+                    "enum": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"]
+                },
+                "output_resolution": {
+                    "enum": ["1k", "2k", "4k"]
+                },
+                "prompt": {
+                    "required": True
+                }
+            },
+            "gpt-image-2.5-sunburst": {
+                "aspect_ratio": {
+                    "enum": ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5", "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"]
+                },
+                "output_resolution": {
+                    "enum": ["1k", "2k", "4k"]
+                },
+                "prompt": {
+                    "required": True
+                }
+            }
+        },
+        "rules": [{
+            "when": {
+                "aspect_ratio": "1:1",
+                "output_resolution": "4k"
+            },
+            "forbidden": ["aspect_ratio"]
+        }, {
+            "when": {
+                "aspect_ratio": "auto",
+                "output_resolution": "4k"
+            },
+            "forbidden": ["aspect_ratio"]
+        }, {
+            "when": {
+                "aspect_ratio": {
+                    "present": False
+                },
+                "output_resolution": "4k"
+            },
+            "forbidden": ["output_resolution"]
+        }, {
+            "when": {
+                "aspect_ratio": "auto",
+                "output_resolution": "2k"
+            },
+            "forbidden": ["aspect_ratio"]
+        }, {
+            "when": {
+                "aspect_ratio": {
+                    "present": False
+                },
+                "output_resolution": "2k"
+            },
+            "forbidden": ["output_resolution"]
+        }]
+    }
+}

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/resources/__init__.py

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

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/resources/edit_image.py

@@ -0,0 +1,58 @@
+"""GPT Image 2.5 edit-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import Resource, RequestOptions
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedEditImageResponse,
+    EditImageResponse,
+)
+
+
+class EditImage(Resource):
+    """Edit images from a prompt and source images with GPT Image 2.5."""
+
+    ENDPOINT = "/api/v1/gpt_image_2_5/edit_image"
+
+    RESPONSE_CLASS = EditImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedEditImageResponse
+
+    def run(self, options: Optional[RequestOptions] = None, **params: Any) -> Any:
+        """Create an edit-image task and poll until it completes.
+
+        Args:
+            **params: Edit-image parameters (model, prompt, ...).
+
+        Returns:
+            The completed edit-image response.
+        """
+        task = self.create(options=options, **params)
+        return self._poll_until_complete(lambda: self.get(task.id, options=options))
+
+    def create(self, options: Optional[RequestOptions] = None, **params: Any) -> Any:
+        """Create an edit-image task and return immediately with an id.
+
+        Args:
+            **params: Edit-image parameters (model, prompt, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_contract(CONTRACT["edit-image"], compacted)
+        return self._request("post", self.ENDPOINT, body=compacted, options=options)
+
+    def get(self, id: str, options: Optional[RequestOptions] = None) -> Any:
+        """Fetch the current status of an edit-image task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current edit-image status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}", options=options)

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/resources/text_to_image.py

@@ -0,0 +1,58 @@
+"""GPT Image 2.5 text-to-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import Resource, RequestOptions
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedTextToImageResponse,
+    TextToImageResponse,
+)
+
+
+class TextToImage(Resource):
+    """Generate images from text prompts with GPT Image 2.5."""
+
+    ENDPOINT = "/api/v1/gpt_image_2_5/text_to_image"
+
+    RESPONSE_CLASS = TextToImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToImageResponse
+
+    def run(self, options: Optional[RequestOptions] = None, **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(options=options, **params)
+        return self._poll_until_complete(lambda: self.get(task.id, options=options))
+
+    def create(self, options: Optional[RequestOptions] = None, **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_contract(CONTRACT["text-to-image"], compacted)
+        return self._request("post", self.ENDPOINT, body=compacted, options=options)
+
+    def get(self, id: str, options: Optional[RequestOptions] = None) -> 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}", options=options)

runapi_gpt_image_2_5-0.1.1/src/runapi/gpt_image_2_5/types.py

@@ -0,0 +1,30 @@
+"""GPT Image 2.5 model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+
+class Image(BaseModel):
+    url = optional(str)
+
+
+class TextToImageResponse(TaskResponse):
+    """Task status/result for GPT Image 2.5 text-to-image."""
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+    task_replayed = optional(bool)
+    images = optional([lambda: Image])
+    error = optional(str)
+
+
+EditImageResponse = TextToImageResponse
+
+
+class CompletedTextToImageResponse(TextToImageResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    images = required([lambda: Image])
+
+
+CompletedEditImageResponse = CompletedTextToImageResponse

runapi_gpt_image_2_5-0.1.1/tests/test_client.py

@@ -0,0 +1,155 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.gpt_image_2_5 import GptImage25Client
+from runapi.gpt_image_2_5.resources.edit_image import EditImage
+from runapi.gpt_image_2_5.resources.text_to_image import TextToImage
+from runapi.gpt_image_2_5.types import CompletedTextToImageResponse, TextToImageResponse
+
+
+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(GptImage25Client(api_key="k", http_client=FakeHttp()), GptImage25Client)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(GptImage25Client(http_client=FakeHttp()), GptImage25Client)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(GptImage25Client(http_client=FakeHttp()), GptImage25Client)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        GptImage25Client()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = GptImage25Client(api_key="k", http_client=fake)
+    assert client.text_to_image._http is fake
+    assert client.edit_image._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_image, TextToImage)
+    assert isinstance(client.edit_image, EditImage)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending", "task_replayed": True})
+    client = GptImage25Client(api_key="k", http_client=fake)
+    result = client.text_to_image.create(
+        model="gpt-image-2.5-flare", prompt="hello world", aspect_ratio="1:1", output_resolution=None
+    )
+    assert fake.calls == [
+        ("post", "/api/v1/gpt_image_2_5/text_to_image", {"model": "gpt-image-2.5-flare", "prompt": "hello world", "aspect_ratio": "1:1"}),
+    ]
+    assert isinstance(result, TextToImageResponse)
+    assert result.task_replayed is True
+
+
+def test_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = GptImage25Client(api_key="k", http_client=fake)
+    client.text_to_image.get("t1")
+    assert fake.calls == [("get", "/api/v1/gpt_image_2_5/text_to_image/t1", None)]
+
+
+def test_edit_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GptImage25Client(api_key="k", http_client=fake)
+    client.edit_image.create(
+        model="gpt-image-2.5-flare",
+        prompt="oil painting",
+        source_image_urls=["https://x/a.png"],
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/gpt_image_2_5/edit_image",
+            {"model": "gpt-image-2.5-flare", "prompt": "oil painting", "source_image_urls": ["https://x/a.png"]},
+        ),
+    ]
+
+
+def test_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "images": [{"url": "https://x/y.png"}]},
+    )
+    client = GptImage25Client(api_key="k", http_client=fake)
+    result = client.text_to_image.run(model="gpt-image-2.5-flare", prompt="a serene lake")
+    assert isinstance(result, CompletedTextToImageResponse)
+    assert result.images[0].url == "https://x/y.png"
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_requires_model():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: gpt-image-2.5-flare"):
+        client.text_to_image.create(prompt="hi there")
+
+
+def test_requires_prompt():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.text_to_image.create(model="gpt-image-2.5-flare")
+
+
+def test_rejects_unknown_model():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: gpt-image-2.5-flare"):
+        client.text_to_image.create(model="nope", prompt="hi there")
+
+
+def test_rejects_invalid_aspect_ratio():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="aspect_ratio must be one of"):
+        client.text_to_image.create(model="gpt-image-2.5-flare", prompt="hi there", aspect_ratio="5:5")
+
+
+def test_rejects_invalid_output_resolution():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="output_resolution must be one of"):
+        client.text_to_image.create(model="gpt-image-2.5-flare", prompt="hi there", output_resolution="8k")
+
+
+def test_edit_requires_source_image_urls():
+    client = GptImage25Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_image_urls is required"):
+        client.edit_image.create(model="gpt-image-2.5-flare", prompt="make it pop")