runapi-grok-imagine 0.1.0__tar.gz

runapi_grok_imagine-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_grok_imagine-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: runapi-grok-imagine
+Version: 0.1.0
+Summary: Grok-Imagine multimodal generation client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/grok-imagine
+Project-URL: Documentation, https://runapi.ai/docs#sdk-grok-imagine
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,grok-imagine,image-to-video,runapi,sdk,text-to-image,text-to-video
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Grok-Imagine Python SDK for RunAPI
+
+The Grok-Imagine Python SDK is the language-specific package for Grok-Imagine on
+RunAPI. Use it for text-to-video, image-to-video, text-to-image, and image
+editing 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/grok-imagine; for API reference,
+use https://runapi.ai/docs#grok-imagine; for SDK docs, use
+https://runapi.ai/docs#sdk-grok-imagine.
+
+## Install
+
+```bash
+pip install runapi-grok-imagine
+```
+
+## Quick start
+
+```python
+from runapi.grok_imagine import GrokImagineClient
+
+client = GrokImagineClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="grok-imagine-text-to-video",
+    prompt="A drone shot over a neon cityscape at night",
+    output_resolution="720p",
+)
+status = client.text_to_video.get(task.id)
+
+image = client.text_to_image.create(
+    model="grok-imagine-text-to-image",
+    prompt="A watercolor fox in a snowy forest",
+    aspect_ratio="16:9",
+)
+```
+
+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_video.run(
+    model="grok-imagine-text-to-video",
+    prompt="A serene mountain lake at dawn",
+)
+print(result.videos[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 media 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.grok_imagine` error
+classes when building media jobs or scripts. The available resources are
+`text_to_video`, `image_to_video`, `text_to_image`, `edit_image`, `extensions`,
+and `upscales`. The `extensions` and `upscales` resources take a prior task's
+`source_task_id`. 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/grok-imagine
+- SDK docs: https://runapi.ai/docs#sdk-grok-imagine
+- Product docs: https://runapi.ai/docs#grok-imagine
+- Pricing and rate limits: https://runapi.ai/models/grok-imagine
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_grok_imagine-0.1.0/README.md

@@ -0,0 +1,76 @@
+# Grok-Imagine Python SDK for RunAPI
+
+The Grok-Imagine Python SDK is the language-specific package for Grok-Imagine on
+RunAPI. Use it for text-to-video, image-to-video, text-to-image, and image
+editing 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/grok-imagine; for API reference,
+use https://runapi.ai/docs#grok-imagine; for SDK docs, use
+https://runapi.ai/docs#sdk-grok-imagine.
+
+## Install
+
+```bash
+pip install runapi-grok-imagine
+```
+
+## Quick start
+
+```python
+from runapi.grok_imagine import GrokImagineClient
+
+client = GrokImagineClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="grok-imagine-text-to-video",
+    prompt="A drone shot over a neon cityscape at night",
+    output_resolution="720p",
+)
+status = client.text_to_video.get(task.id)
+
+image = client.text_to_image.create(
+    model="grok-imagine-text-to-image",
+    prompt="A watercolor fox in a snowy forest",
+    aspect_ratio="16:9",
+)
+```
+
+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_video.run(
+    model="grok-imagine-text-to-video",
+    prompt="A serene mountain lake at dawn",
+)
+print(result.videos[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 media 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.grok_imagine` error
+classes when building media jobs or scripts. The available resources are
+`text_to_video`, `image_to_video`, `text_to_image`, `edit_image`, `extensions`,
+and `upscales`. The `extensions` and `upscales` resources take a prior task's
+`source_task_id`. 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/grok-imagine
+- SDK docs: https://runapi.ai/docs#sdk-grok-imagine
+- Product docs: https://runapi.ai/docs#grok-imagine
+- Pricing and rate limits: https://runapi.ai/models/grok-imagine
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_grok_imagine-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-grok-imagine"
+version = "0.1.0"
+description = "Grok-Imagine multimodal generation client for RunAPI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "grok-imagine", "text-to-video", "image-to-video", "text-to-image", "ai", "sdk"]
+dependencies = ["runapi-core"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/grok-imagine"
+Documentation = "https://runapi.ai/docs#sdk-grok-imagine"
+
+[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_grok_imagine-0.1.0/src/runapi/grok_imagine/__init__.py

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

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/client.py

@@ -0,0 +1,39 @@
+"""Grok-Imagine client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.edit_image import EditImage
+from .resources.extensions import Extensions
+from .resources.image_to_video import ImageToVideo
+from .resources.text_to_image import TextToImage
+from .resources.text_to_video import TextToVideo
+from .resources.upscales import Upscales
+
+
+class GrokImagineClient:
+    """Grok-Imagine multimodal generation client.
+
+    Example::
+
+        client = GrokImagineClient(api_key="sk-...")
+        result = client.text_to_video.run(
+            model="grok-imagine-text-to-video",
+            prompt="A drone shot over a neon cityscape",
+            output_resolution="720p",
+        )
+    """
+
+    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_video = TextToVideo(http)
+        self.image_to_video = ImageToVideo(http)
+        self.text_to_image = TextToImage(http)
+        self.edit_image = EditImage(http)
+        self.extensions = Extensions(http)
+        self.upscales = Upscales(http)

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/__init__.py

@@ -0,0 +1,15 @@
+from .edit_image import EditImage
+from .extensions import Extensions
+from .image_to_video import ImageToVideo
+from .text_to_image import TextToImage
+from .text_to_video import TextToVideo
+from .upscales import Upscales
+
+__all__ = [
+    "TextToVideo",
+    "ImageToVideo",
+    "TextToImage",
+    "EditImage",
+    "Extensions",
+    "Upscales",
+]

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/edit_image.py

@@ -0,0 +1,64 @@
+"""Grok-Imagine prompt-guided image editing resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    EDIT_IMAGE_MODEL,
+    CompletedImageTaskResponse,
+    ImageTaskResponse,
+)
+
+
+class EditImage(Resource):
+    """Edit an image with a text prompt using Grok-Imagine."""
+
+    ENDPOINT = "/api/v1/grok_imagine/edit_image"
+
+    RESPONSE_CLASS = ImageTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedImageTaskResponse
+
+    def run(self, **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(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **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_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> 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}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if params.get("model") != EDIT_IMAGE_MODEL:
+            raise ValidationError("model is required")
+        if not params.get("source_image_url"):
+            raise ValidationError("source_image_url is required")

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/extensions.py

@@ -0,0 +1,78 @@
+"""Grok-Imagine video extension resource.
+
+Takes a prior grok-imagine video source_task_id and extends it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    EXTENSION_DURATION_SECONDS,
+    CompletedVideoTaskResponse,
+    VideoTaskResponse,
+)
+
+
+class Extensions(Resource):
+    """Extend a previously generated Grok-Imagine video."""
+
+    ENDPOINT = "/api/v1/grok_imagine/extend_video"
+
+    RESPONSE_CLASS = VideoTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedVideoTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a video extension task and poll until it completes.
+
+        Args:
+            **params: Video extension parameters (model, prompt, ...).
+
+        Returns:
+            The completed video extension response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a video extension task and return immediately with an id.
+
+        Args:
+            **params: Video extension 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 video extension task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current video extension status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if not params.get("source_task_id"):
+            raise ValidationError("source_task_id is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+        # start_seconds is numeric and 0 (extend from the beginning) is valid, so
+        # check for absence explicitly rather than treating 0 as missing.
+        if params.get("start_seconds") is None:
+            raise ValidationError("start_seconds is required")
+
+        extension_duration_seconds = params.get("extension_duration_seconds")
+        if not extension_duration_seconds:
+            raise ValidationError("extension_duration_seconds is required")
+        if extension_duration_seconds not in EXTENSION_DURATION_SECONDS:
+            joined = ", ".join(str(value) for value in EXTENSION_DURATION_SECONDS)
+            raise ValidationError(f"extension_duration_seconds must be one of: {joined}")

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/image_to_video.py

@@ -0,0 +1,97 @@
+"""Grok-Imagine image-to-video generation resource.
+
+Accepts either external source_image_urls or a prior text-to-image
+source_task_id (+ index).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    ASPECT_RATIOS,
+    IMAGE_TO_VIDEO_MODEL,
+    INDEX_RANGE,
+    MOTION_STYLES,
+    RESOLUTIONS,
+    CompletedVideoTaskResponse,
+    VideoTaskResponse,
+)
+
+
+class ImageToVideo(Resource):
+    """Generate videos from a source image with Grok-Imagine."""
+
+    ENDPOINT = "/api/v1/grok_imagine/image_to_video"
+
+    RESPONSE_CLASS = VideoTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedVideoTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create an image-to-video task and poll until it completes.
+
+        Args:
+            **params: Image-to-video parameters (model, prompt, ...).
+
+        Returns:
+            The completed image-to-video response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create an image-to-video task and return immediately with an id.
+
+        Args:
+            **params: Image-to-video 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 an image-to-video task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current image-to-video status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if params.get("model") != IMAGE_TO_VIDEO_MODEL:
+            raise ValidationError("model is required")
+
+        source_image_urls = params.get("source_image_urls")
+        source_task_id = params.get("source_task_id")
+
+        if source_image_urls and len(source_image_urls) > 0 and source_task_id:
+            raise ValidationError("Provide either source_image_urls or source_task_id, not both")
+        if (not source_image_urls or len(source_image_urls) == 0) and not source_task_id:
+            raise ValidationError("One of source_image_urls or source_task_id is required")
+        if source_image_urls and len(source_image_urls) > 1:
+            raise ValidationError("source_image_urls supports at most 1 entry")
+
+        if source_task_id:
+            index = params.get("index")
+            if index is not None:
+                try:
+                    value = None if isinstance(index, bool) else int(index)
+                except (TypeError, ValueError):
+                    value = None
+                if value is None or value not in INDEX_RANGE:
+                    raise ValidationError("index must be an integer between 0 and 5")
+
+        self._validate_optional(params, "aspect_ratio", ASPECT_RATIOS)
+        self._validate_optional(params, "motion_style", MOTION_STYLES)
+        self._validate_optional(params, "output_resolution", RESOLUTIONS)
+
+        if str(params.get("motion_style")) == "spicy" and source_image_urls and len(source_image_urls) > 0:
+            raise ValidationError("spicy motion_style requires a source_task_id source image.")

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/text_to_image.py

@@ -0,0 +1,66 @@
+"""Grok-Imagine text-to-image generation resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    ASPECT_RATIOS,
+    TEXT_TO_IMAGE_MODEL,
+    CompletedImageTaskResponse,
+    ImageTaskResponse,
+)
+
+
+class TextToImage(Resource):
+    """Generate images from text prompts with Grok-Imagine."""
+
+    ENDPOINT = "/api/v1/grok_imagine/text_to_image"
+
+    RESPONSE_CLASS = ImageTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedImageTaskResponse
+
+    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 params.get("model") != TEXT_TO_IMAGE_MODEL:
+            raise ValidationError("model is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+        self._validate_optional(params, "aspect_ratio", ASPECT_RATIOS)

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/text_to_video.py

@@ -0,0 +1,80 @@
+"""Grok-Imagine text-to-video generation resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    ASPECT_RATIOS,
+    DURATION_RANGE,
+    MOTION_STYLES,
+    RESOLUTIONS,
+    TEXT_TO_VIDEO_MODEL,
+    CompletedVideoTaskResponse,
+    VideoTaskResponse,
+)
+
+
+class TextToVideo(Resource):
+    """Generate videos from text prompts with Grok-Imagine."""
+
+    ENDPOINT = "/api/v1/grok_imagine/text_to_video"
+
+    RESPONSE_CLASS = VideoTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedVideoTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a text-to-video task and poll until it completes.
+
+        Args:
+            **params: Text-to-video parameters (model, prompt, ...).
+
+        Returns:
+            The completed text-to-video 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-video task and return immediately with an id.
+
+        Args:
+            **params: Text-to-video 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-video task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current text-to-video status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if params.get("model") != TEXT_TO_VIDEO_MODEL:
+            raise ValidationError("model is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+        self._validate_optional(params, "aspect_ratio", ASPECT_RATIOS)
+        self._validate_optional(params, "motion_style", MOTION_STYLES)
+        self._validate_optional(params, "output_resolution", RESOLUTIONS)
+
+        duration_seconds = params.get("duration_seconds")
+        if duration_seconds:
+            try:
+                value = int(duration_seconds)
+            except (TypeError, ValueError):
+                value = None
+            if value is None or value not in DURATION_RANGE:
+                raise ValidationError("duration_seconds must be an integer between 6 and 30")

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/resources/upscales.py

@@ -0,0 +1,64 @@
+"""Grok-Imagine video upscale resource.
+
+Takes a prior grok-imagine video source_task_id and upscales it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    CompletedVideoTaskResponse,
+    VideoTaskResponse,
+)
+
+
+class Upscales(Resource):
+    """Upscale a previously generated Grok-Imagine video."""
+
+    ENDPOINT = "/api/v1/grok_imagine/upscale_image"
+
+    RESPONSE_CLASS = VideoTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedVideoTaskResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create a video upscale task and poll until it completes.
+
+        Args:
+            **params: Video upscale parameters (model, prompt, ...).
+
+        Returns:
+            The completed video upscale response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a video upscale task and return immediately with an id.
+
+        Args:
+            **params: Video upscale 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 video upscale task.
+
+        Args:
+            id: Task id.
+
+        Returns:
+            The current video upscale status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if not params.get("source_task_id"):
+            raise ValidationError("source_task_id is required")

runapi_grok_imagine-0.1.0/src/runapi/grok_imagine/types.py

@@ -0,0 +1,50 @@
+"""Grok-Imagine model identifiers, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+TEXT_TO_VIDEO_MODEL = "grok-imagine-text-to-video"
+IMAGE_TO_VIDEO_MODEL = "grok-imagine-image-to-video"
+TEXT_TO_IMAGE_MODEL = "grok-imagine-text-to-image"
+EDIT_IMAGE_MODEL = "grok-imagine-edit-image"
+
+ASPECT_RATIOS = ["2:3", "3:2", "1:1", "16:9", "9:16"]
+MOTION_STYLES = ["fun", "normal", "spicy"]
+RESOLUTIONS = ["480p", "720p"]
+DURATION_RANGE = range(6, 31)
+EXTENSION_DURATION_SECONDS = [6, 10]
+INDEX_RANGE = range(0, 6)
+
+
+class MediaUrl(BaseModel):
+    url = optional(str)
+
+
+class AsyncTaskResponse(TaskResponse):
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+
+
+class VideoTaskResponse(AsyncTaskResponse):
+    """Task status/result for Grok-Imagine video generation."""
+    videos = optional([lambda: MediaUrl])
+    error = optional(str)
+
+
+class CompletedVideoTaskResponse(VideoTaskResponse):
+    """Narrowed video response from ``run()`` once polling observes completion."""
+
+    videos = required([lambda: MediaUrl])
+
+
+class ImageTaskResponse(AsyncTaskResponse):
+    """Task status/result for Grok-Imagine image generation."""
+    images = optional([lambda: MediaUrl])
+    error = optional(str)
+
+
+class CompletedImageTaskResponse(ImageTaskResponse):
+    """Narrowed image response from ``run()`` once polling observes completion."""
+
+    images = required([lambda: MediaUrl])

runapi_grok_imagine-0.1.0/tests/test_client.py

@@ -0,0 +1,352 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.grok_imagine import GrokImagineClient
+from runapi.grok_imagine.resources.edit_image import EditImage
+from runapi.grok_imagine.resources.extensions import Extensions
+from runapi.grok_imagine.resources.image_to_video import ImageToVideo
+from runapi.grok_imagine.resources.text_to_image import TextToImage
+from runapi.grok_imagine.resources.text_to_video import TextToVideo
+from runapi.grok_imagine.resources.upscales import Upscales
+from runapi.grok_imagine.types import (
+    CompletedImageTaskResponse,
+    CompletedVideoTaskResponse,
+    ImageTaskResponse,
+    VideoTaskResponse,
+)
+
+
+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(GrokImagineClient(api_key="k", http_client=FakeHttp()), GrokImagineClient)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(GrokImagineClient(http_client=FakeHttp()), GrokImagineClient)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(GrokImagineClient(http_client=FakeHttp()), GrokImagineClient)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        GrokImagineClient()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    assert client.text_to_video._http is fake
+    assert client.image_to_video._http is fake
+    assert client.text_to_image._http is fake
+    assert client.edit_image._http is fake
+    assert client.extensions._http is fake
+    assert client.upscales._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_video, TextToVideo)
+    assert isinstance(client.image_to_video, ImageToVideo)
+    assert isinstance(client.text_to_image, TextToImage)
+    assert isinstance(client.edit_image, EditImage)
+    assert isinstance(client.extensions, Extensions)
+    assert isinstance(client.upscales, Upscales)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_text_to_video_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    result = client.text_to_video.create(
+        model="grok-imagine-text-to-video",
+        prompt="a neon city",
+        output_resolution="720p",
+        motion_style=None,
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/grok_imagine/text_to_video",
+            {"model": "grok-imagine-text-to-video", "prompt": "a neon city", "output_resolution": "720p"},
+        ),
+    ]
+    assert isinstance(result, VideoTaskResponse)
+
+
+def test_text_to_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    client.text_to_video.get("t1")
+    assert fake.calls == [("get", "/api/v1/grok_imagine/text_to_video/t1", None)]
+
+
+def test_text_to_image_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    result = client.text_to_image.create(model="grok-imagine-text-to-image", prompt="a fox", aspect_ratio="1:1")
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/grok_imagine/text_to_image",
+            {"model": "grok-imagine-text-to-image", "prompt": "a fox", "aspect_ratio": "1:1"},
+        ),
+    ]
+    assert isinstance(result, ImageTaskResponse)
+
+
+def test_image_to_video_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    client.image_to_video.create(
+        model="grok-imagine-image-to-video", source_image_urls=["https://x/a.png"]
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/grok_imagine/image_to_video",
+            {"model": "grok-imagine-image-to-video", "source_image_urls": ["https://x/a.png"]},
+        ),
+    ]
+
+
+def test_edit_image_create_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    client.edit_image.create(model="grok-imagine-edit-image", source_image_url="https://x/a.png")
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/grok_imagine/edit_image",
+            {"model": "grok-imagine-edit-image", "source_image_url": "https://x/a.png"},
+        ),
+    ]
+
+
+def test_extensions_create_uses_task_id_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    result = client.extensions.create(
+        source_task_id="src_1",
+        prompt="keep going",
+        start_seconds=4,
+        extension_duration_seconds=6,
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/grok_imagine/extend_video",
+            {
+                "source_task_id": "src_1",
+                "prompt": "keep going",
+                "start_seconds": 4,
+                "extension_duration_seconds": 6,
+            },
+        ),
+    ]
+    assert isinstance(result, VideoTaskResponse)
+
+
+def test_upscales_create_uses_task_id_shape():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    client.upscales.create(source_task_id="src_1")
+    assert fake.calls == [
+        ("post", "/api/v1/grok_imagine/upscale_image", {"source_task_id": "src_1"}),
+    ]
+
+
+def test_text_to_video_non_numeric_duration_raises_validation_error():
+    # Regression: a non-numeric duration must raise the SDK's ValidationError,
+    # not a bare ValueError from int(). Fails if int() is unguarded again.
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="duration_seconds must be an integer between 6 and 30"):
+        client.text_to_video.create(
+            model="grok-imagine-text-to-video", prompt="a fox", duration_seconds="6s"
+        )
+
+
+def test_image_to_video_non_numeric_index_raises_validation_error():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="index must be an integer between 0 and 5"):
+        client.image_to_video.create(
+            model="grok-imagine-image-to-video", source_task_id="src_1", index="abc"
+        )
+
+
+def test_extensions_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    client.extensions.get("t1")
+    assert fake.calls == [("get", "/api/v1/grok_imagine/extend_video/t1", None)]
+
+
+# --- run narrowing --------------------------------------------------------
+
+
+def test_run_narrows_completed_video_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "videos": [{"url": "https://x/y.mp4"}]},
+    )
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    result = client.text_to_video.run(model="grok-imagine-text-to-video", prompt="a lake")
+    assert isinstance(result, CompletedVideoTaskResponse)
+    assert result.videos[0].url == "https://x/y.mp4"
+
+
+def test_run_narrows_completed_image_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "images": [{"url": "https://x/y.png"}]},
+    )
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    result = client.text_to_image.run(model="grok-imagine-text-to-image", prompt="a fox")
+    assert isinstance(result, CompletedImageTaskResponse)
+    assert result.images[0].url == "https://x/y.png"
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_text_to_video_requires_model():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model is required"):
+        client.text_to_video.create(prompt="hi")
+
+
+def test_text_to_video_requires_prompt():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.text_to_video.create(model="grok-imagine-text-to-video")
+
+
+def test_text_to_video_rejects_bad_aspect_ratio():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid aspect_ratio"):
+        client.text_to_video.create(model="grok-imagine-text-to-video", prompt="hi", aspect_ratio="4:5")
+
+
+def test_text_to_video_duration_range():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="duration_seconds must be an integer between 6 and 30"):
+        client.text_to_video.create(model="grok-imagine-text-to-video", prompt="hi", duration_seconds=99)
+
+
+def test_image_to_video_requires_a_source():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="One of source_image_urls or source_task_id is required"):
+        client.image_to_video.create(model="grok-imagine-image-to-video")
+
+
+def test_image_to_video_rejects_both_sources():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="not both"):
+        client.image_to_video.create(
+            model="grok-imagine-image-to-video",
+            source_image_urls=["https://x/a.png"],
+            source_task_id="src_1",
+        )
+
+
+def test_image_to_video_rejects_multiple_urls():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="supports at most 1 entry"):
+        client.image_to_video.create(
+            model="grok-imagine-image-to-video",
+            source_image_urls=["https://x/a.png", "https://x/b.png"],
+        )
+
+
+def test_image_to_video_index_range():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="index must be an integer between 0 and 5"):
+        client.image_to_video.create(
+            model="grok-imagine-image-to-video", source_task_id="src_1", index=9
+        )
+
+
+def test_image_to_video_index_rejects_bool():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="index must be an integer between 0 and 5"):
+        client.image_to_video.create(
+            model="grok-imagine-image-to-video", source_task_id="src_1", index=True
+        )
+
+
+def test_image_to_video_spicy_requires_source_task_id():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="spicy motion_style requires a source_task_id source image."):
+        client.image_to_video.create(
+            model="grok-imagine-image-to-video",
+            source_image_urls=["https://x/a.png"],
+            motion_style="spicy",
+        )
+
+
+def test_edit_image_requires_source_image_url():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_image_url is required"):
+        client.edit_image.create(model="grok-imagine-edit-image")
+
+
+def test_extensions_requires_source_task_id():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_task_id is required"):
+        client.extensions.create(prompt="go", start_seconds=4, extension_duration_seconds=6)
+
+
+def test_extensions_rejects_bad_duration():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="extension_duration_seconds must be one of: 6, 10"):
+        client.extensions.create(
+            source_task_id="src_1", prompt="go", start_seconds=4, extension_duration_seconds=8
+        )
+
+
+def test_upscales_requires_source_task_id():
+    client = GrokImagineClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_task_id is required"):
+        client.upscales.create()
+
+
+def test_extensions_accepts_zero_start_seconds():
+    # Regression: start_seconds=0 (extend from the beginning) is valid and must
+    # not be rejected as missing by a truthiness check.
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = GrokImagineClient(api_key="k", http_client=fake)
+    client.extensions.create(
+        source_task_id="src_1", prompt="go", start_seconds=0, extension_duration_seconds=6
+    )
+    _, _, body = fake.calls[0]
+    assert body["start_seconds"] == 0