runapi-kling 0.1.0__tar.gz

runapi_kling-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_kling-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,74 @@
+# 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/pyproject.toml

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

@@ -0,0 +1,519 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.kling import KlingClient
+from runapi.kling.resources.ai_avatar import AiAvatar
+from runapi.kling.resources.image_to_video import ImageToVideo
+from runapi.kling.resources.motion_control import MotionControl
+from runapi.kling.resources.text_to_video import TextToVideo
+from runapi.kling.types import (
+    AiAvatarResponse,
+    CompletedAiAvatarResponse,
+    CompletedImageToVideoResponse,
+    CompletedMotionControlResponse,
+    CompletedTextToVideoResponse,
+    ImageToVideoResponse,
+    MotionControlResponse,
+    TextToVideoResponse,
+)
+
+
+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(KlingClient(api_key="k", http_client=FakeHttp()), KlingClient)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(KlingClient(http_client=FakeHttp()), KlingClient)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(KlingClient(http_client=FakeHttp()), KlingClient)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        KlingClient()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = KlingClient(api_key="k", http_client=fake)
+    assert client.text_to_video._http is fake
+    assert client.ai_avatar._http is fake
+    assert client.image_to_video._http is fake
+    assert client.motion_control._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_video, TextToVideo)
+    assert isinstance(client.ai_avatar, AiAvatar)
+    assert isinstance(client.image_to_video, ImageToVideo)
+    assert isinstance(client.motion_control, MotionControl)
+
+
+# --- text_to_video --------------------------------------------------------
+
+
+def test_text_to_video_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.text_to_video.create(
+        model="kling-3.0", prompt="a cat in a garden", aspect_ratio="16:9", seed=None
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/kling/text_to_video",
+            {"model": "kling-3.0", "prompt": "a cat in a garden", "aspect_ratio": "16:9"},
+        ),
+    ]
+    assert isinstance(result, TextToVideoResponse)
+
+
+def test_text_to_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = KlingClient(api_key="k", http_client=fake)
+    client.text_to_video.get("t1")
+    assert fake.calls == [("get", "/api/v1/kling/text_to_video/t1", None)]
+
+
+def test_text_to_video_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "videos": [{"url": "https://x/y.mp4"}]},
+    )
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.text_to_video.run(model="kling-3.0", prompt="a serene forest")
+    assert isinstance(result, CompletedTextToVideoResponse)
+    assert result.videos[0].url == "https://x/y.mp4"
+
+
+def test_text_to_video_rejects_missing_model():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model is required"):
+        client.text_to_video.create(prompt="hello")
+
+
+def test_text_to_video_rejects_unknown_model():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid model"):
+        client.text_to_video.create(model="nope", prompt="hello")
+
+
+def test_text_to_video_requires_prompt():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.text_to_video.create(model="kling-3.0")
+
+
+def test_text_to_video_multi_shots_requires_enable_sound():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="enable_sound must be true when multi_shots is true"):
+        client.text_to_video.create(model="kling-3.0", multi_shots=True)
+
+
+def test_text_to_video_multi_shots_rejects_last_frame():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(
+        ValidationError, match="last_frame_image_url is not supported when multi_shots is true"
+    ):
+        client.text_to_video.create(
+            model="kling-3.0",
+            multi_shots=True,
+            enable_sound=True,
+            last_frame_image_url="https://x/a.png",
+            multi_prompt=[{"prompt": "shot one", "duration_seconds": 5}],
+        )
+
+
+def test_text_to_video_multi_prompt_must_be_non_empty():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(
+        ValidationError, match="multi_prompt must be a non-empty array when multi_shots is true"
+    ):
+        client.text_to_video.create(
+            model="kling-3.0", multi_shots=True, enable_sound=True, multi_prompt=[]
+        )
+
+
+def test_text_to_video_multi_prompt_requires_prompt():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match=r"multi_prompt\[0\].prompt is required"):
+        client.text_to_video.create(
+            model="kling-3.0",
+            multi_shots=True,
+            enable_sound=True,
+            multi_prompt=[{"duration_seconds": 5}],
+        )
+
+
+def test_text_to_video_multi_prompt_max_length():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match=r"multi_prompt\[0\].prompt exceeds 500 characters"):
+        client.text_to_video.create(
+            model="kling-3.0",
+            multi_shots=True,
+            enable_sound=True,
+            multi_prompt=[{"prompt": "x" * 501, "duration_seconds": 5}],
+        )
+
+
+def test_text_to_video_multi_prompt_requires_duration():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match=r"multi_prompt\[0\].duration_seconds is required"):
+        client.text_to_video.create(
+            model="kling-3.0",
+            multi_shots=True,
+            enable_sound=True,
+            multi_prompt=[{"prompt": "shot one"}],
+        )
+
+
+def test_text_to_video_multi_prompt_duration_range():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(
+        ValidationError, match=r"multi_prompt\[0\].duration_seconds must be between 1 and 12"
+    ):
+        client.text_to_video.create(
+            model="kling-3.0",
+            multi_shots=True,
+            enable_sound=True,
+            multi_prompt=[{"prompt": "shot one", "duration_seconds": 20}],
+        )
+
+
+def test_text_to_video_rejects_invalid_output_resolution():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid output_resolution"):
+        client.text_to_video.create(model="kling-3.0", prompt="hello", output_resolution="9k")
+
+
+def test_text_to_video_rejects_invalid_aspect_ratio():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid aspect_ratio"):
+        client.text_to_video.create(model="kling-3.0", prompt="hello", aspect_ratio="4:3")
+
+
+def test_text_to_video_fixed_duration_models():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Must be one of: 5, 10"):
+        client.text_to_video.create(
+            model="kling-v2.1-master-text-to-video", prompt="hello", duration_seconds=7
+        )
+
+
+def test_text_to_video_range_duration_models():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(
+        ValidationError, match="Must be an integer between 3 and 15"
+    ):
+        client.text_to_video.create(model="kling-3.0", prompt="hello", duration_seconds=20)
+
+
+# --- ai_avatar ------------------------------------------------------------
+
+
+def test_ai_avatar_create_posts_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.ai_avatar.create(
+        model="kling-ai-avatar-pro",
+        prompt="a host greeting",
+        source_image_url="https://x/p.jpg",
+        source_audio_url="https://x/a.mp3",
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/kling/ai_avatar",
+            {
+                "model": "kling-ai-avatar-pro",
+                "prompt": "a host greeting",
+                "source_image_url": "https://x/p.jpg",
+                "source_audio_url": "https://x/a.mp3",
+            },
+        ),
+    ]
+    assert isinstance(result, AiAvatarResponse)
+
+
+def test_ai_avatar_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = KlingClient(api_key="k", http_client=fake)
+    client.ai_avatar.get("t1")
+    assert fake.calls == [("get", "/api/v1/kling/ai_avatar/t1", None)]
+
+
+def test_ai_avatar_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "videos": [{"url": "https://x/a.mp4"}]},
+    )
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.ai_avatar.run(
+        model="kling-ai-avatar-pro",
+        prompt="a host",
+        source_image_url="https://x/p.jpg",
+        source_audio_url="https://x/a.mp3",
+    )
+    assert isinstance(result, CompletedAiAvatarResponse)
+    assert result.videos[0].url == "https://x/a.mp4"
+
+
+def test_ai_avatar_rejects_unknown_model():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid model"):
+        client.ai_avatar.create(model="nope")
+
+
+def test_ai_avatar_requires_source_image_url():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_image_url is required"):
+        client.ai_avatar.create(model="kling-ai-avatar-pro")
+
+
+def test_ai_avatar_requires_source_audio_url():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_audio_url is required"):
+        client.ai_avatar.create(model="kling-ai-avatar-pro", source_image_url="https://x/p.jpg")
+
+
+def test_ai_avatar_requires_prompt():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.ai_avatar.create(
+            model="kling-ai-avatar-pro",
+            source_image_url="https://x/p.jpg",
+            source_audio_url="https://x/a.mp3",
+        )
+
+
+# --- image_to_video -------------------------------------------------------
+
+
+def test_image_to_video_create_posts_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.image_to_video.create(
+        model="kling-v2.1-pro",
+        prompt="zoom out slowly",
+        first_frame_image_url="https://x/f.jpg",
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/kling/image_to_video",
+            {
+                "model": "kling-v2.1-pro",
+                "prompt": "zoom out slowly",
+                "first_frame_image_url": "https://x/f.jpg",
+            },
+        ),
+    ]
+    assert isinstance(result, ImageToVideoResponse)
+
+
+def test_image_to_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = KlingClient(api_key="k", http_client=fake)
+    client.image_to_video.get("t1")
+    assert fake.calls == [("get", "/api/v1/kling/image_to_video/t1", None)]
+
+
+def test_image_to_video_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "videos": [{"url": "https://x/i.mp4"}]},
+    )
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.image_to_video.run(
+        model="kling-v2.1-pro", prompt="zoom", first_frame_image_url="https://x/f.jpg"
+    )
+    assert isinstance(result, CompletedImageToVideoResponse)
+    assert result.videos[0].url == "https://x/i.mp4"
+
+
+def test_image_to_video_rejects_unknown_model():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid model"):
+        client.image_to_video.create(model="nope")
+
+
+def test_image_to_video_requires_prompt():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.image_to_video.create(model="kling-v2.1-pro")
+
+
+def test_image_to_video_requires_first_frame_image_url():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="first_frame_image_url is required"):
+        client.image_to_video.create(model="kling-v2.1-pro", prompt="zoom")
+
+
+def test_image_to_video_rejects_invalid_duration():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Must be one of: 5, 10"):
+        client.image_to_video.create(
+            model="kling-v2.1-pro",
+            prompt="zoom",
+            first_frame_image_url="https://x/f.jpg",
+            duration_seconds=7,
+        )
+
+
+def test_image_to_video_last_frame_model_gate():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(
+        ValidationError,
+        match="last_frame_image_url is only supported by kling-v2.5-turbo-image-to-video-pro and kling-v2.1-pro",
+    ):
+        client.image_to_video.create(
+            model="kling-v2.1-standard",
+            prompt="zoom",
+            first_frame_image_url="https://x/f.jpg",
+            last_frame_image_url="https://x/l.jpg",
+        )
+
+
+def test_image_to_video_last_frame_allowed_for_supported_model():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = KlingClient(api_key="k", http_client=fake)
+    client.image_to_video.create(
+        model="kling-v2.1-pro",
+        prompt="zoom",
+        first_frame_image_url="https://x/f.jpg",
+        last_frame_image_url="https://x/l.jpg",
+    )
+    assert fake.calls[0][2]["last_frame_image_url"] == "https://x/l.jpg"
+
+
+# --- motion_control -------------------------------------------------------
+
+
+def test_motion_control_create_posts_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.motion_control.create(
+        model="kling-3.0",
+        source_image_url="https://x/s.jpg",
+        reference_video_url="https://x/r.mp4",
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/kling/motion_control",
+            {
+                "model": "kling-3.0",
+                "source_image_url": "https://x/s.jpg",
+                "reference_video_url": "https://x/r.mp4",
+            },
+        ),
+    ]
+    assert isinstance(result, MotionControlResponse)
+
+
+def test_motion_control_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = KlingClient(api_key="k", http_client=fake)
+    client.motion_control.get("t1")
+    assert fake.calls == [("get", "/api/v1/kling/motion_control/t1", None)]
+
+
+def test_motion_control_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "videos": [{"url": "https://x/m.mp4"}]},
+    )
+    client = KlingClient(api_key="k", http_client=fake)
+    result = client.motion_control.run(
+        model="kling-3.0",
+        source_image_url="https://x/s.jpg",
+        reference_video_url="https://x/r.mp4",
+    )
+    assert isinstance(result, CompletedMotionControlResponse)
+    assert result.videos[0].url == "https://x/m.mp4"
+
+
+def test_motion_control_rejects_unknown_model():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid model"):
+        client.motion_control.create(model="nope")
+
+
+def test_motion_control_rejects_invalid_output_resolution():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid output_resolution"):
+        client.motion_control.create(model="kling-3.0", output_resolution="4k")
+
+
+def test_motion_control_rejects_invalid_character_orientation():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid character_orientation"):
+        client.motion_control.create(model="kling-3.0", character_orientation="upside-down")
+
+
+def test_motion_control_rejects_invalid_background_source():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid background_source"):
+        client.motion_control.create(model="kling-3.0", background_source="audio")
+
+
+def test_motion_control_requires_source_image_url():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_image_url is required"):
+        client.motion_control.create(model="kling-3.0")
+
+
+def test_motion_control_requires_reference_video_url():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference_video_url is required"):
+        client.motion_control.create(model="kling-3.0", source_image_url="https://x/s.jpg")
+
+
+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 = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Must be an integer between"):
+        client.text_to_video.create(model="kling-3.0", prompt="a cat", duration_seconds="abc")
+
+
+def test_multi_prompt_non_numeric_duration_raises_validation_error():
+    client = KlingClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match=r"multi_prompt\[0\].duration_seconds must be between"):
+        client.text_to_video.create(
+            model="kling-3.0",
+            multi_shots=True,
+            enable_sound=True,
+            multi_prompt=[{"prompt": "shot one", "duration_seconds": "abc"}],
+        )