runapi-minimax-h3 0.1.0__tar.gz

runapi_minimax_h3-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 RunAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runapi_minimax_h3-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: runapi-minimax-h3
+Version: 0.1.0
+Summary: RunAPI MiniMax H3 SDK for text-to-video, reference-media, and image-to-video workflows in JavaScript, Python, Ruby, Go, Java, and PHP
+Project-URL: Homepage, https://runapi.ai/models/minimax-h3
+Project-URL: Documentation, https://runapi.ai/docs/resources/sdks
+Project-URL: Source, https://github.com/runapi-ai/minimax-h3-sdk
+Project-URL: Issues, https://github.com/runapi-ai/minimax-h3-sdk/issues
+Project-URL: Changelog, https://github.com/runapi-ai/minimax-h3-sdk/blob/main/CHANGELOG.md
+Project-URL: Release Notes, https://github.com/runapi-ai/minimax-h3-sdk/releases/tag/python%2Fv0.1.0
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: api,golang,gradle,image-to-video,java,maven,minimax-h3,python,ruby,runapi,runapi-ai,sdk,text-to-video,typescript,video-generation
+Requires-Python: >=3.9
+Requires-Dist: runapi-core>=0.4.0
+Description-Content-Type: text/markdown
+
+# MiniMax H3 API Python SDK for RunAPI
+
+Use `runapi-minimax-h3` for MiniMax H3 video tasks in Python.
+
+```bash
+pip install runapi-minimax-h3
+```
+
+```python
+from runapi.minimax_h3 import MiniMaxH3Client
+
+client = MiniMaxH3Client()
+result = client.text_to_video.run(
+    model="minimax-h3",
+    prompt="A cinematic tracking shot through a rain-soaked city",
+    aspect_ratio="16:9",
+)
+print(result.videos[0].url)
+```
+
+Use `text_to_video` for prompt-only or reference-media generation. Use `image_to_video` with a first frame, last frame, or both. Each resource provides `create`, `get`, and `run`.
+
+- [Model reference](https://runapi.ai/models/minimax-h3)
+- [API reference](https://runapi.ai/docs/api/minimax-h3/text-to-video)
+- [Pricing and rate limits](https://runapi.ai/models/minimax-h3)
+
+Licensed under the Apache License, Version 2.0.

runapi_minimax_h3-0.1.0/README.md

@@ -0,0 +1,27 @@
+# MiniMax H3 API Python SDK for RunAPI
+
+Use `runapi-minimax-h3` for MiniMax H3 video tasks in Python.
+
+```bash
+pip install runapi-minimax-h3
+```
+
+```python
+from runapi.minimax_h3 import MiniMaxH3Client
+
+client = MiniMaxH3Client()
+result = client.text_to_video.run(
+    model="minimax-h3",
+    prompt="A cinematic tracking shot through a rain-soaked city",
+    aspect_ratio="16:9",
+)
+print(result.videos[0].url)
+```
+
+Use `text_to_video` for prompt-only or reference-media generation. Use `image_to_video` with a first frame, last frame, or both. Each resource provides `create`, `get`, and `run`.
+
+- [Model reference](https://runapi.ai/models/minimax-h3)
+- [API reference](https://runapi.ai/docs/api/minimax-h3/text-to-video)
+- [Pricing and rate limits](https://runapi.ai/models/minimax-h3)
+
+Licensed under the Apache License, Version 2.0.

runapi_minimax_h3-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-minimax-h3"
+version = "0.1.0"
+description = "RunAPI MiniMax H3 SDK for text-to-video, reference-media, and image-to-video 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", "minimax-h3", "api", "sdk", "typescript", "python", "ruby", "golang", "java", "maven", "gradle", "video-generation", "text-to-video", "image-to-video"]
+dependencies = ["runapi-core>=0.4.0"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/minimax-h3"
+Documentation = "https://runapi.ai/docs/resources/sdks"
+Source = "https://github.com/runapi-ai/minimax-h3-sdk"
+Issues = "https://github.com/runapi-ai/minimax-h3-sdk/issues"
+Changelog = "https://github.com/runapi-ai/minimax-h3-sdk/blob/main/CHANGELOG.md"
+"Release Notes" = "https://github.com/runapi-ai/minimax-h3-sdk/releases/tag/python%2Fv0.1.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.runapi]
+slug = "minimax-h3"

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/__init__.py

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

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/client.py

@@ -0,0 +1,28 @@
+"""MiniMax H3 client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ProviderClient
+
+from .resources.image_to_video import ImageToVideo
+from .resources.text_to_video import TextToVideo
+
+
+class MiniMaxH3Client(ProviderClient):
+    """MiniMax H3 text-to-video and image-to-video client.
+
+    Example::
+
+        client = MiniMaxH3Client(api_key="sk-...")
+        result = client.text_to_video.run(
+            model="minimax-h3", prompt="A neon city street"
+        )
+    """
+
+    def __init__(self, api_key: Optional[str] = None, **options: Any) -> None:
+        super().__init__(api_key, **options)
+        http = self._http
+        self.text_to_video = TextToVideo(http)
+        self.image_to_video = ImageToVideo(http)

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/contract_gen.py

@@ -0,0 +1,84 @@
+CONTRACT = {
+    "image-to-video": {
+        "models": ["minimax-h3"],
+        "fields_by_model": {
+            "minimax-h3": {
+                "duration_seconds": {
+                    "enum": [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+                    "type": "integer"
+                },
+                "model": {
+                    "required": True
+                },
+                "output_resolution": {
+                    "enum": ["768p", "2k"]
+                },
+                "prompt": {
+                    "required": True,
+                    "min": 1,
+                    "max": 7000,
+                    "length": True
+                }
+            }
+        },
+        "rules": [{
+            "required_any": ["first_frame_image_url", "last_frame_image_url"]
+        }]
+    },
+    "text-to-video": {
+        "models": ["minimax-h3"],
+        "fields_by_model": {
+            "minimax-h3": {
+                "aspect_ratio": {
+                    "enum": ["adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"]
+                },
+                "duration_seconds": {
+                    "enum": [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+                    "type": "integer"
+                },
+                "model": {
+                    "required": True
+                },
+                "output_resolution": {
+                    "enum": ["768p", "2k"]
+                },
+                "prompt": {
+                    "required": True,
+                    "min": 1,
+                    "max": 7000,
+                    "length": True
+                },
+                "reference_audio_urls": {
+                    "max_items": 3
+                },
+                "reference_image_urls": {
+                    "max_items": 9
+                },
+                "reference_video_urls": {
+                    "max_items": 3
+                }
+            }
+        },
+        "rules": [{
+            "when": {
+                "reference_audio_urls": {
+                    "present": True
+                }
+            },
+            "required_any": ["reference_image_urls", "reference_video_urls"]
+        }, {
+            "enum": {
+                "aspect_ratio": ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"]
+            },
+            "when": {
+                "reference_image_urls": {
+                    "present": False
+                },
+                "reference_video_urls": {
+                    "present": False
+                }
+            },
+            "required": ["aspect_ratio"]
+        }]
+    }
+}

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/resources/__init__.py

@@ -0,0 +1,4 @@
+from .image_to_video import ImageToVideo
+from .text_to_video import TextToVideo
+
+__all__ = ["TextToVideo", "ImageToVideo"]

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/resources/image_to_video.py

@@ -0,0 +1,61 @@
+"""MiniMax H3 image-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from runapi.core import Resource, RequestOptions
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedVideoTaskResponse,
+    VideoTaskResponse,
+)
+
+
+class ImageToVideo(Resource):
+    """Generate videos from a source image with MiniMax H3 models."""
+
+    ENDPOINT = "/api/v1/minimax_h3/image_to_video"
+
+    RESPONSE_CLASS = VideoTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedVideoTaskResponse
+
+    def run(self, options: Optional[RequestOptions] = None, **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 task with videos.
+        """
+        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 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, options=options)
+
+    def get(self, id: str, options: Optional[RequestOptions] = None) -> Any:
+        """Fetch the current status of an image-to-video task.
+
+        Args:
+            id: The task id.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}", options=options)
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        self._validate_contract(CONTRACT["image-to-video"], params)

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/resources/text_to_video.py

@@ -0,0 +1,61 @@
+"""MiniMax H3 text-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from runapi.core import Resource, RequestOptions
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedVideoTaskResponse,
+    VideoTaskResponse,
+)
+
+
+class TextToVideo(Resource):
+    """Generate videos from text prompts with MiniMax H3 models."""
+
+    ENDPOINT = "/api/v1/minimax_h3/text_to_video"
+
+    RESPONSE_CLASS = VideoTaskResponse
+    COMPLETED_RESPONSE_CLASS = CompletedVideoTaskResponse
+
+    def run(self, options: Optional[RequestOptions] = None, **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 task with videos.
+        """
+        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-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, options=options)
+
+    def get(self, id: str, options: Optional[RequestOptions] = None) -> Any:
+        """Fetch the current status of a text-to-video task.
+
+        Args:
+            id: The task id.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}", options=options)
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        self._validate_contract(CONTRACT["text-to-video"], params)

runapi_minimax_h3-0.1.0/src/runapi/minimax_h3/types.py

@@ -0,0 +1,24 @@
+"""MiniMax H3 model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+
+class MediaUrl(BaseModel):
+    url = optional(str)
+
+
+class VideoTaskResponse(TaskResponse):
+    """Response for a video generation task."""
+
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+    videos = optional([lambda: MediaUrl])
+    error = optional(str)
+
+
+class CompletedVideoTaskResponse(VideoTaskResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    videos = required([lambda: MediaUrl])

runapi_minimax_h3-0.1.0/tests/test_client.py

@@ -0,0 +1,68 @@
+import pytest
+
+from runapi.core.errors import ValidationError
+from runapi.minimax_h3 import MiniMaxH3Client
+
+
+class FakeHttp:
+    def __init__(self, response=None):
+        self.response = response or {"id": "task_1", "status": "pending"}
+        self.calls = []
+
+    def request(self, method, path, body=None, options=None):
+        self.calls.append((method, path, body))
+        return self.response
+
+
+def test_posts_reference_media_through_text_to_video():
+    fake = FakeHttp()
+    client = MiniMaxH3Client(api_key="k", http_client=fake)
+    client.text_to_video.create(
+        model="minimax-h3",
+        prompt="Continue the performance",
+        reference_image_urls=["https://cdn.runapi.ai/public/samples/image.jpg"],
+        reference_audio_urls=["https://cdn.runapi.ai/public/samples/voice.mp3"],
+        aspect_ratio="adaptive",
+    )
+    assert fake.calls == [("post", "/api/v1/minimax_h3/text_to_video", {
+        "model": "minimax-h3",
+        "prompt": "Continue the performance",
+        "reference_image_urls": ["https://cdn.runapi.ai/public/samples/image.jpg"],
+        "reference_audio_urls": ["https://cdn.runapi.ai/public/samples/voice.mp3"],
+        "aspect_ratio": "adaptive",
+    })]
+
+
+def test_posts_last_frame_only_through_image_to_video():
+    fake = FakeHttp()
+    client = MiniMaxH3Client(api_key="k", http_client=fake)
+    client.image_to_video.create(
+        model="minimax-h3", prompt="Animate", last_frame_image_url="https://cdn.runapi.ai/public/samples/image.jpg"
+    )
+    assert fake.calls[0][1] == "/api/v1/minimax_h3/image_to_video"
+
+
+def test_rejects_audio_only_references():
+    client = MiniMaxH3Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="one of reference_image_urls, reference_video_urls is required"):
+        client.text_to_video.create(
+            model="minimax-h3", prompt="Continue", reference_audio_urls=["https://cdn.runapi.ai/public/samples/voice.mp3"]
+        )
+
+
+def test_requires_aspect_ratio_without_references():
+    client = MiniMaxH3Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="aspect_ratio is required when reference_image_urls is absent and reference_video_urls is absent"):
+        client.text_to_video.create(model="minimax-h3", prompt="Continue")
+
+
+def test_rejects_adaptive_aspect_ratio_without_references():
+    client = MiniMaxH3Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="aspect_ratio must be one of:"):
+        client.text_to_video.create(model="minimax-h3", prompt="Continue", aspect_ratio="adaptive")
+
+
+def test_requires_first_or_last_frame():
+    client = MiniMaxH3Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="one of first_frame_image_url, last_frame_image_url is required"):
+        client.image_to_video.create(model="minimax-h3", prompt="Animate")