runapi-imagen-4 0.1.0__py3-none-any.whl

runapi/imagen_4/__init__.py

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

runapi/imagen_4/client.py

@@ -0,0 +1,29 @@
+"""Imagen 4 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 Imagen4Client:
+    """Imagen 4 text-to-image and remix-image client.
+
+    Example::
+
+        client = Imagen4Client(api_key="sk-...")
+        result = client.text_to_image.run(
+            model="imagen-4", prompt="A neon city street"
+        )
+    """
+
+    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/imagen_4/resources/__init__.py

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

runapi/imagen_4/resources/remix_image.py

@@ -0,0 +1,84 @@
+"""Imagen 4 remix-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    OUTPUT_FORMATS,
+    OUTPUT_RESOLUTIONS,
+    PRO_ASPECT_RATIOS,
+    REMIX_MODELS,
+    CompletedRemixImageResponse,
+    RemixImageResponse,
+)
+
+
+class RemixImage(Resource):
+    """Remix a set of source images with an Imagen 4 pro model."""
+
+    ENDPOINT = "/api/v1/imagen_4/remix_image"
+
+    RESPONSE_CLASS = RemixImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedRemixImageResponse
+
+    SOURCE_IMAGE_URLS_MAX = 8
+
+    def run(self, **params: Any) -> Any:
+        """Remix source images and poll until it completes.
+
+        Args:
+            **params: Remix-image parameters (model, prompt, source_image_urls, ...).
+
+        Returns:
+            The completed task with images.
+        """
+        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, source_image_urls, ...).
+
+        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: The task id.
+
+        Returns:
+            The current task 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:
+            raise ValidationError(f"Invalid model: {model}. Must be one of: {', '.join(REMIX_MODELS)}")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+
+        self._validate_source_image_urls(params)
+        self._validate_optional(params, "aspect_ratio", PRO_ASPECT_RATIOS)
+        self._validate_optional(params, "output_resolution", OUTPUT_RESOLUTIONS)
+        self._validate_optional(params, "output_format", OUTPUT_FORMATS)
+
+    def _validate_source_image_urls(self, params: Dict[str, Any]) -> None:
+        urls = params.get("source_image_urls")
+        if urls is None or (hasattr(urls, "__len__") and len(urls) == 0):
+            raise ValidationError("source_image_urls is required")
+        if hasattr(urls, "__len__") and len(urls) > self.SOURCE_IMAGE_URLS_MAX:
+            raise ValidationError(f"source_image_urls supports up to {self.SOURCE_IMAGE_URLS_MAX} images")

runapi/imagen_4/resources/text_to_image.py

@@ -0,0 +1,81 @@
+"""Imagen 4 text-to-image resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    MODELS,
+    OUTPUT_COUNTS,
+    TEXT_ASPECT_RATIOS,
+    CompletedTextToImageResponse,
+    TextToImageResponse,
+)
+
+
+class TextToImage(Resource):
+    """Generate images from text prompts with Imagen 4 models."""
+
+    ENDPOINT = "/api/v1/imagen_4/text_to_image"
+
+    RESPONSE_CLASS = TextToImageResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToImageResponse
+
+    def run(self, **params: Any) -> Any:
+        """Generate images from text and poll until it completes.
+
+        Args:
+            **params: Text-to-image parameters (model, prompt, ...).
+
+        Returns:
+            The completed task with images.
+        """
+        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: The task id.
+
+        Returns:
+            The current task 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 MODELS:
+            raise ValidationError(f"Invalid model: {model}. Must be: {', '.join(MODELS)}")
+
+        self._validate_text_params(params, model)
+
+    def _validate_text_params(self, params: Dict[str, Any], model: str) -> None:
+        self._validate_optional(params, "aspect_ratio", TEXT_ASPECT_RATIOS)
+        if not params.get("output_count"):
+            return
+
+        if model != "imagen-4-fast":
+            raise ValidationError("output_count is only supported for imagen-4-fast")
+        self._validate_optional(params, "output_count", OUTPUT_COUNTS)

runapi/imagen_4/types.py

@@ -0,0 +1,46 @@
+"""Imagen 4 model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+TEXT_MODELS = ["imagen-4", "imagen-4-fast", "imagen-4-ultra"]
+REMIX_MODELS = ["imagen-4-pro-remix-image"]
+MODELS = TEXT_MODELS + REMIX_MODELS
+TEXT_ASPECT_RATIOS = ["1:1", "16:9", "9:16", "3:4", "4:3"]
+PRO_ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "auto"]
+OUTPUT_RESOLUTIONS = ["1k", "2k", "4k"]
+OUTPUT_FORMATS = ["png", "jpg"]
+OUTPUT_COUNTS = [1, 2, 3, 4]
+
+
+class Image(BaseModel):
+    url = optional(str)
+    origin_url = optional(str)
+
+
+class TextToImageResponse(TaskResponse):
+    """Response for a text-to-image task."""
+
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+    images = optional([lambda: Image])
+    error = optional(str)
+
+
+class CompletedTextToImageResponse(TextToImageResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    images = required([lambda: Image])
+
+
+class RemixImageResponse(TextToImageResponse):
+    """Response for a remix-image task."""
+
+    pass
+
+
+class CompletedRemixImageResponse(CompletedTextToImageResponse):
+    """Narrowed remix-image response from ``run()`` once polling observes completion."""
+
+    pass

runapi_imagen_4-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: runapi-imagen-4
+Version: 0.1.0
+Summary: Imagen 4 text-to-image and remix-image client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/imagen-4
+Project-URL: Documentation, https://runapi.ai/docs#sdk-imagen-4
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,imagen-4,remix-image,runapi,sdk,text-to-image
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Imagen 4 Python SDK for RunAPI
+
+The Imagen 4 Python SDK is the language-specific package for Imagen 4 on RunAPI.
+Use it for text-to-image and remix-image 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/imagen-4; for API reference, use
+https://runapi.ai/docs#imagen-4; for SDK docs, use https://runapi.ai/docs#sdk-imagen-4.
+
+## Install
+
+```bash
+pip install runapi-imagen-4
+```
+
+## Quick start
+
+```python
+from runapi.imagen_4 import Imagen4Client
+
+client = Imagen4Client()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_image.create(
+    model="imagen-4",
+    prompt="A neon city street after rain, cinematic",
+    aspect_ratio="16:9",
+)
+status = client.text_to_image.get(task.id)
+
+remix = client.remix_image.create(
+    model="imagen-4-pro-remix-image",
+    prompt="Make it golden hour",
+    source_image_urls=["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.text_to_image.run(
+    model="imagen-4",
+    prompt="A serene mountain lake at dawn",
+)
+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.imagen_4` 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/imagen-4
+- SDK docs: https://runapi.ai/docs#sdk-imagen-4
+- Product docs: https://runapi.ai/docs#imagen-4
+- Pricing and rate limits: https://runapi.ai/models/imagen-4
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_imagen_4-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+runapi/imagen_4/__init__.py,sha256=3IqQXNgvfEzVfaPAggf9l46IB6yp3BMVW_ugr4R-x-A,464
+runapi/imagen_4/client.py,sha256=Ke1OiqJOmCLdADRIfH9JSF_kouM5-An5zgqlnvj0DR0,889
+runapi/imagen_4/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runapi/imagen_4/types.py,sha256=e4hXY2x7UtPiRakHIrIg55Jju38PwrD9QYz2MS8auMo,1333
+runapi/imagen_4/resources/__init__.py,sha256=_qgSycx9qXoXiFBejkxC4N-fuGhZ9MVuqjGUYbRWApI,116
+runapi/imagen_4/resources/remix_image.py,sha256=4fiiLs-SKdcjqZoMTGvvzB60fAsmzQncn9l6rqI1HHY,2847
+runapi/imagen_4/resources/text_to_image.py,sha256=mcoKX3V6UBBpH7IzFRiLYQizTU0kPSM0Xpwvr1OoDqc,2502
+runapi_imagen_4-0.1.0.dist-info/METADATA,sha256=K5qqiQfnoxKyJHRZg52vWBzLOz5Tk2IcQT3nxgV8h2A,2653
+runapi_imagen_4-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+runapi_imagen_4-0.1.0.dist-info/RECORD,,

runapi_imagen_4-0.1.0.dist-info/WHEEL

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