feat(kosong,kimi): add video upload support for Kimi provider (#656)

Signed-off-by: Richard Chien <stdrc@outlook.com>
Co-authored-by: Richard Chien <stdrc@outlook.com>

Author: xxchan

CHANGELOG.md

@@ -11,6 +11,7 @@ Only write entries that are worth mentioning to users.
 
 ## Unreleased
 
+- Tool: Upload videos to Kimi files API when using Kimi provider, replacing inline data URLs with `ms://` references
 - Config: Add `reserved_context_size` setting to customize auto-compaction trigger threshold (default: 50000 tokens)
 
 ## 0.81 (2026-01-21)

packages/kosong/CHANGELOG.md

@@ -3,6 +3,8 @@
 ## Unreleased
 
 - Control thinking mode via `extra_body` parameter instead of legacy `reasoning_effort`
+- Add `files` property to `Kimi` provider that returns a `KimiFiles` object
+- Add `KimiFiles.upload_video()` method for uploading videos to Kimi files API, returning `VideoURLPart`
 
 ## 0.38.0 (2026-01-15)
 

packages/kosong/src/kosong/chat_provider/kimi.py

@@ -1,11 +1,13 @@
 import copy
+import mimetypes
 import os
 import uuid
 from collections.abc import AsyncIterator, Sequence
 from typing import TYPE_CHECKING, Any, Literal, Self, Unpack, cast
 
 import httpx
-from openai import AsyncOpenAI, AsyncStream, OpenAIError, omit
+from openai import AsyncOpenAI, AsyncStream, BaseModel, OpenAIError, omit
+from openai._types import RequestFiles, RequestOptions
 from openai.types.chat import (
     ChatCompletion,
     ChatCompletionChunk,
@@ -24,7 +26,15 @@
     TokenUsage,
 )
 from kosong.chat_provider.openai_common import convert_error, tool_to_openai
-from kosong.message import ContentPart, Message, TextPart, ThinkPart, ToolCall, ToolCallPart
+from kosong.message import (
+    ContentPart,
+    Message,
+    TextPart,
+    ThinkPart,
+    ToolCall,
+    ToolCallPart,
+    VideoURLPart,
+)
 from kosong.tooling import Tool
 
 if TYPE_CHECKING:
@@ -216,6 +226,50 @@ def model_parameters(self) -> dict[str, Any]:
         model_parameters.update(self._generation_kwargs)
         return model_parameters
 
+    @property
+    def files(self) -> "KimiFiles":
+        return KimiFiles(self.client)
+
+
+class KimiFiles:
+    def __init__(self, client: AsyncOpenAI) -> None:
+        self._client = client
+
+    async def upload_video(self, *, data: bytes, mime_type: str) -> VideoURLPart:
+        """Upload a video to Kimi files API and return a video URL content part."""
+        if not mime_type.startswith("video/"):
+            raise ChatProviderError(f"Expected a video mime type, got {mime_type}")
+        url = await self._upload_file(data=data, mime_type=mime_type, purpose="video")
+        return VideoURLPart(video_url=VideoURLPart.VideoURL(url=url))
+
+    async def _upload_file(self, *, data: bytes, mime_type: str, purpose: "KimiFilePurpose") -> str:
+        filename = _guess_filename(mime_type)
+        files: RequestFiles = {"file": (filename, data, mime_type)}
+        options: RequestOptions = {"headers": {"Content-Type": "multipart/form-data"}}
+        try:
+            response: KimiFileObject = await self._client.post(
+                "/files",
+                cast_to=KimiFileObject,
+                body={"purpose": purpose},
+                files=files,
+                options=options,
+            )
+        except (OpenAIError, httpx.HTTPError) as e:
+            raise convert_error(e) from e
+        return f"ms://{response.id}"
+
+
+class KimiFileObject(BaseModel):
+    id: str
+
+
+type KimiFilePurpose = Literal["video", "image"]
+
+
+def _guess_filename(mime_type: str) -> str:
+    extension = mimetypes.guess_extension(mime_type) or ".bin"
+    return f"upload{extension}"
+
 
 def _convert_message(message: Message) -> ChatCompletionMessageParam:
     message = message.model_copy(deep=True)

src/kimi_cli/tools/file/read.py

@@ -3,6 +3,7 @@
 from typing import override
 
 from kaos.path import KaosPath
+from kosong.chat_provider.kimi import Kimi
 from kosong.tooling import CallableTool2, ToolError, ToolOk, ToolReturnValue
 from pydantic import BaseModel, Field
 
@@ -67,6 +68,7 @@ def __init__(self, runtime: Runtime) -> None:
             },
         )
         super().__init__(description=description)
+        self._runtime = runtime
         self._work_dir = runtime.builtin_args.KIMI_WORK_DIR
 
     async def _validate_path(self, path: KaosPath) -> ToolError | None:
@@ -105,13 +107,21 @@ async def _read_media(self, path: KaosPath, file_type: FileType) -> ToolReturnVa
                 brief="File too large",
             )
 
-        data = await path.read_bytes()
-        data_url = _to_data_url(file_type.mime_type, data)
         match file_type.kind:
             case "image":
+                data = await path.read_bytes()
+                data_url = _to_data_url(file_type.mime_type, data)
                 part = ImageURLPart(image_url=ImageURLPart.ImageURL(url=data_url))
             case "video":
-                part = VideoURLPart(video_url=VideoURLPart.VideoURL(url=data_url))
+                data = await path.read_bytes()
+                if (llm := self._runtime.llm) and isinstance(llm.chat_provider, Kimi):
+                    part = await llm.chat_provider.files.upload_video(
+                        data=data,
+                        mime_type=file_type.mime_type,
+                    )
+                else:
+                    data_url = _to_data_url(file_type.mime_type, data)
+                    part = VideoURLPart(video_url=VideoURLPart.VideoURL(url=data_url))
         return ToolOk(
             output=part,
             message=(