runapi-kling 0.1.0__py3-none-any.whl

runapi/kling/__init__.py

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

runapi/kling/client.py

@@ -0,0 +1,33 @@
+"""Kling client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.ai_avatar import AiAvatar
+from .resources.image_to_video import ImageToVideo
+from .resources.motion_control import MotionControl
+from .resources.text_to_video import TextToVideo
+
+
+class KlingClient:
+    """Kling video generation client.
+
+    Example::
+
+        client = KlingClient(api_key="sk-...")
+        result = client.text_to_video.run(
+            model="kling-3.0", prompt="A cat walking through a garden"
+        )
+    """
+
+    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.ai_avatar = AiAvatar(http)
+        self.image_to_video = ImageToVideo(http)
+        self.motion_control = MotionControl(http)

runapi/kling/resources/__init__.py

@@ -0,0 +1,6 @@
+from .ai_avatar import AiAvatar
+from .image_to_video import ImageToVideo
+from .motion_control import MotionControl
+from .text_to_video import TextToVideo
+
+__all__ = ["TextToVideo", "AiAvatar", "ImageToVideo", "MotionControl"]

runapi/kling/resources/ai_avatar.py

@@ -0,0 +1,70 @@
+"""Kling AI avatar resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import AI_AVATAR_MODELS, AiAvatarResponse, CompletedAiAvatarResponse
+
+
+class AiAvatar(Resource):
+    """Generate talking avatar videos from images and audio."""
+
+    ENDPOINT = "/api/v1/kling/ai_avatar"
+
+    RESPONSE_CLASS = AiAvatarResponse
+    COMPLETED_RESPONSE_CLASS = CompletedAiAvatarResponse
+
+    def run(self, **params: Any) -> Any:
+        """Generate an AI avatar video and poll until it completes.
+
+        Args:
+            **params: AI avatar parameters (model, source_image_url, source_audio_url, prompt, ...).
+
+        Returns:
+            The completed task with videos.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create an AI avatar task and return immediately with an ``id``.
+
+        Args:
+            **params: AI avatar parameters (model, source_image_url, source_audio_url, 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 AI avatar 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 AI_AVATAR_MODELS:
+            raise ValidationError(
+                f"Invalid model: {model}. Must be one of: {', '.join(AI_AVATAR_MODELS)}"
+            )
+
+        if not params.get("source_image_url"):
+            raise ValidationError("source_image_url is required")
+        if not params.get("source_audio_url"):
+            raise ValidationError("source_audio_url is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")

runapi/kling/resources/image_to_video.py

@@ -0,0 +1,90 @@
+"""Kling image-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    FIXED_DURATIONS,
+    IMAGE_TO_VIDEO_MODELS,
+    CompletedImageToVideoResponse,
+    ImageToVideoResponse,
+)
+
+
+class ImageToVideo(Resource):
+    """Generate videos from an input image with Kling models."""
+
+    ENDPOINT = "/api/v1/kling/image_to_video"
+
+    RESPONSE_CLASS = ImageToVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedImageToVideoResponse
+
+    def run(self, **params: Any) -> Any:
+        """Generate a video from an image and poll until it completes.
+
+        Args:
+            **params: Image-to-video parameters (model, prompt, first_frame_image_url, ...).
+
+        Returns:
+            The completed task with videos.
+        """
+        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, first_frame_image_url, ...).
+
+        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: 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 IMAGE_TO_VIDEO_MODELS:
+            raise ValidationError(
+                f"Invalid model: {model}. Must be one of: {', '.join(IMAGE_TO_VIDEO_MODELS)}"
+            )
+
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+        if not params.get("first_frame_image_url"):
+            raise ValidationError("first_frame_image_url is required")
+
+        duration_seconds = params.get("duration_seconds")
+        if duration_seconds is not None and duration_seconds not in FIXED_DURATIONS:
+            raise ValidationError(
+                f"Invalid duration_seconds: {duration_seconds}. "
+                f"Must be one of: {', '.join(str(d) for d in FIXED_DURATIONS)}"
+            )
+
+        last_frame_image_url = params.get("last_frame_image_url")
+        if last_frame_image_url and model not in (
+            "kling-v2.5-turbo-image-to-video-pro",
+            "kling-v2.1-pro",
+        ):
+            raise ValidationError(
+                "last_frame_image_url is only supported by "
+                "kling-v2.5-turbo-image-to-video-pro and kling-v2.1-pro"
+            )

runapi/kling/resources/motion_control.py

@@ -0,0 +1,80 @@
+"""Kling motion control resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    MOTION_CONTROL_BACKGROUND_SOURCES,
+    MOTION_CONTROL_CHARACTER_ORIENTATIONS,
+    MOTION_CONTROL_MODELS,
+    MOTION_CONTROL_OUTPUT_RESOLUTIONS,
+    CompletedMotionControlResponse,
+    MotionControlResponse,
+)
+
+
+class MotionControl(Resource):
+    """Generate videos with motion transfer from reference videos."""
+
+    ENDPOINT = "/api/v1/kling/motion_control"
+
+    RESPONSE_CLASS = MotionControlResponse
+    COMPLETED_RESPONSE_CLASS = CompletedMotionControlResponse
+
+    def run(self, **params: Any) -> Any:
+        """Generate a motion control video and poll until it completes.
+
+        Args:
+            **params: Motion control parameters (model, source_image_url, reference_video_url, ...).
+
+        Returns:
+            The completed task with videos.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a motion control task and return immediately with an ``id``.
+
+        Args:
+            **params: Motion control parameters (model, source_image_url, reference_video_url, ...).
+
+        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 motion control 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 MOTION_CONTROL_MODELS:
+            raise ValidationError(
+                f"Invalid model: {model}. Must be one of: {', '.join(MOTION_CONTROL_MODELS)}"
+            )
+
+        self._validate_optional(params, "output_resolution", MOTION_CONTROL_OUTPUT_RESOLUTIONS)
+        self._validate_optional(params, "character_orientation", MOTION_CONTROL_CHARACTER_ORIENTATIONS)
+        self._validate_optional(params, "background_source", MOTION_CONTROL_BACKGROUND_SOURCES)
+
+        if not params.get("source_image_url"):
+            raise ValidationError("source_image_url is required")
+
+        if not params.get("reference_video_url"):
+            raise ValidationError("reference_video_url is required")

runapi/kling/resources/text_to_video.py

@@ -0,0 +1,136 @@
+"""Kling text-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    ASPECT_RATIOS,
+    DURATION_RANGE,
+    FIXED_DURATIONS,
+    MULTI_PROMPT_DURATION_RANGE,
+    MULTI_PROMPT_MAX_LENGTH,
+    TEXT_TO_VIDEO_MODELS,
+    TEXT_TO_VIDEO_OUTPUT_RESOLUTIONS,
+    CompletedTextToVideoResponse,
+    TextToVideoResponse,
+)
+
+
+class TextToVideo(Resource):
+    """Generate videos from text prompts with Kling models."""
+
+    ENDPOINT = "/api/v1/kling/text_to_video"
+
+    RESPONSE_CLASS = TextToVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToVideoResponse
+
+    def run(self, **params: Any) -> Any:
+        """Generate a video from text and poll until it completes.
+
+        Args:
+            **params: Text-to-video parameters (model, prompt, ...).
+
+        Returns:
+            The completed task with videos.
+        """
+        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: 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 TEXT_TO_VIDEO_MODELS:
+            raise ValidationError(
+                f"Invalid model: {model}. Must be one of: {', '.join(TEXT_TO_VIDEO_MODELS)}"
+            )
+
+        multi_shots = params.get("multi_shots") is True
+
+        if multi_shots:
+            if params.get("enable_sound") is not True:
+                raise ValidationError("enable_sound must be true when multi_shots is true")
+            if params.get("last_frame_image_url"):
+                raise ValidationError("last_frame_image_url is not supported when multi_shots is true")
+
+            self._validate_multi_prompt(params.get("multi_prompt"))
+        else:
+            if not params.get("prompt"):
+                raise ValidationError("prompt is required")
+
+        self._validate_optional(params, "output_resolution", TEXT_TO_VIDEO_OUTPUT_RESOLUTIONS)
+        self._validate_optional(params, "aspect_ratio", ASPECT_RATIOS)
+
+        duration_seconds = params.get("duration_seconds")
+        if duration_seconds is not None:
+            try:
+                dur_int = int(duration_seconds)
+            except (TypeError, ValueError):
+                dur_int = None
+            if model in ("kling-v2.1-master-text-to-video", "kling-v2.5-turbo-text-to-video-pro"):
+                if duration_seconds not in FIXED_DURATIONS:
+                    raise ValidationError(
+                        f"Invalid duration_seconds: {duration_seconds}. "
+                        f"Must be one of: {', '.join(str(d) for d in FIXED_DURATIONS)}"
+                    )
+            elif dur_int is None or dur_int not in DURATION_RANGE:
+                raise ValidationError(
+                    f"Invalid duration_seconds: {duration_seconds}. "
+                    f"Must be an integer between {DURATION_RANGE.start} and {DURATION_RANGE.stop - 1}"
+                )
+
+    def _validate_multi_prompt(self, multi_prompt: Any) -> None:
+        if not (isinstance(multi_prompt, list) and len(multi_prompt) > 0):
+            raise ValidationError("multi_prompt must be a non-empty array when multi_shots is true")
+
+        for index, shot in enumerate(multi_prompt):
+            prompt = shot.get("prompt") if isinstance(shot, dict) else None
+            duration_seconds = shot.get("duration_seconds") if isinstance(shot, dict) else None
+
+            if prompt is None or len(prompt) == 0:
+                raise ValidationError(f"multi_prompt[{index}].prompt is required")
+
+            if len(prompt) > MULTI_PROMPT_MAX_LENGTH:
+                raise ValidationError(
+                    f"multi_prompt[{index}].prompt exceeds {MULTI_PROMPT_MAX_LENGTH} characters"
+                )
+
+            if duration_seconds is None:
+                raise ValidationError(f"multi_prompt[{index}].duration_seconds is required")
+
+            try:
+                dur_int = int(duration_seconds)
+            except (TypeError, ValueError):
+                dur_int = None
+            if dur_int is None or dur_int not in MULTI_PROMPT_DURATION_RANGE:
+                raise ValidationError(
+                    f"multi_prompt[{index}].duration_seconds must be between "
+                    f"{MULTI_PROMPT_DURATION_RANGE.start} and {MULTI_PROMPT_DURATION_RANGE.stop - 1}"
+                )

runapi/kling/types.py

@@ -0,0 +1,110 @@
+"""Kling model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+TEXT_TO_VIDEO_MODELS = [
+    "kling-3.0",
+    "kling-v2.5-turbo-text-to-video-pro",
+    "kling-v2.1-master-text-to-video",
+]
+
+AI_AVATAR_MODELS = [
+    "kling-ai-avatar-pro",
+    "kling-ai-avatar-standard",
+    "kling-ai-avatar-v1-pro",
+    "kling-v1-avatar-standard",
+]
+
+IMAGE_TO_VIDEO_MODELS = [
+    "kling-v2.5-turbo-image-to-video-pro",
+    "kling-v2.1-pro",
+    "kling-v2.1-standard",
+    "kling-v2.1-master-image-to-video",
+]
+
+TEXT_TO_VIDEO_OUTPUT_RESOLUTIONS = ["720p", "1080p", "4k"]
+
+MOTION_CONTROL_MODELS = ["kling-3.0"]
+
+MOTION_CONTROL_OUTPUT_RESOLUTIONS = ["720p", "1080p"]
+
+MOTION_CONTROL_CHARACTER_ORIENTATIONS = ["video", "image"]
+
+MOTION_CONTROL_BACKGROUND_SOURCES = ["video", "image"]
+
+ASPECT_RATIOS = ["16:9", "9:16", "1:1"]
+
+DURATION_RANGE = range(3, 16)
+
+MULTI_PROMPT_DURATION_RANGE = range(1, 13)
+
+FIXED_DURATIONS = [5, 10]
+
+MULTI_PROMPT_MAX_LENGTH = 500
+
+
+class Video(BaseModel):
+    url = optional(str)
+
+
+class AsyncTaskResponse(TaskResponse):
+    """Base response for an asynchronous Kling task."""
+
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+
+
+class TextToVideoResponse(AsyncTaskResponse):
+    """Response for a text-to-video task."""
+
+    videos = optional([lambda: Video])
+    error = optional(str)
+
+
+class AiAvatarResponse(AsyncTaskResponse):
+    """Response for an AI avatar task."""
+
+    videos = optional([lambda: Video])
+    error = optional(str)
+
+
+class ImageToVideoResponse(AsyncTaskResponse):
+    """Response for an image-to-video task."""
+
+    videos = optional([lambda: Video])
+    error = optional(str)
+
+
+class MotionControlResponse(AsyncTaskResponse):
+    """Response for a motion control task."""
+
+    videos = optional([lambda: Video])
+    error = optional(str)
+
+
+# Narrowed responses returned by ``run()`` once polling observes completion.
+# ``videos`` is required so consumers never have to null-check it on success.
+class CompletedTextToVideoResponse(TextToVideoResponse):
+    """Narrowed text-to-video response once polling observes completion."""
+
+    videos = required([lambda: Video])
+
+
+class CompletedAiAvatarResponse(AiAvatarResponse):
+    """Narrowed AI avatar response once polling observes completion."""
+
+    videos = required([lambda: Video])
+
+
+class CompletedImageToVideoResponse(ImageToVideoResponse):
+    """Narrowed image-to-video response once polling observes completion."""
+
+    videos = required([lambda: Video])
+
+
+class CompletedMotionControlResponse(MotionControlResponse):
+    """Narrowed motion control response once polling observes completion."""
+
+    videos = required([lambda: Video])

runapi_kling-0.1.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: runapi-kling
+Version: 0.1.0
+Summary: Kling video generation client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/kling
+Project-URL: Documentation, https://runapi.ai/docs#sdk-kling
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,image-to-video,kling,runapi,sdk,text-to-video
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Kling Python SDK for RunAPI
+
+The Kling Python SDK is the language-specific package for Kling on RunAPI.
+Use it for text-to-video, image-to-video, AI avatar, and motion control 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/kling; for API reference, use
+https://runapi.ai/docs#kling; for SDK docs, use https://runapi.ai/docs#sdk-kling.
+
+## Install
+
+```bash
+pip install runapi-kling
+```
+
+## Quick start
+
+```python
+from runapi.kling import KlingClient
+
+client = KlingClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="kling-3.0",
+    prompt="A cat walking through a garden",
+)
+status = client.text_to_video.get(task.id)
+
+avatar = client.ai_avatar.create(
+    model="kling-ai-avatar-pro",
+    prompt="A friendly host greeting the audience",
+    source_image_url="https://example.com/portrait.jpg",
+    source_audio_url="https://example.com/voice.mp3",
+)
+```
+
+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="kling-3.0",
+    prompt="A serene drone shot over a misty forest",
+)
+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 videos 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.kling` error classes
+when building video jobs or scripts. The available resources are
+`text_to_video`, `ai_avatar`, `image_to_video`, and `motion_control`. 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/kling
+- SDK docs: https://runapi.ai/docs#sdk-kling
+- Product docs: https://runapi.ai/docs#kling
+- Pricing and rate limits: https://runapi.ai/models/kling
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_kling-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+runapi/kling/__init__.py,sha256=UgYgGJF6XmaT-Uh0stCmoeEFAIK-LRrna78E0Thnl2U,457
+runapi/kling/client.py,sha256=YNVEc2iOzeynzLtS9wl1zqqQLX1hf353Lm2QUF9zJIo,1073
+runapi/kling/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+runapi/kling/types.py,sha256=5PMnLV5UW1VLBkhFbUbDZoyv7ZLyrDkvD8xsK56qAsk,2759
+runapi/kling/resources/__init__.py,sha256=eC8NJ7kgXrhTJq_uds_YiIa5ZtFfHsvVqsoZDjuY7mM,226
+runapi/kling/resources/ai_avatar.py,sha256=5AHkJLKiYiOxS_hYJCptbY682dK7ZlzsBxuM-EC0ro4,2284
+runapi/kling/resources/image_to_video.py,sha256=eI46MRIb6_b0wQ6kDbGaV47jsGwYRgeKjSip60X7JfQ,2994
+runapi/kling/resources/motion_control.py,sha256=D4J7dlGI2_EtdcTB3BZ_uHSCHBKX4yIEhsrNXhtSGog,2701
+runapi/kling/resources/text_to_video.py,sha256=C2mFonAtCobhGb3DUOoytyJlU8fDys2MDAOhYFZ2M_4,5177
+runapi_kling-0.1.0.dist-info/METADATA,sha256=QF1O_MLSvqO5zYCgOGgseGRESSDBMhdqeo3jOWyfN_g,2692
+runapi_kling-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+runapi_kling-0.1.0.dist-info/RECORD,,

runapi_kling-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