runapi-veo-3-1 0.1.0__tar.gz

runapi_veo_3_1-0.1.0/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.4
+Name: runapi-veo-3-1
+Version: 0.1.0
+Summary: Veo 3.1 video client for RunAPI
+Project-URL: Homepage, https://runapi.ai/models/veo-3-1
+Project-URL: Documentation, https://runapi.ai/docs#sdk-veo-3-1
+Author-email: RunAPI <contact@runapi.ai>
+License-Expression: Apache-2.0
+Keywords: ai,runapi,sdk,text-to-video,veo,veo-3.1
+Requires-Python: >=3.9
+Requires-Dist: runapi-core
+Description-Content-Type: text/markdown
+
+# Veo API Python SDK for RunAPI
+
+The veo api Python SDK is the language-specific package for Veo 3 on RunAPI. Use this veo api package for text-to-video, video extension, and video upscaling flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This veo api README is the Python package guide inside the public `veo3-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/veo-3.1; for API reference, use https://runapi.ai/docs#veo-3.1; for SDK docs, use https://runapi.ai/docs#sdk-veo-3.1.
+
+## Install
+
+```bash
+pip install runapi-veo-3-1
+```
+
+## Quick start
+
+```python
+from runapi.veo_3_1 import Veo31Client
+
+client = Veo31Client()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="veo-3.1-fast",
+    prompt="A drone shot over mountains at sunset",
+    duration_seconds=8,
+)
+status = client.text_to_video.get(task.id)
+
+extension = client.extend_video.create(
+    source_task_id=task.id,
+    prompt="Continue the flight toward the coastline",
+)
+
+upscale = client.upscale_video.create(
+    source_task_id=task.id,
+    output_resolution="4k",
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_video.run(
+    model="veo-3.1-fast",
+    prompt="A serene mountain lake at dawn",
+)
+print(result.videos[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files 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.veo_3_1` error classes when building video jobs or scripts. Text-to-video request bodies can include `duration` with `4`, `6`, or `8` seconds. The available resources are `text_to_video`, `extend_video`, and `upscale_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/veo-3.1
+- SDK docs: https://runapi.ai/docs#sdk-veo-3.1
+- Product docs: https://runapi.ai/docs#veo-3.1
+- Pricing and rate limits: https://runapi.ai/models/veo-3.1/veo-3.1
+- Provider comparison: https://runapi.ai/providers/google
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/veo3-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_veo_3_1-0.1.0/README.md

@@ -0,0 +1,68 @@
+# Veo API Python SDK for RunAPI
+
+The veo api Python SDK is the language-specific package for Veo 3 on RunAPI. Use this veo api package for text-to-video, video extension, and video upscaling flows when your application needs JSON request bodies, task status lookup, and consistent RunAPI errors in Python.
+
+This veo api README is the Python package guide inside the public `veo3-sdk` repository. For the repository overview, start at `../README.md`; for model details, use https://runapi.ai/models/veo-3.1; for API reference, use https://runapi.ai/docs#veo-3.1; for SDK docs, use https://runapi.ai/docs#sdk-veo-3.1.
+
+## Install
+
+```bash
+pip install runapi-veo-3-1
+```
+
+## Quick start
+
+```python
+from runapi.veo_3_1 import Veo31Client
+
+client = Veo31Client()  # reads RUNAPI_API_KEY, or pass api_key="sk-..."
+
+task = client.text_to_video.create(
+    model="veo-3.1-fast",
+    prompt="A drone shot over mountains at sunset",
+    duration_seconds=8,
+)
+status = client.text_to_video.get(task.id)
+
+extension = client.extend_video.create(
+    source_task_id=task.id,
+    prompt="Continue the flight toward the coastline",
+)
+
+upscale = client.upscale_video.create(
+    source_task_id=task.id,
+    output_resolution="4k",
+)
+```
+
+Use `create` to submit a task and return quickly, `get` to fetch the latest task state, and `run` when a script should create and poll until completion:
+
+```python
+result = client.text_to_video.run(
+    model="veo-3.1-fast",
+    prompt="A serene mountain lake at dawn",
+)
+print(result.videos[0].url)
+```
+
+In web request handlers, prefer `create` plus webhook or later `get` polling so a worker is not held open.
+
+RunAPI-generated file URLs are temporary. Download and store generated images, videos, audio, or other files 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.veo_3_1` error classes when building video jobs or scripts. Text-to-video request bodies can include `duration` with `4`, `6`, or `8` seconds. The available resources are `text_to_video`, `extend_video`, and `upscale_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/veo-3.1
+- SDK docs: https://runapi.ai/docs#sdk-veo-3.1
+- Product docs: https://runapi.ai/docs#veo-3.1
+- Pricing and rate limits: https://runapi.ai/models/veo-3.1/veo-3.1
+- Provider comparison: https://runapi.ai/providers/google
+- Full catalog: https://runapi.ai/models
+- Repository: https://github.com/runapi-ai/veo3-sdk
+
+## License
+
+Licensed under the Apache License, Version 2.0.

runapi_veo_3_1-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runapi-veo-3-1"
+version = "0.1.0"
+description = "Veo 3.1 video client for RunAPI"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "RunAPI", email = "contact@runapi.ai" }]
+keywords = ["runapi", "veo", "veo-3.1", "text-to-video", "ai", "sdk"]
+dependencies = ["runapi-core"]
+
+[project.urls]
+Homepage = "https://runapi.ai/models/veo-3-1"
+Documentation = "https://runapi.ai/docs#sdk-veo-3-1"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/runapi"]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+runapi-core = { workspace = true }
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.runapi]
+slug = "veo-3.1"

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/__init__.py

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

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/client.py

@@ -0,0 +1,31 @@
+"""Veo 3.1 client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from runapi.core import ClientOptions, HttpClient, resolve_api_key
+
+from .resources.extend_video import ExtendVideo
+from .resources.text_to_video import TextToVideo
+from .resources.upscale_video import UpscaleVideo
+
+
+class Veo31Client:
+    """Veo 3.1 video API client.
+
+    Example::
+
+        client = Veo31Client(api_key="sk-...")
+        result = client.text_to_video.run(
+            model="veo-3.1-fast", prompt="A drone shot over mountains at sunset"
+        )
+    """
+
+    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.extend_video = ExtendVideo(http)
+        self.upscale_video = UpscaleVideo(http)

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/contract_gen.py

@@ -0,0 +1,65 @@
+# Code generated by SdkContractGenerator. DO NOT EDIT.
+
+CONTRACT = {
+    "extend-video": {
+        "models": [],
+        "fields_by_model": {
+            "_": {
+                "seeds": {
+                    "type": "integer"
+                },
+                "source_task_id": {
+                    "required": True
+                }
+            }
+        }
+    },
+    "text-to-video": {
+        "models": ["veo-3.1", "veo-3.1-fast"],
+        "fields_by_model": {
+            "veo-3.1": {
+                "aspect_ratio": {
+                    "enum": ["16:9", "9:16", "auto"]
+                },
+                "duration_seconds": {
+                    "enum": [4, 6, 8],
+                    "type": "integer"
+                },
+                "input_mode": {
+                    "enum": ["text", "first_and_last_frames", "reference"]
+                },
+                "seeds": {
+                    "type": "integer"
+                }
+            },
+            "veo-3.1-fast": {
+                "aspect_ratio": {
+                    "enum": ["16:9", "9:16", "auto"]
+                },
+                "duration_seconds": {
+                    "enum": [4, 6, 8],
+                    "type": "integer"
+                },
+                "input_mode": {
+                    "enum": ["text", "first_and_last_frames", "reference"]
+                },
+                "seeds": {
+                    "type": "integer"
+                }
+            }
+        }
+    },
+    "upscale-video": {
+        "models": [],
+        "fields_by_model": {
+            "_": {
+                "index": {
+                    "type": "integer"
+                },
+                "output_resolution": {
+                    "enum": ["1080p", "4k"]
+                }
+            }
+        }
+    }
+}

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/resources/__init__.py

@@ -0,0 +1,5 @@
+from .extend_video import ExtendVideo
+from .text_to_video import TextToVideo
+from .upscale_video import UpscaleVideo
+
+__all__ = ["TextToVideo", "ExtendVideo", "UpscaleVideo"]

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/resources/extend_video.py

@@ -0,0 +1,60 @@
+"""Veo 3.1 video extension resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import CompletedExtendVideoResponse, ExtendVideoResponse
+
+
+class ExtendVideo(Resource):
+    """Extend a previously generated video by referencing its task id."""
+
+    ENDPOINT = "/api/v1/veo_3_1/extend_video"
+
+    RESPONSE_CLASS = ExtendVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedExtendVideoResponse
+
+    def run(self, **params: Any) -> Any:
+        """Extend a video and poll until it completes.
+
+        Args:
+            **params: extend-video parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) extend-video response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create an extend-video task and return immediately with an id.
+
+        Args:
+            **params: extend-video parameters (model, ...).
+
+        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 extend-video task.
+
+        Args:
+            id: The task id returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if not params.get("source_task_id"):
+            raise ValidationError("source_task_id is required")
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/resources/text_to_video.py

@@ -0,0 +1,100 @@
+"""Veo 3.1 text-to-video resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..contract_gen import CONTRACT
+from ..types import (
+    CompletedTextToVideoResponse,
+    TextToVideoResponse,
+)
+
+
+class TextToVideo(Resource):
+    """Generate videos from text, image, and reference-image prompts."""
+
+    ENDPOINT = "/api/v1/veo_3_1/text_to_video"
+
+    RESPONSE_CLASS = TextToVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedTextToVideoResponse
+
+    def run(self, **params: Any) -> Any:
+        """Generate a video and poll until it completes.
+
+        Args:
+            **params: text-to-video parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) text-to-video response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a text-to-video task and return immediately with an id.
+
+        Args:
+            **params: text-to-video parameters (model, ...).
+
+        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 returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        self._validate_contract(CONTRACT["text-to-video"], params)
+
+        if not params.get("prompt"):
+            raise ValidationError("prompt is required")
+
+        self._validate_input_mode(params)
+
+    def _validate_input_mode(self, params: Dict[str, Any]) -> None:
+        input_mode = params.get("input_mode")
+        if not input_mode:
+            return
+
+        if input_mode == "first_and_last_frames":
+            if not self._field_present(params, "first_frame_image_url"):
+                raise ValidationError("first_frame_image_url is required for first_and_last_frames")
+            if self._field_present(params, "reference_image_urls"):
+                raise ValidationError("reference_image_urls requires input_mode reference")
+        elif input_mode == "reference":
+            urls = params.get("reference_image_urls")
+            if not urls:
+                raise ValidationError("reference_image_urls is required for reference")
+            if not (isinstance(urls, list) and 1 <= len(urls) <= 3):
+                raise ValidationError("reference_image_urls must contain 1-3 items for reference")
+            model = params.get("model")
+            if model != "veo-3.1-fast":
+                raise ValidationError("reference requires model veo-3.1-fast")
+            ar = params.get("aspect_ratio")
+            if ar and ar != "16:9":
+                raise ValidationError("reference requires aspect_ratio 16:9")
+            if self._field_present(params, "first_frame_image_url") or self._field_present(params, "last_frame_image_url"):
+                raise ValidationError(
+                    "first_frame_image_url and last_frame_image_url require input_mode first_and_last_frames"
+                )
+        else:
+            if self._field_present(params, "first_frame_image_url") or self._field_present(params, "last_frame_image_url"):
+                raise ValidationError(
+                    "first_frame_image_url and last_frame_image_url require input_mode first_and_last_frames"
+                )
+            if self._field_present(params, "reference_image_urls"):
+                raise ValidationError("reference_image_urls requires input_mode reference")

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/resources/upscale_video.py

@@ -0,0 +1,65 @@
+"""Veo 3.1 video upscaling resource."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from runapi.core import Resource, ValidationError
+
+from ..types import (
+    OUTPUT_RESOLUTIONS,
+    CompletedUpscaleVideoResponse,
+    UpscaleVideoResponse,
+)
+
+
+class UpscaleVideo(Resource):
+    """Upscale a previously generated video by referencing its task id."""
+
+    ENDPOINT = "/api/v1/veo_3_1/upscale_video"
+
+    RESPONSE_CLASS = UpscaleVideoResponse
+    COMPLETED_RESPONSE_CLASS = CompletedUpscaleVideoResponse
+
+    def run(self, **params: Any) -> Any:
+        """Upscale a video and poll until it completes.
+
+        Args:
+            **params: video upscale parameters (model, ...).
+
+        Returns:
+            The completed (narrowed) video upscale response.
+        """
+        task = self.create(**params)
+        return self._poll_until_complete(lambda: self.get(task.id))
+
+    def create(self, **params: Any) -> Any:
+        """Create a video upscale task and return immediately with an id.
+
+        Args:
+            **params: video upscale parameters (model, ...).
+
+        Returns:
+            The task creation result with an id.
+        """
+        compacted = self._compact_params(params)
+        self._validate_params(compacted)
+        return self._request("post", self.ENDPOINT, body=compacted)
+
+    def get(self, id: str) -> Any:
+        """Fetch the current status of a video upscale task.
+
+        Args:
+            id: The task id returned by ``create``.
+
+        Returns:
+            The current task status.
+        """
+        return self._request("get", f"{self.ENDPOINT}/{id}")
+
+    def _validate_params(self, params: Dict[str, Any]) -> None:
+        if not params.get("source_task_id"):
+            raise ValidationError("source_task_id is required")
+        output_resolution = params.get("output_resolution")
+        if output_resolution not in OUTPUT_RESOLUTIONS:
+            raise ValidationError(f"output_resolution must be one of: {', '.join(OUTPUT_RESOLUTIONS)}")

runapi_veo_3_1-0.1.0/src/runapi/veo_3_1/types.py

@@ -0,0 +1,65 @@
+"""Veo 3.1 model lists, enums, and response models."""
+
+from __future__ import annotations
+
+from runapi.core import BaseModel, TaskResponse, optional, required
+
+OUTPUT_RESOLUTIONS = ["1080p", "4k"]
+
+
+class Video(BaseModel):
+    url = optional(str)
+    resolution = optional(str)
+    has_audio = optional()
+
+
+class Source(BaseModel):
+    url = optional(str)
+
+
+class AsyncTaskResponse(TaskResponse):
+    """Veo 3.1 async task status response."""
+
+    id = required(str)
+    status = optional(str, enum=lambda: TaskResponse.Status.ALL)
+
+
+class TextToVideoResponse(AsyncTaskResponse):
+    """Veo 3.1 text-to-video task status response."""
+
+    videos = optional([lambda: Video])
+    sources = optional([lambda: Source])
+
+
+class ExtendVideoResponse(AsyncTaskResponse):
+    """Veo 3.1 extend-video task status response."""
+
+    videos = optional([lambda: Video])
+    sources = optional([lambda: Source])
+
+
+class UpscaleVideoResponse(AsyncTaskResponse):
+    """Veo 3.1 video upscale task status response."""
+
+    source_task_id = optional(str)
+    videos = optional([lambda: Video])
+    sources = optional([lambda: Source])
+    media_ids = optional([str])
+
+
+class CompletedTextToVideoResponse(TextToVideoResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    videos = required([lambda: Video])
+
+
+class CompletedExtendVideoResponse(ExtendVideoResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    videos = required([lambda: Video])
+
+
+class CompletedUpscaleVideoResponse(UpscaleVideoResponse):
+    """Narrowed response from ``run()`` once polling observes completion."""
+
+    videos = required([lambda: Video])

runapi_veo_3_1-0.1.0/tests/test_client.py

@@ -0,0 +1,252 @@
+import pytest
+
+from runapi.core import config
+from runapi.core.errors import AuthenticationError, ValidationError
+from runapi.veo_3_1 import Veo31Client
+from runapi.veo_3_1.resources.extend_video import ExtendVideo
+from runapi.veo_3_1.resources.text_to_video import TextToVideo
+from runapi.veo_3_1.resources.upscale_video import UpscaleVideo
+from runapi.veo_3_1.types import (
+    CompletedExtendVideoResponse,
+    CompletedTextToVideoResponse,
+    CompletedUpscaleVideoResponse,
+    ExtendVideoResponse,
+    TextToVideoResponse,
+    UpscaleVideoResponse,
+)
+
+
+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(Veo31Client(api_key="k", http_client=FakeHttp()), Veo31Client)
+
+
+def test_falls_back_to_global(monkeypatch):
+    monkeypatch.setattr(config, "api_key", "global-key")
+    assert isinstance(Veo31Client(http_client=FakeHttp()), Veo31Client)
+
+
+def test_falls_back_to_env(monkeypatch):
+    monkeypatch.setenv("RUNAPI_API_KEY", "env-key")
+    assert isinstance(Veo31Client(http_client=FakeHttp()), Veo31Client)
+
+
+def test_raises_without_api_key():
+    with pytest.raises(AuthenticationError, match="API key is required"):
+        Veo31Client()
+
+
+# --- injection / accessors ------------------------------------------------
+
+
+def test_uses_injected_http_client():
+    fake = FakeHttp()
+    client = Veo31Client(api_key="k", http_client=fake)
+    assert client.text_to_video._http is fake
+    assert client.extend_video._http is fake
+    assert client.upscale_video._http is fake
+
+
+def test_exposes_resource_accessors():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    assert isinstance(client.text_to_video, TextToVideo)
+    assert isinstance(client.extend_video, ExtendVideo)
+    assert isinstance(client.upscale_video, UpscaleVideo)
+
+
+# --- request shapes -------------------------------------------------------
+
+
+def test_text_to_video_create_posts_compacted_body():
+    fake = FakeHttp({"id": "t1", "status": "pending"})
+    client = Veo31Client(api_key="k", http_client=fake)
+    result = client.text_to_video.create(
+        model="veo-3.1-fast", prompt="a kite", aspect_ratio="16:9", duration_seconds=None
+    )
+    assert fake.calls == [
+        ("post", "/api/v1/veo_3_1/text_to_video", {"model": "veo-3.1-fast", "prompt": "a kite", "aspect_ratio": "16:9"}),
+    ]
+    assert isinstance(result, TextToVideoResponse)
+
+
+def test_text_to_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "t1", "status": "processing"})
+    client = Veo31Client(api_key="k", http_client=fake)
+    client.text_to_video.get("t1")
+    assert fake.calls == [("get", "/api/v1/veo_3_1/text_to_video/t1", None)]
+
+
+def test_extend_video_create_posts_source_task_id():
+    fake = FakeHttp({"id": "e1", "status": "pending"})
+    client = Veo31Client(api_key="k", http_client=fake)
+    result = client.extend_video.create(source_task_id="t1", prompt="keep going")
+    assert fake.calls == [
+        ("post", "/api/v1/veo_3_1/extend_video", {"source_task_id": "t1", "prompt": "keep going"}),
+    ]
+    assert isinstance(result, ExtendVideoResponse)
+
+
+def test_extend_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "e1", "status": "processing"})
+    client = Veo31Client(api_key="k", http_client=fake)
+    client.extend_video.get("e1")
+    assert fake.calls == [("get", "/api/v1/veo_3_1/extend_video/e1", None)]
+
+
+def test_upscale_video_create_posts_source_task_id():
+    fake = FakeHttp({"id": "u1", "status": "pending"})
+    client = Veo31Client(api_key="k", http_client=fake)
+    result = client.upscale_video.create(source_task_id="t1", output_resolution="4k")
+    assert fake.calls == [
+        ("post", "/api/v1/veo_3_1/upscale_video", {"source_task_id": "t1", "output_resolution": "4k"}),
+    ]
+    assert isinstance(result, UpscaleVideoResponse)
+
+
+def test_upscale_video_get_fetches_by_id():
+    fake = FakeHttp({"id": "u1", "status": "processing"})
+    client = Veo31Client(api_key="k", http_client=fake)
+    client.upscale_video.get("u1")
+    assert fake.calls == [("get", "/api/v1/veo_3_1/upscale_video/u1", None)]
+
+
+# --- run narrowing --------------------------------------------------------
+
+
+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 = Veo31Client(api_key="k", http_client=fake)
+    result = client.text_to_video.run(model="veo-3.1-fast", prompt="a serene lake")
+    assert isinstance(result, CompletedTextToVideoResponse)
+    assert result.videos[0].url == "https://x/y.mp4"
+
+
+def test_extend_video_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "e1", "status": "pending"},
+        {"id": "e1", "status": "completed", "videos": [{"url": "https://x/e.mp4"}]},
+    )
+    client = Veo31Client(api_key="k", http_client=fake)
+    result = client.extend_video.run(source_task_id="t1", prompt="continue")
+    assert isinstance(result, CompletedExtendVideoResponse)
+    assert result.videos[0].url == "https://x/e.mp4"
+
+
+def test_upscale_video_run_narrows_completed_type():
+    fake = FakeHttp(
+        {"id": "u1", "status": "pending"},
+        {"id": "u1", "status": "completed", "videos": [{"url": "https://x/u.mp4"}]},
+    )
+    client = Veo31Client(api_key="k", http_client=fake)
+    result = client.upscale_video.run(source_task_id="t1", output_resolution="1080p")
+    assert isinstance(result, CompletedUpscaleVideoResponse)
+    assert result.videos[0].url == "https://x/u.mp4"
+
+
+# --- validation -----------------------------------------------------------
+
+
+def test_text_to_video_requires_model():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: veo-3.1, veo-3.1-fast"):
+        client.text_to_video.create(prompt="hi")
+
+
+def test_text_to_video_requires_prompt():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.text_to_video.create(model="veo-3.1-fast")
+
+
+def test_text_to_video_rejects_unknown_model():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="model must be one of: veo-3.1, veo-3.1-fast"):
+        client.text_to_video.create(model="nope", prompt="hi")
+
+
+def test_text_to_video_rejects_invalid_aspect_ratio():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="aspect_ratio must be one of: 16:9, 9:16, auto"):
+        client.text_to_video.create(model="veo-3.1-fast", prompt="hi", aspect_ratio="4:3")
+
+
+def test_text_to_video_rejects_invalid_duration():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="duration_seconds must be one of: 4, 6, 8"):
+        client.text_to_video.create(model="veo-3.1-fast", prompt="hi", duration_seconds=5)
+
+
+def test_first_and_last_frames_requires_first_frame():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="first_frame_image_url is required for first_and_last_frames"):
+        client.text_to_video.create(model="veo-3.1-fast", prompt="hi", input_mode="first_and_last_frames")
+
+
+def test_reference_requires_reference_image_urls():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference_image_urls is required for reference"):
+        client.text_to_video.create(model="veo-3.1-fast", prompt="hi", input_mode="reference")
+
+
+def test_reference_requires_fast_model():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference requires model veo-3.1-fast"):
+        client.text_to_video.create(
+            model="veo-3.1", prompt="hi", input_mode="reference", reference_image_urls=["https://x/a.png"]
+        )
+
+
+def test_reference_image_urls_without_reference_mode_rejected():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="reference_image_urls requires input_mode reference"):
+        client.text_to_video.create(
+            model="veo-3.1-fast", prompt="hi", input_mode="text", reference_image_urls=["https://x/a.png"]
+        )
+
+
+def test_extend_video_requires_source_task_id():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_task_id is required"):
+        client.extend_video.create(prompt="continue")
+
+
+def test_extend_video_requires_prompt():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="prompt is required"):
+        client.extend_video.create(source_task_id="t1")
+
+
+def test_upscale_video_requires_source_task_id():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="source_task_id is required"):
+        client.upscale_video.create(output_resolution="4k")
+
+
+def test_upscale_video_rejects_invalid_output_resolution():
+    client = Veo31Client(api_key="k", http_client=FakeHttp())
+    with pytest.raises(ValidationError, match="output_resolution must be one of"):
+        client.upscale_video.create(source_task_id="t1", output_resolution="720p")