From 95969ef97b7b1da32c04310bf77f455bf2d7085e Mon Sep 17 00:00:00 2001
From: Carson <cpsievert1@gmail.com>
Date: Wed, 29 Jul 2026 09:45:48 -0500
Subject: [PATCH 1/2] feat(content): add video content types and file/YouTube
 helpers

Introduces ContentVideoInline and ContentVideoUrl (plus the shared
ContentVideo base and VideoContentTypes literal) to represent Gemini video
input: small inline clips, and public YouTube URLs referenced with no
upload and no MIME type. content_video_file() and content_video_youtube()
are the public constructors, exported from chatlas and chatlas.types
alongside the existing image/PDF helpers.
---
 chatlas/__init__.py         |   3 +
 chatlas/_content.py         |  95 ++++++++++++++++++++++++++
 chatlas/_content_video.py   | 129 ++++++++++++++++++++++++++++++++++++
 chatlas/types/__init__.py   |   8 +++
 tests/test_content_video.py | 127 +++++++++++++++++++++++++++++++++++
 5 files changed, 362 insertions(+)
 create mode 100644 chatlas/_content_video.py
 create mode 100644 tests/test_content_video.py

diff --git a/chatlas/__init__.py b/chatlas/__init__.py
index 22fe3b0e..14688d6c 100644
--- a/chatlas/__init__.py
+++ b/chatlas/__init__.py
@@ -13,6 +13,7 @@
 )
 from ._content_image import content_image_file, content_image_plot, content_image_url
 from ._content_pdf import content_pdf_file, content_pdf_url
+from ._content_video import content_video_file, content_video_youtube
 from ._files import FileManager
 from ._interpolate import interpolate, interpolate_file
 from ._parallel import parallel_chat, parallel_chat_structured, parallel_chat_text
@@ -84,6 +85,8 @@
     "content_image_url",
     "content_pdf_file",
     "content_pdf_url",
+    "content_video_file",
+    "content_video_youtube",
     "ContentToolRequest",
     "ContentToolResult",
     "FileManager",
diff --git a/chatlas/_content.py b/chatlas/_content.py
index 9e32c2e4..31699264 100644
--- a/chatlas/_content.py
+++ b/chatlas/_content.py
@@ -86,6 +86,22 @@ class ToolAnnotations(TypedDict, total=False):
 """
 
 
+VideoContentTypes = Literal[
+    "video/mp4",
+    "video/mpeg",
+    "video/mov",
+    "video/avi",
+    "video/x-flv",
+    "video/mpg",
+    "video/webm",
+    "video/wmv",
+    "video/3gpp",
+]
+"""
+Allowable content types for inline video. Only Gemini accepts video input.
+"""
+
+
 class ToolInfo(BaseModel):
     """
     Serializable tool information
@@ -134,6 +150,8 @@ def from_tool(cls, tool: "Tool | ToolBuiltIn") -> "ToolInfo":
     "text",
     "image_remote",
     "image_inline",
+    "video_inline",
+    "video_url",
     "tool_request",
     "tool_result",
     "tool_result_image",
@@ -255,6 +273,77 @@ def __str__(self):
         return f"![](data:{self.image_content_type};base64,{self.data})"
 
 
+class ContentVideo(Content):
+    """
+    Base class for video content.
+
+    This class is not meant to be used directly. Instead, use
+    [](`~chatlas.content_video_file`) or [](`~chatlas.content_video_youtube`).
+    """
+
+    pass
+
+
+class ContentVideoInline(ContentVideo):
+    """
+    Inline video content, for small clips.
+
+    This is the return type for [](`~chatlas.content_video_file`).
+    It's not meant to be used directly.
+
+    Only Gemini accepts video input, and only for requests that stay under
+    roughly 100 MB once base64-encoded; use `chat.files.upload()` for larger
+    files instead.
+
+    Parameters
+    ----------
+    video_content_type
+        The content type of the video.
+    data
+        The base64-encoded video data.
+    filename
+        The name of the video file, if known.
+    """
+
+    video_content_type: VideoContentTypes
+    data: str
+    filename: Optional[str] = None
+
+    content_type: ContentTypeEnum = "video_inline"
+
+    def __str__(self):
+        name = f" file={self.filename}" if self.filename else ""
+        return f"<video{name} mime_type={self.video_content_type}>"
+
+
+class ContentVideoUrl(ContentVideo):
+    """
+    A video referenced by URL, with no upload involved.
+
+    This is the return type for [](`~chatlas.content_video_youtube`).
+    It's not meant to be used directly.
+
+    Unlike [](`~chatlas.types.ContentUploaded`), this isn't a file a provider
+    is hosting on your behalf -- there's nothing to list, download, or
+    delete, and it doesn't expire. It's sent with no MIME type, since Gemini
+    determines the video format itself. As of this writing, Gemini only
+    accepts public YouTube URLs this way (up to 10 per request on Gemini
+    2.5+), and only Gemini accepts video URLs at all.
+
+    Parameters
+    ----------
+    url
+        The URL of the video.
+    """
+
+    url: str
+
+    content_type: ContentTypeEnum = "video_url"
+
+    def __str__(self):
+        return f"<video url={self.url}>"
+
+
 class ContentToolRequest(Content):
     """
     A request to call a tool/function
@@ -878,6 +967,8 @@ def __str__(self):
     ContentText,
     ContentImageRemote,
     ContentImageInline,
+    ContentVideoInline,
+    ContentVideoUrl,
     ContentToolRequest,
     ContentToolResult,
     ContentJson,
@@ -959,6 +1050,10 @@ def create_content(data: dict[str, Any]) -> ContentUnion:
         return ContentImageRemote.model_validate(data)
     elif ct == "image_inline":
         return ContentImageInline.model_validate(data)
+    elif ct == "video_inline":
+        return ContentVideoInline.model_validate(data)
+    elif ct == "video_url":
+        return ContentVideoUrl.model_validate(data)
     elif ct == "tool_request":
         return ContentToolRequest.model_validate(data)
     elif ct == "tool_result":
diff --git a/chatlas/_content_video.py b/chatlas/_content_video.py
new file mode 100644
index 00000000..1852146f
--- /dev/null
+++ b/chatlas/_content_video.py
@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+from ._content import ContentVideoInline, ContentVideoUrl, VideoContentTypes
+
+__all__ = (
+    "content_video_file",
+    "content_video_youtube",
+)
+
+
+def content_video_file(
+    path: str | Path,
+    mime_type: Optional[VideoContentTypes] = None,
+) -> ContentVideoInline:
+    """
+    Prepare a local video clip for input to a chat.
+
+    Only Gemini accepts video input, and only inline data that keeps the
+    total request under roughly 100 MB. For larger files, upload the video
+    once with `chat.files.upload()` and reuse the returned reference across
+    turns instead of re-sending its bytes.
+
+    Parameters
+    ----------
+    path
+        A path to a local video file.
+    mime_type
+        The video's MIME type. If not provided, it's guessed from `path`'s
+        extension.
+
+    Returns
+    -------
+    [](`~chatlas.types.Content`)
+        Content suitable for a [](`~chatlas.Turn`) object.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    ValueError
+        If `mime_type` isn't provided and can't be guessed from the file
+        extension.
+    """
+
+    if isinstance(path, str):
+        path = Path(path)
+
+    if not path.is_file():
+        raise FileNotFoundError(f"Video file not found: {path}")
+
+    if mime_type is None:
+        guessed = _VIDEO_EXTENSION_MIME_TYPES.get(path.suffix.lower())
+        if guessed is None:
+            raise ValueError(
+                f"Couldn't guess a video MIME type from extension {path.suffix!r}. "
+                f"Pass `mime_type` explicitly (one of {sorted(_VIDEO_EXTENSION_MIME_TYPES.values())})."
+            )
+        mime_type = guessed
+
+    with open(path, "rb") as f:
+        data = base64.b64encode(f.read()).decode("utf-8")
+
+    return ContentVideoInline(
+        video_content_type=mime_type,
+        data=data,
+        filename=path.name,
+    )
+
+
+def content_video_youtube(url: str) -> ContentVideoUrl:
+    """
+    Reference a public YouTube video for input to a chat.
+
+    Only Gemini accepts this: the URL is passed straight through with no
+    upload and no MIME type (Gemini fetches and determines the video format
+    itself). As of this writing, this is a free preview feature limited to
+    public (not private or unlisted) videos, up to 10 per request on Gemini
+    2.5+ models.
+
+    Parameters
+    ----------
+    url
+        A `youtube.com` or `youtu.be` video URL.
+
+    Returns
+    -------
+    [](`~chatlas.types.Content`)
+        Content suitable for a [](`~chatlas.Turn`) object.
+
+    Raises
+    ------
+    ValueError
+        If `url` doesn't look like a YouTube video URL.
+    """
+
+    if not _is_youtube_url(url):
+        raise ValueError(
+            f"{url!r} doesn't look like a YouTube video URL "
+            "(expected a youtube.com or youtu.be URL)."
+        )
+
+    return ContentVideoUrl(url=url)
+
+
+_VIDEO_EXTENSION_MIME_TYPES: dict[str, VideoContentTypes] = {
+    ".mp4": "video/mp4",
+    ".mpeg": "video/mpeg",
+    ".mpg": "video/mpg",
+    ".mov": "video/mov",
+    ".avi": "video/avi",
+    ".flv": "video/x-flv",
+    ".webm": "video/webm",
+    ".wmv": "video/wmv",
+    ".3gpp": "video/3gpp",
+    ".3gp": "video/3gpp",
+}
+
+
+def _is_youtube_url(url: str) -> bool:
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        return False
+    host = parsed.hostname or ""
+    return host in ("youtu.be", "youtube.com", "www.youtube.com", "m.youtube.com")
diff --git a/chatlas/types/__init__.py b/chatlas/types/__init__.py
index bc255998..65a82de7 100644
--- a/chatlas/types/__init__.py
+++ b/chatlas/types/__init__.py
@@ -20,9 +20,13 @@
     ContentToolResponseSearch,
     ContentToolResult,
     ContentUploaded,
+    ContentVideo,
+    ContentVideoInline,
+    ContentVideoUrl,
     ImageContentTypes,
     ToolAnnotations,
     ToolInfo,
+    VideoContentTypes,
 )
 from .._files import FileMetadata
 from .._parallel import StructuredChatResult
@@ -48,6 +52,9 @@
     "ContentToolRequestSearch",
     "ContentToolResponseSearch",
     "ContentUploaded",
+    "ContentVideo",
+    "ContentVideoInline",
+    "ContentVideoUrl",
     "FileMetadata",
     "FinishReason",
     "StructuredChatResult",
@@ -58,6 +65,7 @@
     "TokenUsage",
     "ToolAnnotations",
     "ToolInfo",
+    "VideoContentTypes",
     "MISSING_TYPE",
     "MISSING",
     "ModelInfo",
diff --git a/tests/test_content_video.py b/tests/test_content_video.py
new file mode 100644
index 00000000..7e0fea42
--- /dev/null
+++ b/tests/test_content_video.py
@@ -0,0 +1,127 @@
+import base64
+
+import pytest
+from chatlas import content_video_file, content_video_youtube
+from chatlas._content import ContentVideoInline, ContentVideoUrl, create_content
+from chatlas._turn import Turn, UserTurn
+
+
+def test_can_create_video_from_local_file(tmp_path):
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"\x00\x01fake mp4 bytes\x02")
+
+    obj = content_video_file(path)
+    assert isinstance(obj, ContentVideoInline)
+    assert obj.filename == "clip.mp4"
+    assert obj.video_content_type == "video/mp4"
+    assert base64.b64decode(obj.data) == b"\x00\x01fake mp4 bytes\x02"
+
+
+@pytest.mark.parametrize(
+    ("suffix", "mime_type"),
+    [
+        (".mp4", "video/mp4"),
+        (".mpeg", "video/mpeg"),
+        (".mpg", "video/mpg"),
+        (".mov", "video/mov"),
+        (".avi", "video/avi"),
+        (".flv", "video/x-flv"),
+        (".webm", "video/webm"),
+        (".wmv", "video/wmv"),
+        (".3gpp", "video/3gpp"),
+        (".3gp", "video/3gpp"),
+    ],
+)
+def test_content_video_file_guesses_mime_type_from_extension(
+    tmp_path, suffix, mime_type
+):
+    path = tmp_path / f"clip{suffix}"
+    path.write_bytes(b"data")
+    assert content_video_file(path).video_content_type == mime_type
+
+
+def test_content_video_file_explicit_mime_type_overrides_guess(tmp_path):
+    path = tmp_path / "clip.mp4"
+    path.write_bytes(b"data")
+    obj = content_video_file(path, mime_type="video/webm")
+    assert obj.video_content_type == "video/webm"
+
+
+def test_content_video_file_unknown_extension_raises(tmp_path):
+    path = tmp_path / "clip.xyz"
+    path.write_bytes(b"data")
+    with pytest.raises(ValueError, match="Couldn't guess a video MIME type"):
+        content_video_file(path)
+
+
+def test_content_video_file_missing_raises(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        content_video_file(tmp_path / "nope.mp4")
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "https://www.youtube.com/watch?v=9hE5-98ZeCg",
+        "https://youtu.be/9hE5-98ZeCg",
+        "https://m.youtube.com/watch?v=9hE5-98ZeCg",
+        "https://youtube.com/shorts/9hE5-98ZeCg",
+    ],
+)
+def test_content_video_youtube_accepts_youtube_urls(url):
+    obj = content_video_youtube(url)
+    assert isinstance(obj, ContentVideoUrl)
+    assert obj.url == url
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "https://example.com/video.mp4",
+        "not a url",
+        "ftp://youtube.com/watch?v=abc",
+    ],
+)
+def test_content_video_youtube_rejects_non_youtube_urls(url):
+    with pytest.raises(ValueError, match="doesn't look like a YouTube"):
+        content_video_youtube(url)
+
+
+def test_video_inline_round_trip():
+    video = ContentVideoInline(
+        video_content_type="video/mp4", data="ZmFrZQ==", filename="clip.mp4"
+    )
+    turn = UserTurn([video])
+    dumped = turn.model_dump(mode="json")
+    restored = Turn.model_validate(dumped)
+    assert isinstance(restored.contents[0], ContentVideoInline)
+    assert restored.contents[0].data == "ZmFrZQ=="
+    assert restored.contents[0].filename == "clip.mp4"
+
+
+def test_video_url_round_trip():
+    video = ContentVideoUrl(url="https://www.youtube.com/watch?v=9hE5-98ZeCg")
+    turn = UserTurn([video])
+    dumped = turn.model_dump(mode="json")
+    restored = Turn.model_validate(dumped)
+    assert isinstance(restored.contents[0], ContentVideoUrl)
+    assert restored.contents[0].url == "https://www.youtube.com/watch?v=9hE5-98ZeCg"
+
+
+def test_create_content_dispatches_video_types():
+    inline = create_content(
+        {
+            "content_type": "video_inline",
+            "video_content_type": "video/mp4",
+            "data": "ZmFrZQ==",
+        }
+    )
+    assert isinstance(inline, ContentVideoInline)
+
+    url = create_content(
+        {
+            "content_type": "video_url",
+            "url": "https://youtu.be/9hE5-98ZeCg",
+        }
+    )
+    assert isinstance(url, ContentVideoUrl)

From f88fc39a2f9a6793aad76d0fa51692adf34df07a Mon Sep 17 00:00:00 2001
From: Carson <cpsievert1@gmail.com>
Date: Wed, 29 Jul 2026 09:46:01 -0500
Subject: [PATCH 2/2] feat(google): wire up video input, reject it on other
 providers

ChatGoogle()/ChatVertex() send ContentVideoInline as inline Blob data and
ContentVideoUrl as a bare Part(file_data=FileData(...)) -- deliberately not
Part.from_uri(), which falls back to mimetypes.guess_type() and raises for
a YouTube watch URL that has no file extension to guess from.

ChatOpenAI(), ChatAnthropic(), and the OpenAI-compatible Chat Completions
providers (Groq, Mistral, Ollama, etc.) now raise a clear NotImplementedError
for video content instead of falling through to a generic "unknown content
type" error, consistent with how remote images are already rejected on
Google.

Also updates docs/chat.qmd and the quartodoc reference with a video input
section, and adds a CHANGELOG entry.
---
 CHANGELOG.md                              |  1 +
 chatlas/_provider_anthropic.py            |  6 +++++
 chatlas/_provider_google.py               | 20 +++++++++++++++++
 chatlas/_provider_openai.py               |  6 +++++
 chatlas/_provider_openai_completions.py   |  6 +++++
 docs/_quarto.yml                          |  9 ++++++++
 docs/get-started/chat.qmd                 | 18 +++++++++++++++
 tests/test_provider_anthropic.py          | 10 ++++++++-
 tests/test_provider_google.py             | 27 +++++++++++++++++++++++
 tests/test_provider_openai.py             | 10 ++++++++-
 tests/test_provider_openai_completions.py | 12 ++++++++++
 11 files changed, 123 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c3e68632..d631efcd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   just the given input, while `"complete"` estimates the total tokens for the
   next request, including history and system prompt where the provider
   supports it.
+* Added video input for `ChatGoogle()`/`ChatVertex()` (Gemini is the only provider that accepts video): `content_video_file()` for small inline clips (mp4, mpeg, mov, avi, x-flv, mpg, webm, wmv, 3gpp), and `content_video_youtube()` to reference a public YouTube URL directly, with no upload and no MIME type. Passing either to a provider other than Gemini raises a clear `NotImplementedError`. For larger local video files, use `chat.files.upload()` instead.
 
 ### Improvements
 
diff --git a/chatlas/_provider_anthropic.py b/chatlas/_provider_anthropic.py
index 992700cc..37e99d33 100644
--- a/chatlas/_provider_anthropic.py
+++ b/chatlas/_provider_anthropic.py
@@ -35,6 +35,7 @@
     ContentToolResponseSearch,
     ContentToolResult,
     ContentUploaded,
+    ContentVideo,
     ProviderAnnotation,
 )
 from ._files import FileMetadata, maybe_write, open_binary
@@ -830,6 +831,11 @@ def _as_content_block(content: Content) -> "ContentBlockParam":
                     "url": content.url,
                 },
             }
+        elif isinstance(content, ContentVideo):
+            raise NotImplementedError(
+                "Video input isn't supported by Anthropic. Only ChatGoogle() "
+                "(Gemini) supports video."
+            )
         elif isinstance(content, ContentToolRequest):
             return {
                 "type": "tool_use",
diff --git a/chatlas/_provider_google.py b/chatlas/_provider_google.py
index 98e92da9..f224c696 100644
--- a/chatlas/_provider_google.py
+++ b/chatlas/_provider_google.py
@@ -28,6 +28,8 @@
     ContentToolResponseSearch,
     ContentToolResult,
     ContentUploaded,
+    ContentVideoInline,
+    ContentVideoUrl,
 )
 from ._files import FileMetadata, maybe_write
 from ._logging import log_model_default
@@ -607,6 +609,24 @@ def _as_part_type(self, content: Content) -> "Part":
                 "Remote images aren't supported by Google (Gemini). "
                 "Consider downloading the image and using content_image_file() instead."
             )
+        elif isinstance(content, ContentVideoInline):
+            from google.genai.types import Blob
+
+            return Part(
+                inline_data=Blob(
+                    data=base64.b64decode(content.data),
+                    mime_type=content.video_content_type,
+                )
+            )
+        elif isinstance(content, ContentVideoUrl):
+            from google.genai.types import FileData
+
+            # Not Part.from_uri(): it falls back to mimetypes.guess_type() when
+            # mime_type is omitted, which raises for a YouTube watch URL (no
+            # file extension to guess from). Gemini wants no mime_type at all
+            # here -- it determines the video format itself -- so build the
+            # Part directly instead.
+            return Part(file_data=FileData(file_uri=content.url))
         elif isinstance(content, ContentToolRequest):
             return Part(
                 function_call=FunctionCall(
diff --git a/chatlas/_provider_openai.py b/chatlas/_provider_openai.py
index 02c8341b..c9c1b62a 100644
--- a/chatlas/_provider_openai.py
+++ b/chatlas/_provider_openai.py
@@ -32,6 +32,7 @@
     ContentToolRequestSearch,
     ContentToolResult,
     ContentUploaded,
+    ContentVideo,
     ProviderAnnotation,
 )
 from ._files import FileMetadata, maybe_write, open_binary
@@ -712,6 +713,11 @@ def as_input_param(content: Content, role: Role) -> "ResponseInputItemParam":
             },
             role,
         )
+    elif isinstance(content, ContentVideo):
+        raise NotImplementedError(
+            "Video input isn't supported by OpenAI. Only ChatGoogle() (Gemini) "
+            "supports video."
+        )
     elif isinstance(content, ContentThinking):
         # Filter out 'status' which is output-only and not accepted as input
         extra = content.extra or {}
diff --git a/chatlas/_provider_openai_completions.py b/chatlas/_provider_openai_completions.py
index d99de9d3..e19461ae 100644
--- a/chatlas/_provider_openai_completions.py
+++ b/chatlas/_provider_openai_completions.py
@@ -29,6 +29,7 @@
     ContentToolRequest,
     ContentToolResult,
     ContentUploaded,
+    ContentVideo,
 )
 from ._logging import log_model_default
 from ._merge import merge_dicts
@@ -405,6 +406,11 @@ def _turns_as_inputs(self, turns: list[Turn]) -> list["ChatCompletionMessagePara
                                 "API), or pass the image inline via content_image_file()."
                             )
                         contents.append({"type": "file", "file": {"file_id": x.id}})
+                    elif isinstance(x, ContentVideo):
+                        raise NotImplementedError(
+                            f"Video input isn't supported by {self.name}. Only "
+                            "ChatGoogle() (Gemini) supports video."
+                        )
                     elif isinstance(x, ContentToolResult):
                         tool_results.append(
                             ChatCompletionToolMessageParam(
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
index 453f7677..040bca49 100644
--- a/docs/_quarto.yml
+++ b/docs/_quarto.yml
@@ -179,6 +179,11 @@ quartodoc:
       contents:
         - content_pdf_file
         - content_pdf_url
+    - title: Video input
+      desc: Submit video input to the chat (Gemini only)
+      contents:
+        - content_video_file
+        - content_video_youtube
     - title: Tool calling
       desc: Add context to python function before registering it as a tool.
       contents:
@@ -235,10 +240,14 @@ quartodoc:
         - types.ContentToolRequestFetch
         - types.ContentToolResponseFetch
         - types.ContentUploaded
+        - types.ContentVideo
+        - types.ContentVideoInline
+        - types.ContentVideoUrl
         - types.ChatResponse
         - types.ChatResponseAsync
         - types.FileMetadata
         - types.ImageContentTypes
+        - types.VideoContentTypes
         - types.MISSING_TYPE
         - types.MISSING
         - types.SubmitInputArgsT
diff --git a/docs/get-started/chat.qmd b/docs/get-started/chat.qmd
index 774e68c5..f4506023 100644
--- a/docs/get-started/chat.qmd
+++ b/docs/get-started/chat.qmd
@@ -108,6 +108,24 @@ chat.chat(uploaded, "Now list the risks mentioned.")
 
 See [`chat.files`](../reference/FileManager.qmd) for the full set of upload/list/download/delete operations and provider support notes, and [`ContentUploaded`](../reference/types.ContentUploaded.qmd) for the reference type it returns.
 
+::: callout-note
+### Video input (Gemini only)
+
+Of the major providers, only `ChatGoogle()`/`ChatVertex()` (Gemini) accepts video. For a small local clip, use [`content_video_file()`](../reference/content_video_file.qmd); for anything larger, prefer `chat.files.upload()` above. A public YouTube video can be referenced directly, with no upload at all:
+
+```python
+import chatlas as ctl
+
+chat = ctl.ChatGoogle()
+chat.chat(
+  ctl.content_video_youtube("https://www.youtube.com/watch?v=9hE5-98ZeCg"),
+  "Summarize this video in 3 sentences.",
+)
+```
+
+This is a free preview feature limited to public videos, up to 10 per request on Gemini 2.5+ models. Passing video content to any other provider raises a clear error.
+:::
+
 ## Chat history
 
 Note that `chat` is a stateful object, and accumulates conversation history by default.
diff --git a/tests/test_provider_anthropic.py b/tests/test_provider_anthropic.py
index f8b65e50..b7067c08 100644
--- a/tests/test_provider_anthropic.py
+++ b/tests/test_provider_anthropic.py
@@ -10,7 +10,7 @@
     tool_web_fetch,
     tool_web_search,
 )
-from chatlas._content import ContentUploaded
+from chatlas._content import ContentUploaded, ContentVideoUrl
 from chatlas._provider_anthropic import _ANTHROPIC_FINISH_REASON_MAP, AnthropicProvider
 from chatlas._provider_anthropic import (
     normalize_finish_reason as anthropic_normalize_finish_reason,
@@ -250,6 +250,14 @@ def test_anthropic_uploaded_cross_provider_raises():
         AnthropicProvider._as_content_block(c)
 
 
+def test_anthropic_video_raises_clear_error():
+    c = ContentVideoUrl(url="https://www.youtube.com/watch?v=9hE5-98ZeCg")
+    with pytest.raises(
+        NotImplementedError, match="Video input isn't supported by Anthropic"
+    ):
+        AnthropicProvider._as_content_block(c)
+
+
 def test_anthropic_uploaded_triggers_beta_header():
     provider = AnthropicProvider(model="claude-sonnet-4-6")
     turn = UserTurn(
diff --git a/tests/test_provider_google.py b/tests/test_provider_google.py
index cd5c67a1..020589e8 100644
--- a/tests/test_provider_google.py
+++ b/tests/test_provider_google.py
@@ -1,6 +1,9 @@
+import base64
+
 import pytest
 import requests
 from chatlas import ChatGoogle, ChatVertex, tool_web_fetch, tool_web_search
+from chatlas._content import ContentVideoInline, ContentVideoUrl
 from chatlas._provider_google import GoogleProvider
 from chatlas._provider_google import (
     normalize_finish_reason as google_normalize_finish_reason,
@@ -316,6 +319,28 @@ def test_google_pdfs():
     assert_pdf_local(chat_func)
 
 
+def test_google_video_inline_part():
+    provider = GoogleProvider(model="gemini-2.5-flash", api_key="dummy", kwargs=None)
+    video = ContentVideoInline(
+        video_content_type="video/mp4",
+        data=base64.b64encode(b"fake video bytes").decode("ascii"),
+    )
+    part = provider._as_part_type(video)
+    assert part.inline_data.mime_type == "video/mp4"
+    assert part.inline_data.data == b"fake video bytes"
+
+
+def test_google_video_youtube_part_has_no_mime_type():
+    # Part.from_uri() would raise here (mimetypes.guess_type() can't infer a
+    # type from a youtube.com/watch?v=... URL), so this also guards against
+    # accidentally routing ContentVideoUrl through that helper.
+    provider = GoogleProvider(model="gemini-2.5-flash", api_key="dummy", kwargs=None)
+    video = ContentVideoUrl(url="https://www.youtube.com/watch?v=9hE5-98ZeCg")
+    part = provider._as_part_type(video)
+    assert part.file_data.file_uri == "https://www.youtube.com/watch?v=9hE5-98ZeCg"
+    assert part.file_data.mime_type is None
+
+
 @pytest.mark.vcr
 def test_google_list_models():
     assert_list_models(ChatGoogle)
@@ -560,6 +585,8 @@ def test_google_batch_retrieve_handles_thought_signature_bytes():
     turn = provider.batch_result_turn(results[0], has_data_model=False)
     assert turn is not None
     assert turn.text == "42"
+
+
 @pytest.mark.vcr
 @retry_gemini_call
 def test_google_mixed_tools_end_to_end():
diff --git a/tests/test_provider_openai.py b/tests/test_provider_openai.py
index 0379e84c..aaa21fe0 100644
--- a/tests/test_provider_openai.py
+++ b/tests/test_provider_openai.py
@@ -3,7 +3,7 @@
 import httpx
 import pytest
 from chatlas import ChatOpenAI, tool_web_search
-from chatlas._content import ContentUploaded
+from chatlas._content import ContentUploaded, ContentVideoUrl
 from chatlas._provider_openai import as_input_param
 from chatlas._provider_openai import (
     normalize_finish_reason as openai_normalize_finish_reason,
@@ -87,6 +87,14 @@ def test_openai_uploaded_wrong_provider_raises():
         as_input_param(c, role="user")
 
 
+def test_openai_video_raises_clear_error():
+    c = ContentVideoUrl(url="https://www.youtube.com/watch?v=9hE5-98ZeCg")
+    with pytest.raises(
+        NotImplementedError, match="Video input isn't supported by OpenAI"
+    ):
+        as_input_param(c, role="user")
+
+
 @pytest.mark.vcr
 def test_openai_simple_request():
     chat = ChatOpenAI(
diff --git a/tests/test_provider_openai_completions.py b/tests/test_provider_openai_completions.py
index 8c0fb656..dd57f1c7 100644
--- a/tests/test_provider_openai_completions.py
+++ b/tests/test_provider_openai_completions.py
@@ -7,6 +7,7 @@
     ContentThinkingDelta,
     ContentToolRequest,
     ContentUploaded,
+    ContentVideoUrl,
 )
 from chatlas._provider_openai_completions import OpenAICompletionsProvider
 from chatlas._provider_openai_completions import (
@@ -134,6 +135,17 @@ def test_openai_custom_http_client():
     ChatOpenAICompletions(kwargs={"http_client": httpx.AsyncClient()})
 
 
+def test_openai_completions_video_raises_clear_error():
+    provider = OpenAICompletionsProvider(model="test")
+    turn = UserTurn(
+        [ContentVideoUrl(url="https://www.youtube.com/watch?v=9hE5-98ZeCg")]
+    )
+    with pytest.raises(
+        NotImplementedError, match="Video input isn't supported by OpenAI"
+    ):
+        provider._turns_as_inputs([turn])
+
+
 @pytest.mark.vcr
 def test_openai_list_models():
     assert_list_models(ChatOpenAICompletions)