runapi-happyhorse 0.1.0__tar.gz

runapi_happyhorse-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_happyhorse-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: runapi-happyhorse
+Version: 0.1.0
+Summary: HappyHorse text-to-video, image-to-video, and edit-video client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/happyhorse
+Project-URL: Documentation, https://runapi.ai/docs#sdk-happyhorse
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,edit-video,happyhorse,image-to-video,runapi,sdk,text-to-video
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# HappyHorse Python SDK for RunAPI
+
+The HappyHorse Python SDK is the language-specific package for HappyHorse on
+RunAPI. Use it for text-to-video, image-to-video, and edit-video 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/happyhorse; for API reference,
+use https://runapi.ai/docs#happyhorse; for SDK docs, use
+https://runapi.ai/docs#sdk-happyhorse.
+
+## Install
+
+```bash
+pip install runapi-happyhorse
+```
+
+## Quick start
+
+```python
+from runapi.happyhorse import HappyHorseClient
+
+client = HappyHorseClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="happyhorse-text-to-video",
+    prompt="A horse galloping along a beach at sunset, cinematic",
+    aspect_ratio="16:9",
+    output_resolution="1080p",
+)
+status = client.text_to_video.get(task.id)
+
+clip = client.image_to_video.create(
+    model="happyhorse-image-to-video",
+    first_frame_image_url="https://example.com/first-frame.jpg",
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task
+state, and `run` to create and poll until completion:
+
+```python
+result = client.text_to_video.run(
+    model="happyhorse-text-to-video",
+    prompt="A serene mountain river 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 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.happyhorse` error
+classes when building video jobs or scripts. The available resources are
+`text_to_video`, `image_to_video`, and `edit_video`. 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/happyhorse
+- SDK docs: https://runapi.ai/docs#sdk-happyhorse
+- Product docs: https://runapi.ai/docs#happyhorse
+- Pricing and rate limits: https://runapi.ai/models/happyhorse
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_happyhorse-0.1.0/README.md

@@ -0,0 +1,74 @@
+# HappyHorse Python SDK for RunAPI
+
+The HappyHorse Python SDK is the language-specific package for HappyHorse on
+RunAPI. Use it for text-to-video, image-to-video, and edit-video 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/happyhorse; for API reference,
+use https://runapi.ai/docs#happyhorse; for SDK docs, use
+https://runapi.ai/docs#sdk-happyhorse.
+
+## Install
+
+```bash
+pip install runapi-happyhorse
+```
+
+## Quick start
+
+```python
+from runapi.happyhorse import HappyHorseClient
+
+client = HappyHorseClient()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="happyhorse-text-to-video",
+    prompt="A horse galloping along a beach at sunset, cinematic",
+    aspect_ratio="16:9",
+    output_resolution="1080p",
+)
+status = client.text_to_video.get(task.id)
+
+clip = client.image_to_video.create(
+    model="happyhorse-image-to-video",
+    first_frame_image_url="https://example.com/first-frame.jpg",
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task
+state, and `run` to create and poll until completion:
+
+```python
+result = client.text_to_video.run(
+    model="happyhorse-text-to-video",
+    prompt="A serene mountain river 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 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.happyhorse` error
+classes when building video jobs or scripts. The available resources are
+`text_to_video`, `image_to_video`, and `edit_video`. 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/happyhorse
+- SDK docs: https://runapi.ai/docs#sdk-happyhorse
+- Product docs: https://runapi.ai/docs#happyhorse
+- Pricing and rate limits: https://runapi.ai/models/happyhorse
+- Full catalog: https://runapi.ai/models
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_happyhorse-0.1.0/pyproject.toml

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

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

runapi_happyhorse-0.1.0/src/runapi/happyhorse/client.py

@@ -0,0 +1,31 @@
+"""HappyHorse client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.edit_video import EditVideo
+from .resources.image_to_video import ImageToVideo
+from .resources.text_to_video import TextToVideo
+
+
+class HappyHorseClient:
+    """HappyHorse text-to-video, image-to-video, and edit-video client.
+
+    Example::
+
+        client = HappyHorseClient(api_key="sk-...")
+        result = client.text_to_video.run(
+            model="happyhorse-text-to-video", prompt="A horse galloping on a beach"
+        )
+    """
+
+    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.edit_video = EditVideo(http)

runapi_happyhorse-0.1.0/src/runapi/happyhorse/resources/__init__.py

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

runapi_happyhorse-0.1.0/src/runapi/happyhorse/resources/edit_video.py

@@ -0,0 +1,94 @@
+"""HappyHorse edit-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    AUDIO_SETTINGS,
+    EDIT_VIDEO_MODEL,
+    OUTPUT_RESOLUTIONS,
+    SEED_RANGE,
+    CompletedEditVideoResponse,
+    EditVideoResponse,
+)
+
+
+class EditVideo(Resource):
+    """Edit a source video from a prompt with HappyHorse models."""
+
+    ENDPOINT = "/api/v1/happyhorse/edit_video"
+
+    RESPONSE_CLASS = EditVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedEditVideoResponse
+    REFERENCE_IMAGE_RANGE = range(0, 6)
+
+    def run(self, **params: Any) -> Any:
+        """Create an edit-video task and poll until it completes.
+
+        Args:
+            **params: Edit-video parameters (model, prompt, source_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 an edit-video task and return immediately with an ``id``.
+
+        Args:
+            **params: Edit-video parameters (model, prompt, source_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 an edit-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:
+        if params.get("model") != EDIT_VIDEO_MODEL:
+            raise ValidationError("model is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+        if not params.get("source_video_url"):
+            raise ValidationError("source_video_url is required")
+
+        reference_image_urls = params.get("reference_image_urls")
+        if reference_image_urls and (
+            not isinstance(reference_image_urls, list)
+            or len(reference_image_urls) not in self.REFERENCE_IMAGE_RANGE
+        ):
+            raise ValidationError(
+                f"reference_image_urls must include at most {self.REFERENCE_IMAGE_RANGE.stop - 1} entries"
+            )
+
+        self._validate_optional(params, "output_resolution", OUTPUT_RESOLUTIONS)
+        self._validate_optional(params, "audio_setting", AUDIO_SETTINGS)
+        self._validate_integer_range(params, "seed", SEED_RANGE)
+
+    @staticmethod
+    def _validate_integer_range(params: Dict[str, Any], key: str, allowed: range) -> None:
+        value = params.get(key)
+        if value is None:
+            return
+        if isinstance(value, int) and not isinstance(value, bool) and value in allowed:
+            return
+        raise ValidationError(
+            f"{key} must be an integer between {allowed.start} and {allowed.stop - 1}"
+        )

runapi_happyhorse-0.1.0/src/runapi/happyhorse/resources/image_to_video.py

@@ -0,0 +1,82 @@
+"""HappyHorse image-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    DURATION_RANGE,
+    IMAGE_TO_VIDEO_MODEL,
+    OUTPUT_RESOLUTIONS,
+    SEED_RANGE,
+    CompletedImageToVideoResponse,
+    ImageToVideoResponse,
+)
+
+
+class ImageToVideo(Resource):
+    """Generate videos from a first-frame image with HappyHorse models."""
+
+    ENDPOINT = "/api/v1/happyhorse/image_to_video"
+
+    RESPONSE_CLASS = ImageToVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedImageToVideoResponse
+
+    def run(self, **params: Any) -> Any:
+        """Create an image-to-video task and poll until it completes.
+
+        Args:
+            **params: Image-to-video parameters (model, 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, 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:
+        if params.get("model") != IMAGE_TO_VIDEO_MODEL:
+            raise ValidationError("model is required")
+        if not params.get("first_frame_image_url"):
+            raise ValidationError("first_frame_image_url is required")
+
+        self._validate_optional(params, "output_resolution", OUTPUT_RESOLUTIONS)
+        self._validate_integer_range(params, "duration_seconds", DURATION_RANGE)
+        self._validate_integer_range(params, "seed", SEED_RANGE)
+
+    @staticmethod
+    def _validate_integer_range(params: Dict[str, Any], key: str, allowed: range) -> None:
+        value = params.get(key)
+        if value is None:
+            return
+        if isinstance(value, int) and not isinstance(value, bool) and value in allowed:
+            return
+        raise ValidationError(
+            f"{key} must be an integer between {allowed.start} and {allowed.stop - 1}"
+        )

runapi_happyhorse-0.1.0/src/runapi/happyhorse/resources/text_to_video.py

@@ -0,0 +1,100 @@
+"""HappyHorse text-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    ASPECT_RATIOS,
+    CHARACTER_MODEL,
+    DURATION_RANGE,
+    OUTPUT_RESOLUTIONS,
+    SEED_RANGE,
+    TEXT_TO_VIDEO_MODELS,
+    CompletedTextToVideoResponse,
+    TextToVideoResponse,
+)
+
+
+class TextToVideo(Resource):
+    """Generate videos from text prompts with HappyHorse models."""
+
+    ENDPOINT = "/api/v1/happyhorse/text_to_video"
+
+    RESPONSE_CLASS = TextToVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToVideoResponse
+    REFERENCE_IMAGE_URLS_RANGE = range(1, 10)
+
+    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 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 model not in TEXT_TO_VIDEO_MODELS:
+            raise ValidationError("model is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+
+        reference_image_urls = params.get("reference_image_urls")
+        if model == CHARACTER_MODEL:
+            if not (
+                isinstance(reference_image_urls, list)
+                and len(reference_image_urls) in self.REFERENCE_IMAGE_URLS_RANGE
+            ):
+                raise ValidationError(
+                    f"reference_image_urls must include between {self.REFERENCE_IMAGE_URLS_RANGE.start} "
+                    f"and {self.REFERENCE_IMAGE_URLS_RANGE.stop - 1} entries"
+                )
+        elif reference_image_urls:
+            raise ValidationError(f"reference_image_urls is only supported for {CHARACTER_MODEL}")
+
+        self._validate_optional(params, "output_resolution", OUTPUT_RESOLUTIONS)
+        self._validate_optional(params, "aspect_ratio", ASPECT_RATIOS)
+        self._validate_integer_range(params, "duration_seconds", DURATION_RANGE)
+        self._validate_integer_range(params, "seed", SEED_RANGE)
+
+    @staticmethod
+    def _validate_integer_range(params: Dict[str, Any], key: str, allowed: range) -> None:
+        value = params.get(key)
+        if value is None:
+            return
+        if isinstance(value, int) and not isinstance(value, bool) and value in allowed:
+            return
+        raise ValidationError(
+            f"{key} must be an integer between {allowed.start} and {allowed.stop - 1}"
+        )

runapi_happyhorse-0.1.0/src/runapi/happyhorse/types.py

@@ -0,0 +1,41 @@
+"""HappyHorse model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+TEXT_TO_VIDEO_MODEL = "happyhorse-text-to-video"
+CHARACTER_MODEL = "happyhorse-character"
+TEXT_TO_VIDEO_MODELS = [TEXT_TO_VIDEO_MODEL, CHARACTER_MODEL]
+IMAGE_TO_VIDEO_MODEL = "happyhorse-image-to-video"
+EDIT_VIDEO_MODEL = "happyhorse-edit-video"
+OUTPUT_RESOLUTIONS = ["720p", "1080p"]
+ASPECT_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4"]
+AUDIO_SETTINGS = ["auto", "original"]
+DURATION_RANGE = range(3, 16)
+SEED_RANGE = range(0, 2_147_483_648)
+
+
+class MediaUrl(BaseModel):
+    url = optional(str)
+
+
+class TextToVideoResponse(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 CompletedTextToVideoResponse(TextToVideoResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    videos = required([lambda: MediaUrl])
+
+
+ImageToVideoResponse = TextToVideoResponse
+CompletedImageToVideoResponse = CompletedTextToVideoResponse
+EditVideoResponse = TextToVideoResponse
+CompletedEditVideoResponse = CompletedTextToVideoResponse

runapi_happyhorse-0.1.0/tests/test_client.py

@@ -0,0 +1,235 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.happyhorse import HappyHorseClient
+from runapi.happyhorse.resources.edit_video import EditVideo
+from runapi.happyhorse.resources.image_to_video import ImageToVideo
+from runapi.happyhorse.resources.text_to_video import TextToVideo
+from runapi.happyhorse.types import CompletedTextToVideoResponse, 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(HappyHorseClient(api_key="k", http_client=FakeHttp()), HappyHorseClient)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(HappyHorseClient(http_client=FakeHttp()), HappyHorseClient)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(HappyHorseClient(http_client=FakeHttp()), HappyHorseClient)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        HappyHorseClient()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = HappyHorseClient(api_key="k", http_client=fake)
+    assert client.text_to_video._http is fake
+    assert client.image_to_video._http is fake
+    assert client.edit_video._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_video, TextToVideo)
+    assert isinstance(client.image_to_video, ImageToVideo)
+    assert isinstance(client.edit_video, EditVideo)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_text_to_video_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = HappyHorseClient(api_key="k", http_client=fake)
+    result = client.text_to_video.create(
+        model="happyhorse-text-to-video",
+        prompt="a horse",
+        aspect_ratio="16:9",
+        seed=None,
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/happyhorse/text_to_video",
+            {"model": "happyhorse-text-to-video", "prompt": "a horse", "aspect_ratio": "16:9"},
+        ),
+    ]
+    assert isinstance(result, TextToVideoResponse)
+
+
+def test_text_to_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = HappyHorseClient(api_key="k", http_client=fake)
+    client.text_to_video.get("t1")
+    assert fake.calls == [("get", "/api/v1/happyhorse/text_to_video/t1", None)]
+
+
+def test_image_to_video_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = HappyHorseClient(api_key="k", http_client=fake)
+    client.image_to_video.create(
+        model="happyhorse-image-to-video",
+        first_frame_image_url="https://example.com/a.jpg",
+        output_resolution="720p",
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/happyhorse/image_to_video",
+            {
+                "model": "happyhorse-image-to-video",
+                "first_frame_image_url": "https://example.com/a.jpg",
+                "output_resolution": "720p",
+            },
+        ),
+    ]
+
+
+def test_edit_video_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = HappyHorseClient(api_key="k", http_client=fake)
+    client.edit_video.create(
+        model="happyhorse-edit-video",
+        prompt="brighten it",
+        source_video_url="https://example.com/v.mp4",
+    )
+    assert fake.calls == [
+        (
+            "post",
+            "/api/v1/happyhorse/edit_video",
+            {
+                "model": "happyhorse-edit-video",
+                "prompt": "brighten it",
+                "source_video_url": "https://example.com/v.mp4",
+            },
+        ),
+    ]
+
+
+def test_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "t1", "status": "pending"},
+        {"id": "t1", "status": "completed", "videos": [{"url": "https://x/y.mp4"}]},
+    )
+    client = HappyHorseClient(api_key="k", http_client=fake)
+    result = client.text_to_video.run(model="happyhorse-text-to-video", prompt="a serene river")
+    assert isinstance(result, CompletedTextToVideoResponse)
+    assert result.videos[0].url == "https://x/y.mp4"
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_text_to_video_rejects_unknown_model():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model is required"):
+        client.text_to_video.create(model="nope", prompt="hi")
+
+
+def test_text_to_video_requires_prompt():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.text_to_video.create(model="happyhorse-text-to-video")
+
+
+def test_text_to_video_rejects_reference_images_for_non_character():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference_image_urls is only supported for happyhorse-character"):
+        client.text_to_video.create(
+            model="happyhorse-text-to-video",
+            prompt="hi",
+            reference_image_urls=["https://x/a.jpg"],
+        )
+
+
+def test_character_model_requires_reference_images_range():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference_image_urls must include between 1 and 9 entries"):
+        client.text_to_video.create(model="happyhorse-character", prompt="hi", reference_image_urls=[])
+
+
+def test_text_to_video_duration_range():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="duration_seconds must be an integer between 3 and 15"):
+        client.text_to_video.create(model="happyhorse-text-to-video", prompt="hi", duration_seconds=99)
+
+
+def test_text_to_video_rejects_invalid_output_resolution():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid output_resolution"):
+        client.text_to_video.create(
+            model="happyhorse-text-to-video", prompt="hi", output_resolution="4k"
+        )
+
+
+def test_image_to_video_requires_model():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model is required"):
+        client.image_to_video.create(model="wrong", first_frame_image_url="https://x/a.jpg")
+
+
+def test_image_to_video_requires_first_frame():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="first_frame_image_url is required"):
+        client.image_to_video.create(model="happyhorse-image-to-video")
+
+
+def test_edit_video_requires_source_video_url():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_video_url is required"):
+        client.edit_video.create(model="happyhorse-edit-video", prompt="brighten")
+
+
+def test_edit_video_reference_images_max():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference_image_urls must include at most 5 entries"):
+        client.edit_video.create(
+            model="happyhorse-edit-video",
+            prompt="brighten",
+            source_video_url="https://x/v.mp4",
+            reference_image_urls=["a", "b", "c", "d", "e", "f"],
+        )
+
+
+def test_edit_video_rejects_invalid_audio_setting():
+    client = HappyHorseClient(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="Invalid audio_setting"):
+        client.edit_video.create(
+            model="happyhorse-edit-video",
+            prompt="brighten",
+            source_video_url="https://x/v.mp4",
+            audio_setting="muted",
+        )