Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: MCP returns key-free download links and finds media, voices and video frames again (#14079)

Etherl904a61547683
diff --git a/studio/MCP.md b/studio/MCP.md
index 5dab0708b61..a0057137d30 100644
--- a/studio/MCP.md
+++ b/studio/MCP.md
@@ -279,6 +279,8 @@ api_key_format = "Bearer {token}"
| `analyze_audio` | A clip's duration, loudness, true peak, clipping and speech span, plus a match score against `expected_text`. |
| `generate_video` | Start a video, with a seed, frame count, last frame and image or audio references. One renders at a time. Poll it with `get_job`. |
| `get_job` | The state of a video, recipe or export job. |
+| `list_media` | Earlier images, audio clips, videos, transcripts and saved voices, a page at a time. |
+| `voices` | List, save, rename and delete saved voices. |
| `run_recipe` | Validate, preview or run a Data Recipe. |
| `datasets` | List, check, download and follow training datasets. |
| `start_training` | Start LLM or image LoRA training. Follow it with `studio_status`. |
@@ -294,10 +296,22 @@ cancelling an export job stops only that job's own step.
### Media and files
Generated images, audio and videos are saved to Unsloth Studio's galleries, the same as
-in the UI. Tools return each item's id and URL. Small items also come back
-inline. Large images come back as a preview plus a link. A video comes back as a
-thumbnail plus a link, and the MP4 is never sent inline. Links point at
-Unsloth Studio's API, so fetch them with the same `Authorization: Bearer` key.
+in the UI. Tools return each item's id, its `url` and a `download_url`. The
+`download_url` works without the API key for about an hour. It is bound to your
+account and stops working when Unsloth Studio restarts, so call `list_media` for a
+fresh one. The `url` needs the same `Authorization: Bearer` key.
+
+`return_media` sets what else comes back. For images and video it defaults to
+`"inline"`: small images inline, large ones as a preview plus a link, and a video
+as a thumbnail plus a link. `"preview"` sends a small image of `preview_px` pixels
+(1024 by default), and `"link"` sends no media at all. Audio defaults to `"link"`.
+Pass `"inline"` to get a short clip itself. The MP4 is never sent inline.
+
+`list_media` pages through earlier images, audio clips, videos, transcripts and
+saved voices; pass its `next_cursor` back to get the next page. `voices` saves a
+voice from a clip, so `generate_audio` can reuse it as `reference={"voice_id": ...}`.
+A gallery video is an input too: `{"video_id": ..., "frame": "last"}` for an
+image, or `{"video_id": ..., "start_s": ..., "end_s": ...}` for its sound.
Media inputs can be an Unsloth Studio id, inline data, or a file path. **A file path
works only when the agent runs on the Unsloth Studio computer** and connects over
diff --git a/studio/backend/core/inference/audio_inputs.py b/studio/backend/core/inference/audio_inputs.py
index 565307a4b8c..fc0fd54d5eb 100644
--- a/studio/backend/core/inference/audio_inputs.py
+++ b/studio/backend/core/inference/audio_inputs.py
@@ -327,6 +327,49 @@ async def save_stream(
tmp.unlink(missing_ok = True)
+def save_from_media(
+ src: Path,
+ name: Optional[str],
+ start_s: float = 0.0,
+ end_s: Optional[float] = None,
+) -> tuple[dict[str, Any], bool]:
+ """Register the audio track of a media file (a gallery video), cut to ``[start_s, end_s)``,
+ as an input; ``(record, created)``. The same cut again returns the existing record."""
+ directory = inputs_dir()
+ full = directory / f".{uuid.uuid4().hex}.upload.tmp"
+ cut = directory / f".{uuid.uuid4().hex}.upload.tmp"
+ try:
+ try:
+ info = transcode(src, full)
+ except AudioInputError as exc:
+ if exc.status == 400 and "no audio" in exc.detail:
+ raise AudioInputError(400, "This video has no audio track.") from None
+ raise
+ rate = info["sample_rate"]
+ with wave.open(str(full), "rb") as reader:
+ total = reader.getnframes()
+ first = int(start_s * rate)
+ if first >= total:
+ raise AudioInputError(
+ 400,
+ f"start_s is past the end of the audio ({total / rate:.2f} s); "
+ "Unsloth Studio can only cut inside the track.",
+ )
+ last = total if end_s is None else min(total, max(first + 1, int(end_s * rate)))
+ reader.setpos(first)
+ data = reader.readframes(last - first)
+ with wave.open(str(cut), "wb") as writer:
+ writer.setparams(reader.getparams())
+ writer.writeframes(data)
+ payload = cut.read_bytes()
+ return _finish_upload(
+ directory, cut, hashlib.sha256(payload).hexdigest(), _clean_name(name), len(payload)
+ )
+ finally:
+ full.unlink(missing_ok = True)
+ cut.unlink(missing_ok = True)
+
+
def _find_by_sha(directory: Path, sha: str) -> Optional[tuple[str, dict[str, Any]]]:
now = _now()
for sidecar in directory.glob("*.json"):
diff --git a/studio/backend/core/inference/video_gallery.py b/studio/backend/core/inference/video_gallery.py
index 8ed827ffc21..26830c6ce10 100644
--- a/studio/backend/core/inference/video_gallery.py
+++ b/studio/backend/core/inference/video_gallery.py
@@ -33,6 +33,8 @@ _ID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
_JOB_OUTCOME_KEY = "_worker_outcome"
_job_lock = threading.Lock()
_THUMBNAIL_WIDTH = 192
+# A frame PNG is decoded and encoded whole, so refuse anything past 8K square.
+_FRAME_MAX_PIXELS = 8192 * 8192
def gallery_dir() -> Path:
@@ -256,6 +258,82 @@ def first_frame_webp(
raise RuntimeError(f"Thumbnail generation failed to decode the clip: {exc}") from exc
+def _frame_time(frame) -> float:
+ return float(frame.time) if frame.time is not None else 0.0
+
+
+def frame_png(
+ source: Path,
+ at: str = "first",
+ max_px: Optional[int] = None,
+) -> bytes:
+ """One frame of a clip as PNG: ``first``, ``last`` or the frame shown at ``at`` seconds,
+ scaled to fit ``max_px`` when given. ValueError for a bad or past-end ``at`` or a clip PyAV
+ cannot decode; FileNotFoundError when the file is gone."""
+ import io
+ import math
+
+ text = str(at).strip().lower()
+ seconds: Optional[float] = None
+ if text not in ("first", "last"):
+ try:
+ seconds = float(text)
+ except ValueError:
+ seconds = None
+ if seconds is None or not math.isfinite(seconds) or seconds < 0:
+ raise ValueError("at must be 'first', 'last' or a time in seconds.")
+ try:
+ import av
+ from PIL import Image
+ except Exception as exc: # noqa: BLE001 -- a missing decoder dependency
+ raise RuntimeError("Frame extraction needs the 'av' and 'Pillow' packages.") from exc
+ try:
+ with av.open(str(source)) as src:
+ if not src.streams.video:
+ raise ValueError("This clip has no video stream.")
+ stream = src.streams.video[0]
+ if stream.width * stream.height > _FRAME_MAX_PIXELS:
+ raise ValueError(f"{stream.width}x{stream.height} is too large to extract.")
+ duration = (src.duration or 0) / 1_000_000
+ if not duration and stream.duration is not None and stream.time_base:
+ duration = float(stream.duration * stream.time_base)
+ # Frame times and seeks are absolute; ``at`` counts from the stream's first timestamp.
+ origin = float(stream.start_time * stream.time_base) if stream.start_time else 0.0
+ frame = None
+ if text == "first":
+ frame = next(src.decode(stream), None)
+ elif seconds is not None:
+ if duration and seconds > duration:
+ raise ValueError(
+ f"at={seconds:g} is past the end of the clip ({duration:.2f} s)."
+ )
+ src.seek(int((origin + seconds) / stream.time_base), stream = stream, backward = True)
+ for candidate in src.decode(stream):
+ if frame is not None and _frame_time(candidate) > origin + seconds + 1e-6:
+ break
+ frame = candidate
+ else:
+ # Seek close to the end and keep the final frame; a failed seek falls back to a full decode.
+ for start in (max(0.0, duration - 2.0), 0.0):
+ src.seek(int((origin + start) / stream.time_base), stream = stream, backward = True)
+ for candidate in src.decode(stream):
+ frame = candidate
+ if frame is not None or start == 0.0:
+ break
+ if frame is None:
+ raise ValueError("This clip has no decodable frame there.")
+ image = frame.to_image()
+ except FileNotFoundError:
+ raise
+ except av.error.FFmpegError:
+ raise ValueError("This clip could not be decoded.") from None
+ if max_px:
+ image.thumbnail((max_px, max_px), Image.LANCZOS)
+ buf = io.BytesIO()
+ image.save(buf, format = "PNG")
+ return buf.getvalue()
+
+
def transcode_to_file(video_id: str, fmt: str) -> Optional[Path]:
"""Re-encode a stored MP4 for the Download menu into a TEMP FILE and return its path, or None
when the id doesn't resolve. Raises RuntimeError on missing codec/deps (route 501s). The caller
diff --git a/studio/backend/mcp_server.py b/studio/backend/mcp_server.py
index 1eff1076ddb..e4c35c0a42e 100644
--- a/studio/backend/mcp_server.py
+++ b/studio/backend/mcp_server.py
@@ -15,6 +15,7 @@ from studio_mcp.tools import (
export,
images,
jobs,
+ library,
models,
status,
text,
@@ -54,6 +55,7 @@ def create_studio_mcp() -> FastMCP:
data,
training,
export,
+ library,
cancel,
):
for tool, annotations, *schema in module.TOOLS:
diff --git a/studio/backend/routes/inference.py b/studio/backend/routes/inference.py
index 146cfb9b169..2a14d6a4878 100644
--- a/studio/backend/routes/inference.py
+++ b/studio/backend/routes/inference.py
@@ -51500,6 +51500,53 @@ async def get_gallery_audio_file(
)
[email protected]("/audio/gallery/{audio_id}/signed-url")
+async def get_gallery_audio_signed_url(
+ audio_id: str,
+ request: Request,
+ current_subject: str = Depends(get_current_subject),
+):
+ """A key-free link to one clip (bearer-gated to mint, HMAC to use), on the mount called."""
+ from auth.authentication import request_admitted_without_credential
+
+ if request_admitted_without_credential(request):
+ raise HTTPException(
+ status_code = 403,
+ detail = "Audio links can only be created from the Unsloth UI or with an API key.",
+ )
+ from core.inference import audio_gallery
+
+ if await asyncio.to_thread(audio_gallery.owned_audio_path, audio_id) is None:
+ raise HTTPException(status_code = 404, detail = "Audio not found.")
+ token = _sign_audio_id(audio_id)
+ return {
+ "url": _v1_url(
+ request, f"/api/inference/audio/gallery/{audio_id}/file-signed?token={token}"
+ )
+ }
+
+
[email protected]("/audio/gallery/{audio_id}/file-signed")
+async def get_gallery_audio_file_signed(audio_id: str, token: str = Query(...)):
+ """Serve one clip gated by the HMAC token instead of the bearer. No auth dependency, so the
+ token's account is bound with run_as: without it the owner's gallery would resolve."""
+ from core.inference import audio_gallery
+
+ account = media_link_account(_verify_audio_link_token(token), audio_id)
+ if account is None:
+ raise HTTPException(status_code = 401, detail = "Invalid or expired audio link.")
+ path = await asyncio.to_thread(run_as, account, audio_gallery.owned_audio_path, audio_id)
+ if path is None:
+ raise HTTPException(status_code = 404, detail = "Audio not found.")
+ from fastapi.responses import FileResponse
+
+ return FileResponse(
+ path,
+ media_type = "audio/wav",
+ headers = {"Cache-Control": "private, max-age=31536000, immutable"},
+ )
+
+
@studio_router.get("/audio/gallery/{audio_id}/source/file")
async def get_gallery_audio_source_file(
audio_id: str, current_subject: str = Depends(get_current_subject)
@@ -52287,6 +52334,39 @@ def _verify_image_link_token(token: str) -> Optional[str]:
return image_id
+# Audio gallery links for clients without the bearer (MCP hands them to agents): own secret, so a
+# token minted for one media type never serves another. TTL is read at call time.
+_AUDIO_LINK_TTL = 3600
+_AUDIO_LINK_SECRET = _secrets.token_bytes(32)
+
+
+def _sign_audio_id(audio_id: str) -> str:
+ exp = int(time.time()) + _AUDIO_LINK_TTL
+ payload = f"{media_link_target(audio_id)}.{exp}"
+ sig = _hmac.new(_AUDIO_LINK_SECRET, payload.encode(), _hashlib.sha256).hexdigest()
+ return f"{payload}.{sig}"
+
+
+def _verify_audio_link_token(token: str) -> Optional[str]:
+ """The link target a valid, unexpired audio token names, else None."""
+ try:
+ target, exp_s, sig = token.rsplit(".", 2)
+ except ValueError:
+ return None
+ expected = _hmac.new(
+ _AUDIO_LINK_SECRET, f"{target}.{exp_s}".encode(), _hashlib.sha256
+ ).hexdigest()
+ # Bytes: compare_digest raises TypeError on a non-ASCII str, a 500 where a bad link owes a 401.
+ if not _hmac.compare_digest(sig.encode(), expected.encode()):
+ return None
+ try:
+ if int(exp_s) < int(time.time()):
+ return None
+ except ValueError:
+ return None
+ return target
+
+
def _absolute_image_url(request: Request, image_id: str) -> str:
"""The absolute, directly fetchable link for one gallery image, on the request's own
scheme+host. Signed rather than bearer-gated (see above), so a standard image client can
@@ -52318,6 +52398,29 @@ async def get_gallery_image_file_signed(image_id: str, token: str = Query(...)):
)
+@studio_router.get("/images/gallery/{image_id}/signed-url")
+async def get_gallery_image_signed_url(
+ image_id: str,
+ request: Request,
+ current_subject: str = Depends(get_current_subject),
+):
+ """A key-free link to one gallery PNG (bearer-gated to mint, HMAC to use), relative like the
+ video one so it works behind any proxy."""
+ from auth.authentication import request_admitted_without_credential
+
+ if request_admitted_without_credential(request):
+ raise HTTPException(
+ status_code = 403,
+ detail = "Image links can only be created from the Unsloth UI or with an API key.",
+ )
+ from core.inference import image_gallery
+
+ if await asyncio.to_thread(image_gallery.owned_image_path, image_id) is None:
+ raise HTTPException(status_code = 404, detail = "Image not found.")
+ token = _sign_image_id(image_id)
+ return {"url": f"/api/inference/images/gallery/{image_id}/file-signed?token={token}"}
+
+
@router.post(
"/images/generations",
response_model = ImageGenerationResponse,
diff --git a/studio/backend/routes/video.py b/studio/backend/routes/video.py
index 64ca977fb39..6dc2d0b6f20 100644
--- a/studio/backend/routes/video.py
+++ b/studio/backend/routes/video.py
@@ -30,7 +30,7 @@ from datetime import datetime, timezone
from typing import Annotated, Any, Literal, Optional
from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
-from pydantic import ValidationError
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
from starlette.datastructures import UploadFile
from auth.authentication import (
@@ -52,6 +52,7 @@ from loggers.media_progress import (
reset_media_load_progress,
)
from models.inference import (
+ AudioInputRecord,
DiffusionDownloadPlanResponse,
GalleryFlagsPatch,
GalleryMoveRequest,
@@ -923,8 +924,8 @@ _VIDEO_LINK_TTL = 12 * 3600
_VIDEO_LINK_SECRET = _secrets.token_bytes(32)
-def _sign_video_id(video_id: str) -> str:
- exp = int(_time.time()) + _VIDEO_LINK_TTL
+def _sign_video_id(video_id: str, ttl_s: Optional[int] = None) -> str:
+ exp = int(_time.time()) + (_VIDEO_LINK_TTL if ttl_s is None else ttl_s)
payload = f"{media_link_target(video_id)}.{exp}"
sig = _hmac.new(_VIDEO_LINK_SECRET, payload.encode(), _hashlib.sha256).hexdigest()
return f"{payload}.{sig}"
@@ -955,10 +956,12 @@ async def get_gallery_video_signed_url(
video_id: str,
current_subject: str = Depends(get_current_subject),
no_credential: Annotated[bool, Depends(request_admitted_without_credential)] = False,
+ ttl_s: Optional[int] = Query(None, ge = 60, le = 12 * 3600),
):
"""A directly playable, range-capable link for one clip (bearer-gated to mint, HMAC to use).
- Returned as a relative URL so it works behind any proxy the page itself is served through."""
+ Returned as a relative URL so it works behind any proxy the page itself is served through.
+ ``ttl_s`` shortens the life (MCP asks for 1 h); omitted, the UI's 12 h applies."""
if no_credential:
raise HTTPException(
status_code = 403,
@@ -970,7 +973,7 @@ async def get_gallery_video_signed_url(
path = await asyncio.to_thread(video_gallery.owned_video_path, video_id)
if path is None:
raise HTTPException(status_code = 404, detail = "Video not found.")
- token = _sign_video_id(video_id)
+ token = _sign_video_id(video_id, ttl_s)
return {"url": f"/api/inference/video/gallery/{video_id}/file-signed?token={token}"}
@@ -996,6 +999,79 @@ async def get_gallery_video_file_signed(video_id: str, token: str = Query(...)):
)
[email protected]("/video/gallery/{video_id}/frame")
+async def get_gallery_video_frame(
+ video_id: str,
+ at: str = Query("first", max_length = 32),
+ max_px: Optional[int] = Query(None, ge = 32, le = 4096),
+ current_subject: str = Depends(get_current_subject),
+):
+ """One frame of an owned clip as PNG: ``at`` is ``first``, ``last`` or a time in seconds.
+ Nothing is saved to the Images gallery."""
+ from core.inference import video_gallery
+
+ path = await asyncio.to_thread(video_gallery.owned_video_path, video_id)
+ if path is None:
+ raise HTTPException(status_code = 404, detail = "Video not found.")
+ try:
+ data = await asyncio.to_thread(video_gallery.frame_png, path, at, max_px)
+ except FileNotFoundError:
+ raise HTTPException(status_code = 404, detail = "Video not found.") from None
+ except ValueError as exc:
+ raise HTTPException(status_code = 400, detail = str(exc)) from None
+ except RuntimeError as exc:
+ raise HTTPException(status_code = 501, detail = str(exc)) from None
+ return Response(
+ content = data,
+ media_type = "image/png",
+ headers = {"Cache-Control": "private, max-age=31536000, immutable"},
+ )
+
+
+class _VideoAudioInput(BaseModel):
+ model_config = ConfigDict(extra = "forbid")
+
+ start_s: float = Field(0.0, ge = 0, le = 3600)
+ end_s: Optional[float] = Field(None, gt = 0, le = 3600)
+
+ @model_validator(mode = "after")
+ def _ordered(self):
+ if self.end_s is not None and self.end_s <= self.start_s:
+ raise ValueError("end_s must be after start_s.")
+ return self
+
+
+ "/video/gallery/{video_id}/audio-input", status_code = 201, response_model = AudioInputRecord
+)
+async def extract_gallery_video_audio(
+ video_id: str,
+ body: _VideoAudioInput,
+ response: Response,
+ current_subject: str = Depends(get_current_subject),
+):
+ """Register an owned clip's audio track (optionally trimmed) as an audio input; the same
+ extract again returns the existing record with 200."""
+ from core.inference import audio_inputs, video_gallery
+
+ record = await asyncio.to_thread(video_gallery.get_record, video_id)
+ path = await asyncio.to_thread(video_gallery.owned_video_path, video_id)
+ if record is None or path is None:
+ raise HTTPException(status_code = 404, detail = "Video not found.")
+ # The name is cleaned as a file name, so '/' and line breaks in the prompt become spaces first.
+ prompt = " ".join(str(record.get("prompt") or "").replace("/", " ").replace("\\", " ").split())
+ name = f"{(prompt or 'Video')[:60]} (audio).wav"
+ try:
+ saved, created = await asyncio.to_thread(
+ audio_inputs.save_from_media, path, name, body.start_s, body.end_s
+ )
+ except audio_inputs.AudioInputError as exc:
+ raise HTTPException(status_code = exc.status, detail = exc.detail) from None
+ if not created:
+ response.status_code = 200
+ return AudioInputRecord(**saved)
+
+
@router.get("/video/gallery/{video_id}/export")
async def export_gallery_video(
video_id: str,
diff --git a/studio/backend/studio_mcp/inputs.py b/studio/backend/studio_mcp/inputs.py
index b2e4086cb39..782599f32b2 100644
--- a/studio/backend/studio_mcp/inputs.py
+++ b/studio/backend/studio_mcp/inputs.py
@@ -9,15 +9,15 @@ import base64
import binascii
import re
from pathlib import Path
-from typing import Any, Optional
+from typing import Annotated, Any, Literal, Optional, Union
from fastmcp.exceptions import ToolError
-from pydantic import BaseModel, ConfigDict, model_validator
+from pydantic import BaseModel, ConfigDict, Field, model_validator
from studio_mcp.caller import Caller
from studio_mcp.errors import raise_for_route
from studio_mcp.forward import forward
-from studio_mcp.media import image_gallery_path
+from studio_mcp.media import image_gallery_path, video_frame_path, video_gallery_path
PATH_REMOTE = (
"File paths work only when the agent runs on the Unsloth Studio computer. "
@@ -26,21 +26,29 @@ PATH_REMOTE = (
MAX_IMAGE_BYTES = 32 * 1024 * 1024 * 3 // 4
IMAGE_MIMES = ("image/png", "image/jpeg", "image/webp")
_DATA_URL = re.compile(r"^data:(image/(?:png|jpeg|webp));base64,(.*)$", re.DOTALL)
+_MEDIA_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
class ImageInput(BaseModel):
- """Exactly one of ``path`` (a file on the Unsloth Studio computer), ``data_url`` (data:image/png|jpeg|webp;base64,...) or ``gallery_id`` (an image in the Unsloth Studio Images gallery). Inline data rides in the MCP request, which is limited to 4 MiB."""
+ """Exactly one of ``path`` (a file on the Unsloth Studio computer), ``data_url`` (data:image/png|jpeg|webp;base64,...), ``gallery_id`` (an image in the Unsloth Studio Images gallery) or ``video_id`` (one frame of a clip in the Unsloth Studio Video gallery, picked by ``frame``: "first", "last" or seconds from the start; default "first"). Inline data rides in the MCP request, which is limited to 4 MiB."""
model_config = ConfigDict(extra = "forbid")
path: Optional[str] = None
data_url: Optional[str] = None
gallery_id: Optional[str] = None
+ video_id: Optional[str] = None
+ frame: Optional[Union[Literal["first", "last"], Annotated[float, Field(ge = 0)]]] = None
@model_validator(mode = "after")
def _exactly_one(self) -> "ImageInput":
- if sum(value is not None for value in (self.path, self.data_url, self.gallery_id)) != 1:
- raise ValueError("Give exactly one of path, data_url or gallery_id.")
+ sources = (self.path, self.data_url, self.gallery_id, self.video_id)
+ if sum(value is not None for value in sources) != 1:
+ raise ValueError("Give exactly one of path, data_url, gallery_id or video_id.")
+ if self.frame is not None and self.video_id is None:
+ raise ValueError("frame goes with video_id.")
+ if self.video_id is not None and not _MEDIA_ID.match(self.video_id):
+ raise ValueError("Unsloth Studio video ids are letters, digits, - and _.")
return self
@@ -98,6 +106,15 @@ async def resolve_image(
if match is None:
raise ToolError("data_url must be data:image/png, image/jpeg or image/webp;base64,...")
data = decode_base64(match.group(2), max_bytes, "data_url")
+ elif image.video_id is not None:
+ at = image.frame if image.frame is not None else "first"
+ response = await forward(
+ caller, "GET", video_frame_path(image.video_id), params = {"at": str(at)}
+ )
+ raise_for_route(response)
+ data = response.content
+ if len(data) > max_bytes:
+ raise ToolError(f"A frame of video {image.video_id} is too large to send")
else:
response = await forward(caller, "GET", image_gallery_path(image.gallery_id))
raise_for_route(response)
@@ -130,11 +147,11 @@ def data_url(data: bytes, mime: str) -> str:
MAX_AUDIO_BYTES = 200 * 1024 * 1024
-_AUDIO_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_AUDIO_ID = _MEDIA_ID
class AudioInput(BaseModel):
- """Exactly one of ``path`` (a file on the Unsloth Studio computer), ``data_base64`` with a ``filename``, or an Unsloth Studio id: ``input_id`` (an uploaded clip), ``clip_id`` (an Audio history clip) or ``voice_id`` (a saved voice). Inline data rides in the MCP request, which is limited to 4 MiB."""
+ """Exactly one of ``path`` (a file on the Unsloth Studio computer), ``data_base64`` with a ``filename``, or an Unsloth Studio id: ``input_id`` (an uploaded clip), ``clip_id`` (an Audio history clip), ``voice_id`` (a saved voice) or ``video_id`` (the sound of a clip in the Unsloth Studio Video gallery, optionally trimmed to ``start_s``..``end_s`` seconds). Inline data rides in the MCP request, which is limited to 4 MiB."""
model_config = ConfigDict(extra = "forbid")
@@ -144,17 +161,31 @@ class AudioInput(BaseModel):
input_id: Optional[str] = None
clip_id: Optional[str] = None
voice_id: Optional[str] = None
+ video_id: Optional[str] = None
+ start_s: Optional[Annotated[float, Field(ge = 0, le = 3600)]] = None
+ end_s: Optional[Annotated[float, Field(gt = 0, le = 3600)]] = None
@model_validator(mode = "after")
def _exactly_one(self) -> "AudioInput":
- sources = (self.path, self.data_base64, self.input_id, self.clip_id, self.voice_id)
+ sources = (
+ self.path,
+ self.data_base64,
+ self.input_id,
+ self.clip_id,
+ self.voice_id,
+ self.video_id,
+ )
if sum(value is not None for value in sources) != 1:
raise ValueError(
- "Give exactly one of path, data_base64, input_id, clip_id or voice_id."
+ "Give exactly one of path, data_base64, input_id, clip_id, voice_id or video_id."
)
if (self.filename is not None) != (self.data_base64 is not None):
raise ValueError("filename goes with data_base64, and data_base64 needs one.")
- for value in (self.input_id, self.clip_id, self.voice_id):
+ if (self.start_s is not None or self.end_s is not None) and self.video_id is None:
+ raise ValueError("start_s and end_s go with video_id.")
+ if self.end_s is not None and self.end_s <= (self.start_s or 0):
+ raise ValueError("end_s must be after start_s.")
+ for value in (self.input_id, self.clip_id, self.voice_id, self.video_id):
if value is not None and not _AUDIO_ID.match(value):
raise ValueError("Unsloth Studio audio ids are letters, digits, - and _.")
return self
@@ -189,6 +220,19 @@ async def audio_ref(caller: Caller, audio: AudioInput) -> dict[str, str]:
if audio.is_upload:
data, name = audio_bytes(caller, audio)
return {"input_id": await upload_audio(caller, data, name)}
+ if audio.video_id is not None:
+ # Unsloth Studio stores the clip's sound as an audio input; the same trim answers the same id.
+ trim = {"start_s": audio.start_s, "end_s": audio.end_s}
+ response = await forward(
+ caller,
+ "POST",
+ video_gallery_path(audio.video_id, "/audio-input"),
+ json_body = {key: value for key, value in trim.items() if value is not None},
+ )
+ record = raise_for_route(response)
+ if not isinstance(record, dict) or not isinstance(record.get("id"), str):
+ raise ToolError("Unsloth Studio did not store the video's audio")
+ return {"input_id": record["id"]}
for key in ("input_id", "clip_id", "voice_id"):
value = getattr(audio, key)
if value is not None:
diff --git a/studio/backend/studio_mcp/media.py b/studio/backend/studio_mcp/media.py
index bc7fe022f85..02531fa7ffe 100644
--- a/studio/backend/studio_mcp/media.py
+++ b/studio/backend/studio_mcp/media.py
@@ -7,20 +7,32 @@ from __future__ import annotations
import base64
import json
-from typing import Any, Optional
-from urllib.parse import quote, urlsplit
+import re
+from typing import Any, Literal, Optional, Union
+from urllib.parse import parse_qsl, quote, urlsplit
from fastmcp.exceptions import ToolError
from fastmcp.tools import ToolResult
from mcp.types import AudioContent, ImageContent, ResourceLink, TextContent
from studio_mcp.caller import Caller
+from studio_mcp.forward import forward
from studio_mcp.outputs import ToolOutput
# Agents put inline media straight into the model's context; past this a link is kinder.
INLINE_CAP = 1536 * 1024
MEDIA_PREFIXES = ("/v1/", "/api/inference/")
THUMB_SIDE = 1024
+# inline: the media itself when small; preview: a small image plus a link; link: only the link.
+ReturnMedia = Literal["inline", "preview", "link"]
+# Every link the MCP mints lasts about an hour, whatever the UI's own links last.
+MCP_LINK_TTL_S = 3600
+_TOKEN = re.compile(r"^[A-Za-z0-9_.:-]{1,512}$")
+SIGNED_BASES = {
+ "image": "/api/inference/images/gallery",
+ "audio": "/v1/audio/gallery",
+ "video": "/api/inference/video/gallery",
+}
def image_content(data: bytes, mime: str) -> ImageContent:
@@ -62,15 +74,47 @@ def public_url(caller: Caller, path: str) -> str:
return f"{_base(caller)}{parts.path}{query}"
-def image_gallery_path(image_id: str, thumb: bool = False) -> str:
+def image_gallery_path(image_id: str, thumb: Union[bool, int] = False) -> str:
+ """The gallery PNG, or with ``thumb`` a WebP thumbnail that many pixels on its long side (True: 1024)."""
path = f"/api/inference/images/gallery/{quote(image_id, safe = '')}/file"
- return f"{path}?thumb={THUMB_SIDE}" if thumb else path
+ if thumb is False:
+ return path
+ return f"{path}?thumb={THUMB_SIDE if thumb is True else int(thumb)}"
def audio_gallery_path(clip_id: str) -> str:
return f"/v1/audio/gallery/{quote(clip_id, safe = '')}/file"
+def video_gallery_path(video_id: str, suffix: str = "/file") -> str:
+ return f"{SIGNED_BASES['video']}/{quote(video_id, safe = '')}{suffix}"
+
+
+def video_frame_path(video_id: str) -> str:
+ return video_gallery_path(video_id, "/frame")
+
+
+def voice_path(voice_id: str = "", suffix: str = "") -> str:
+ return (
+ f"/v1/audio/voices/{quote(voice_id, safe = '')}{suffix}" if voice_id else "/v1/audio/voices"
+ )
+
+
+async def signed_url(caller: Caller, kind: str, media_id: str) -> Optional[str]:
+ """A link that works without the API key for about an hour, for this caller's account only, or None when Unsloth Studio would not mint one. Only the token is taken from the answer; the path is rebuilt here."""
+ base = f"{SIGNED_BASES[kind]}/{quote(media_id, safe = '')}"
+ params = {"ttl_s": MCP_LINK_TTL_S} if kind == "video" else None
+ try:
+ response = await forward(caller, "GET", f"{base}/signed-url", params = params)
+ url = response.json().get("url") if response.status_code == 200 else None
+ token = dict(parse_qsl(urlsplit(url).query)).get("token") if isinstance(url, str) else None
+ except Exception:
+ return None
+ if not isinstance(token, str) or not _TOKEN.match(token):
+ return None
+ return public_url(caller, f"{base}/file-signed?token={token}")
+
+
def media_result(contents: list[Any], output: ToolOutput) -> ToolResult:
"""Media plus the typed output, which also goes first as JSON text for clients that ignore structuredContent."""
structured = output.model_dump(mode = "json")
diff --git a/studio/backend/studio_mcp/outputs.py b/studio/backend/studio_mcp/outputs.py
index f05cc214ba1..c7085b5aab6 100644
--- a/studio/backend/studio_mcp/outputs.py
+++ b/studio/backend/studio_mcp/outputs.py
@@ -304,6 +304,8 @@ class SystemOneResult(ToolOutput):
class ImageItem(ToolOutput):
id: RouteText
url: str
+ # Works without the API key for about an hour; None when Unsloth Studio would not mint it.
+ download_url: Optional[str] = None
width: Optional[int] = None
height: Optional[int] = None
seed: Optional[int] = None
@@ -316,10 +318,29 @@ class ImageResult(ToolOutput):
images: list[ImageItem]
+class ImageRow(ToolOutput):
+ id: RouteText
+ url: str
+ download_url: Optional[str] = None
+ prompt: Optional[RouteText] = None
+ model: Optional[RouteText] = None
+ workflow: Optional[RouteText] = None
+ width: Optional[int] = None
+ height: Optional[int] = None
+ seed: Optional[int] = None
+ created_at: Optional[float] = None
+ pinned: bool = False
+
+
class AudioClip(ToolOutput):
id: RouteText
role: RouteText = "output"
+ workflow: Optional[RouteText] = None
+ voice_id: Optional[RouteText] = None
+ source_clip_id: Optional[RouteText] = None
+ seed: Optional[int] = None
url: str
+ download_url: Optional[str] = None
duration_s: Optional[float] = None
sample_rate: Optional[int] = None
@@ -352,6 +373,42 @@ class AudioResult(ToolOutput):
return super().from_route(payload, **overrides)
+class AudioRow(ToolOutput):
+ id: RouteText
+ url: str
+ download_url: Optional[str] = None
+ prompt: Optional[RouteText] = None
+ model: Optional[RouteText] = None
+ workflow: Optional[RouteText] = None
+ role: Optional[RouteText] = None
+ group_id: Optional[RouteText] = None
+ voice_id: Optional[RouteText] = None
+ source_clip_id: Optional[RouteText] = None
+ duration_s: Optional[float] = None
+ sample_rate: Optional[int] = None
+ created_at: Optional[RouteText] = None
+ pinned: bool = False
+
+
+class VoiceRow(ToolOutput):
+ id: RouteText
+ name: RouteText
+ # Needs the API key: voices have no key-free link.
+ url: str
+ transcript: Optional[RouteText] = None
+ language: Optional[RouteText] = None
+ duration_s: Optional[float] = None
+ sample_rate: Optional[int] = None
+ created_at: Optional[RouteText] = None
+
+
+class VoicesResult(ToolOutput):
+ action: RouteText
+ voices: Optional[list[VoiceRow]] = None
+ voice: Optional[VoiceRow] = None
+ removed: Optional[bool] = None
+
+
class TranscriptSegment(ToolOutput):
start: Optional[float] = None
end: Optional[float] = None
@@ -362,6 +419,7 @@ class TranscriptSegment(ToolOutput):
class TranscriptResult(ToolOutput):
text: str
+ transcript_id: Optional[RouteText] = None
language: Optional[RouteText] = None
model: Optional[RouteText] = None
segments: Optional[list[TranscriptSegment]] = None
@@ -371,6 +429,17 @@ class TranscriptResult(ToolOutput):
saved_to_history: bool = False
+class TranscriptRow(ToolOutput):
+ id: RouteText
+ title: Optional[RouteText] = None
+ text: str = ""
+ model: Optional[RouteText] = None
+ language: Optional[RouteText] = None
+ duration: Optional[float] = None
+ segment_count: Optional[int] = None
+ created_at: Optional[RouteText] = None
+
+
class AnalysisResult(ToolOutput):
duration_s: Optional[float] = None
sample_rate: Optional[int] = None
@@ -404,9 +473,37 @@ class VideoJobRef(ToolOutput):
class VideoInfo(ToolOutput):
# The MP4, for the agent or its user to download; the tool never fetches it.
url: str
+ download_url: Optional[str] = None
thumbnail_inline: bool = False
+class VideoRow(ToolOutput):
+ id: RouteText
+ url: str
+ download_url: Optional[str] = None
+ prompt: Optional[RouteText] = None
+ model: Optional[RouteText] = None
+ width: Optional[int] = None
+ height: Optional[int] = None
+ fps: Optional[float] = None
+ duration_s: Optional[float] = None
+ seed: Optional[int] = None
+ has_audio: bool = False
+ created_at: Optional[RouteText] = None
+ pinned: bool = False
+
+
+class MediaPage(ToolOutput):
+ kind: RouteText
+ images: Optional[list[ImageRow]] = None
+ audio: Optional[list[AudioRow]] = None
+ videos: Optional[list[VideoRow]] = None
+ transcripts: Optional[list[TranscriptRow]] = None
+ voices: Optional[list[VoiceRow]] = None
+ # Pass it back as cursor for the next page; None on the last page.
+ next_cursor: Optional[str] = None
+
+
class JobSummary(ToolOutput):
id: RouteText
status: RouteText
diff --git a/studio/backend/studio_mcp/tools/audio.py b/studio/backend/studio_mcp/tools/audio.py
index 6c09851497e..83db470599c 100644
--- a/studio/backend/studio_mcp/tools/audio.py
+++ b/studio/backend/studio_mcp/tools/audio.py
@@ -25,11 +25,13 @@ from studio_mcp.forward import forward, ndjson_last
from studio_mcp.inputs import AudioInput, audio_bytes, audio_ref, upload_audio
from studio_mcp.media import (
INLINE_CAP,
+ ReturnMedia,
audio_content,
audio_gallery_path,
media_result,
public_url,
resource_link,
+ signed_url,
)
from studio_mcp.outputs import (
AnalysisResult,
@@ -46,15 +48,20 @@ NOT_LOADED = "No model loaded"
_WAV_BYTES_PER_SAMPLE = 2
-async def _clip_contents(caller: Caller, clip: AudioClip) -> list[Any]:
- """A clip inline when its WAV fits the cap, else a link; one that cannot fit is never fetched."""
+async def _clip_contents(
+ caller: Caller,
+ clip: AudioClip,
+ return_media: ReturnMedia = "link",
+) -> list[Any]:
+ """A link, or with "inline" the clip itself when its WAV fits the cap; one that cannot fit is never fetched. Audio has no preview, so "preview" is a link."""
estimate = (clip.duration_s or 0) * (clip.sample_rate or 0) * _WAV_BYTES_PER_SAMPLE
- if clip.duration_s and clip.sample_rate and estimate <= INLINE_CAP:
+ fits = clip.duration_s and clip.sample_rate and estimate <= INLINE_CAP
+ if return_media == "inline" and fits:
response = await forward(caller, "GET", audio_gallery_path(clip.id))
if response.status_code == 200 and len(response.content) <= INLINE_CAP:
mime = response.headers.get("content-type", "audio/wav").split(";")[0]
return [audio_content(response.content, mime)]
- return [resource_link(clip.url, f"{clip.id}.wav", "audio/wav")]
+ return [resource_link(clip.download_url or clip.url, f"{clip.id}.wav", "audio/wav")]
async def _checked_options(
@@ -266,9 +273,19 @@ async def generate_audio(
speed: Optional[float] = None,
seed: Optional[int] = None,
max_tokens: Optional[int] = None,
+ return_media: Annotated[
+ ReturnMedia,
+ Field(
+ description = 'How each clip comes back besides its id and links: "link" (default) links only; '
+ '"inline" the WAV itself when it fits 1.5 MiB; "preview" is the same as "link" for audio.'
+ ),
+ ] = "link",
+ preview_px: Annotated[
+ Optional[int], Field(ge = 32, le = 1024, description = "Unused for audio, which has no preview.")
+ ] = None,
options: Optional[dict[str, Any]] = None,
) -> ToolResult:
- """Run an Audio page workflow with the audio model loaded in Unsloth Studio, or with ``model`` (an id from list_models(workflow=...)), which Unsloth Studio loads first when "Switch model by request" is on in Settings > API; a model that cannot run the workflow is refused before anything is unloaded, and the refusal names the pages it runs on. Clips are saved to Audio history and returned inline when small, else as links. clone: speak ``text`` in the voice of ``reference`` (a clip, or a saved voice as voice_id; ``reference_text`` is its transcript). speak: ``text`` in the loaded model's default voice, or a saved voice via ``reference``. edit: change the words or delivery of ``source`` per ``edit``. convert: make ``source`` sound like ``target``. music: ``mode`` song or sfx from ``text`` (the style) and ``lyrics``; ``variations`` up to 4 share a group_id. separate: split ``source`` into stems. ``options`` are the loaded model's ``audio_options`` that studio_status lists, such as a built-in ``voice``. Audio inputs are an Unsloth Studio id, inline base64 with a filename, or a path on the Unsloth Studio computer. Failures start with a [code] tag, such as [runtime_stopped] (retry once, then reload) or [out_of_memory] (CPU or a smaller variant)."""
+ """Run an Audio page workflow with the audio model loaded in Unsloth Studio, or with ``model`` (an id from list_models(workflow=...)), which Unsloth Studio loads first when "Switch model by request" is on in Settings > API; a model that cannot run the workflow is refused before anything is unloaded, and the refusal names the pages it runs on. Clips are saved to Audio history and returned as links, or inline with return_media="inline" when the WAV fits 1.5 MiB. clone: speak ``text`` in the voice of ``reference`` (a clip, or a saved voice as voice_id; ``reference_text`` is its transcript). speak: ``text`` in the loaded model's default voice, or a saved voice via ``reference``. edit: change the words or delivery of ``source`` per ``edit``. convert: make ``source`` sound like ``target``. music: ``mode`` song or sfx from ``text`` (the style) and ``lyrics``; ``variations`` up to 4 share a group_id. separate: split ``source`` into stems. ``options`` are the loaded model's ``audio_options`` that studio_status lists, such as a built-in ``voice``. Audio inputs are an Unsloth Studio id, inline base64 with a filename, or a path on the Unsloth Studio computer. Failures start with a [code] tag, such as [runtime_stopped] (retry once, then reload) or [out_of_memory] (CPU or a smaller variant)."""
caller = current_caller()
inputs: dict[str, Any] = {}
for key, audio in (
@@ -313,9 +330,14 @@ async def generate_audio(
for row in payload.get("clips") or []:
if not isinstance(row, dict) or not opt_text(row.get("id")):
continue
- clip = AudioClip.from_route(row, url = public_url(caller, audio_gallery_path(row["id"])))
+ # workflow, voice_id, source_clip_id and seed are copied when the route sends them.
+ clip = AudioClip.from_route(
+ row,
+ url = public_url(caller, audio_gallery_path(row["id"])),
+ download_url = await signed_url(caller, "audio", row["id"]),
+ )
clips.append(clip)
- contents.extend(await _clip_contents(caller, clip))
+ contents.extend(await _clip_contents(caller, clip, return_media))
saved = True
fallback = payload.get("audio")
if isinstance(fallback, dict) and isinstance(fallback.get("data"), str):
@@ -494,8 +516,10 @@ async def _transcribe_source(
raise_for_route(response, payload = payload)
if not isinstance(payload, dict) or payload.get("type") != "complete":
raise ToolError("The transcription did not finish")
+ record = payload.get("record") if isinstance(payload.get("record"), dict) else {}
return TranscriptResult(
text = payload.get("text") if isinstance(payload.get("text"), str) else "",
+ transcript_id = opt_text(record.get("id")),
language = opt_text(payload.get("language")),
model = model,
segments = _segments(payload) if timestamps else None,
diff --git a/studio/backend/studio_mcp/tools/images.py b/studio/backend/studio_mcp/tools/images.py
index cce83384839..df009c31b08 100644
--- a/studio/backend/studio_mcp/tools/images.py
+++ b/studio/backend/studio_mcp/tools/images.py
@@ -18,11 +18,13 @@ from studio_mcp.forward import forward
from studio_mcp.inputs import ImageInput, data_url, resolve_image, sniff_image
from studio_mcp.media import (
INLINE_CAP,
+ ReturnMedia,
image_content,
image_gallery_path,
media_result,
public_url,
resource_link,
+ signed_url,
)
from studio_mcp.outputs import ImageItem, ImageResult
from studio_mcp.tools import WRITES, integer, number, opt_text, present, route_json
@@ -50,23 +52,35 @@ async def _fetch(caller: Caller, path: str) -> Optional[bytes]:
return response.content if response.status_code == 200 else None
-async def _image_contents(caller: Caller, item: ImageItem) -> list[Any]:
- """The PNG inline when it must fit the cap, else a WebP thumbnail plus a link; a large original is never fetched."""
- if item.width and item.height and item.width * item.height * 3 <= INLINE_CAP:
+async def _image_contents(
+ caller: Caller,
+ item: ImageItem,
+ return_media: ReturnMedia = "inline",
+ preview_px: Optional[int] = None,
+) -> list[Any]:
+ """inline: the PNG when it must fit the cap, else a WebP thumbnail plus a link; preview: the thumbnail plus a link; link: the link alone. A large original is never fetched."""
+ link = resource_link(item.download_url or item.url, f"{item.id}.png", "image/png")
+ if return_media == "link":
+ return [link]
+ small = item.width and item.height and item.width * item.height * 3 <= INLINE_CAP
+ if return_media == "inline" and small:
data = await _fetch(caller, image_gallery_path(item.id))
if data is not None and len(data) <= INLINE_CAP:
return [image_content(data, "image/png")]
- thumb = await _fetch(caller, image_gallery_path(item.id, thumb = True))
+ thumb = await _fetch(caller, image_gallery_path(item.id, thumb = preview_px or True))
contents: list[Any] = []
if thumb is not None and len(thumb) <= INLINE_CAP:
- # Studio sends the original PNG when it cannot make the thumbnail.
contents.append(image_content(thumb, sniff_image(thumb) or "image/webp"))
- contents.append(resource_link(item.url, f"{item.id}.png", "image/png"))
+ contents.append(link)
return contents
async def run_generation(
- caller: Caller, ctx: Optional[Context], body: dict[str, Any]
+ caller: Caller,
+ ctx: Optional[Context],
+ body: dict[str, Any],
+ return_media: ReturnMedia = "inline",
+ preview_px: Optional[int] = None,
) -> ToolResult:
generate = route_json(
"POST",
@@ -83,9 +97,13 @@ async def run_generation(
for row in rows:
if not isinstance(row, dict) or not opt_text(row.get("id")):
continue
- item = ImageItem.from_route(row, url = public_url(caller, image_gallery_path(row["id"])))
+ item = ImageItem.from_route(
+ row,
+ url = public_url(caller, image_gallery_path(row["id"])),
+ download_url = await signed_url(caller, "image", row["id"]),
+ )
items.append(item)
- contents.extend(await _image_contents(caller, item))
+ contents.extend(await _image_contents(caller, item, return_media, preview_px))
return media_result(contents, ImageResult(images = items))
@@ -169,6 +187,17 @@ async def generate_image(
strength: Optional[float] = None,
upscale: Optional[float] = None,
allow_oversized: bool = False,
+ return_media: Annotated[
+ ReturnMedia,
+ Field(
+ description = 'How each image comes back besides its id and links: "inline" the image when small, '
+ 'else a preview; "preview" a small preview image only; "link" no image data at all.'
+ ),
+ ] = "inline",
+ preview_px: Annotated[
+ Optional[int],
+ Field(ge = 32, le = 1024, description = "Long side of a preview image in pixels; default 1024."),
+ ] = None,
ctx: Optional[Context] = None,
) -> ToolResult:
"""Generate or edit images with the image model loaded in Unsloth Studio (load_model(kind="image") first).
@@ -212,7 +241,7 @@ async def generate_image(
)
if allow_oversized:
body["allow_oversized"] = True
- return await run_generation(caller, ctx, body)
+ return await run_generation(caller, ctx, body, return_media, preview_px)
TOOLS = ((generate_image, WRITES, ImageResult.model_json_schema()),)
diff --git a/studio/backend/studio_mcp/tools/jobs.py b/studio/backend/studio_mcp/tools/jobs.py
index a9662c83455..6d17aafb67d 100644
--- a/studio/backend/studio_mcp/tools/jobs.py
+++ b/studio/backend/studio_mcp/tools/jobs.py
@@ -15,7 +15,17 @@ from pydantic import Field
from studio_mcp.caller import Caller, current_caller
from studio_mcp.errors import raise_for_route
from studio_mcp.forward import forward
-from studio_mcp.media import INLINE_CAP, image_content, media_result, public_url, resource_link
+from studio_mcp.media import (
+ INLINE_CAP,
+ THUMB_SIDE,
+ ReturnMedia,
+ image_content,
+ media_result,
+ public_url,
+ resource_link,
+ signed_url,
+ video_frame_path,
+)
from studio_mcp import export_jobs
from studio_mcp.outputs import (
ExportInfo,
@@ -34,22 +44,34 @@ def _video_path(video_id: str, suffix: str = "") -> str:
return f"/v1/videos/{quote(video_id, safe = '')}{suffix}"
-async def _video_job(caller: Caller, video_id: str) -> ToolResult:
+async def _video_job(
+ caller: Caller,
+ video_id: str,
+ return_media: ReturnMedia = "inline",
+ preview_px: Optional[int] = None,
+) -> ToolResult:
job = as_dict(await route_json("GET", _video_path(video_id), caller = caller))
error = as_dict(job.get("error"))
contents: list[Any] = []
video = None
if job.get("status") == "completed":
- # The thumbnail only: the MP4 can be hundreds of MB and is shared as a link.
+ # A picture at most: the MP4 can be hundreds of MB and is shared as a link.
video_url = public_url(caller, _video_path(video_id, "/content"))
- thumb = await forward(
- caller, "GET", _video_path(video_id, "/content"), params = {"variant": "thumbnail"}
- )
- inline = thumb.status_code == 200 and len(thumb.content) <= INLINE_CAP
+ download_url = await signed_url(caller, "video", video_id)
+ thumb, mime = None, "image/webp"
+ if return_media == "inline":
+ thumb = await forward(
+ caller, "GET", _video_path(video_id, "/content"), params = {"variant": "thumbnail"}
+ )
+ elif return_media == "preview":
+ params = {"at": "first", "max_px": preview_px or THUMB_SIDE}
+ thumb = await forward(caller, "GET", video_frame_path(video_id), params = params)
+ mime = "image/png"
+ inline = thumb is not None and thumb.status_code == 200 and len(thumb.content) <= INLINE_CAP
if inline:
- contents.append(image_content(thumb.content, "image/webp"))
- contents.append(resource_link(video_url, f"{video_id}.mp4", "video/mp4"))
- video = VideoInfo(url = video_url, thumbnail_inline = inline)
+ contents.append(image_content(thumb.content, mime))
+ contents.append(resource_link(download_url or video_url, f"{video_id}.mp4", "video/mp4"))
+ video = VideoInfo(url = video_url, download_url = download_url, thumbnail_inline = inline)
status = JobStatus(
kind = "video",
id = opt_text(job.get("id")) or video_id,
@@ -159,6 +181,17 @@ async def get_job(
id: Optional[str] = None,
rows: Annotated[Optional[int], Field(ge = 1, le = 500)] = None,
offset: Annotated[int, Field(ge = 0)] = 0,
+ return_media: Annotated[
+ ReturnMedia,
+ Field(
+ description = 'For a completed video: "inline" (default) its thumbnail; "preview" its first frame '
+ 'at preview_px; "link" no picture. The MP4 itself is always a link.'
+ ),
+ ] = "inline",
+ preview_px: Annotated[
+ Optional[int],
+ Field(ge = 32, le = 1024, description = "Long side of a video preview in pixels; default 1024."),
+ ] = None,
) -> ToolResult:
"""The state of a long-running job. kind "video": with ``id``, its status and progress, and once completed a thumbnail plus the video's URL; without ``id``, recent video jobs. kind "recipe": a data recipe job's status and progress (without ``id``, the current one), and with ``rows`` that many generated rows from ``offset``. Unsloth Studio runs one recipe at a time; a recipe job id is not tied to an account. kind "export": an export_model job by its id (without ``id``, this key's export jobs), with its output named relative to Unsloth Studio's exports folder."""
caller = current_caller()
@@ -168,7 +201,7 @@ async def get_job(
return await _export_job(caller, id)
if id is None:
return await _video_jobs(caller)
- return await _video_job(caller, id)
+ return await _video_job(caller, id, return_media, preview_px)
async def run_recipe(
diff --git a/studio/backend/studio_mcp/tools/library.py b/studio/backend/studio_mcp/tools/library.py
new file mode 100644
index 00000000000..2bbf6df9f84
--- /dev/null
+++ b/studio/backend/studio_mcp/tools/library.py
@@ -0,0 +1,261 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The Unsloth Studio library: ``list_media`` pages through the galleries and ``voices`` manages saved voices."""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import re
+from typing import Annotated, Any, Literal, Optional
+
+from fastmcp.exceptions import ToolError
+from pydantic import Field
+
+from studio_mcp.caller import Caller, current_caller
+from studio_mcp.inputs import AudioInput, audio_ref
+from studio_mcp.media import (
+ audio_gallery_path,
+ image_gallery_path,
+ public_url,
+ signed_url,
+ video_gallery_path,
+ voice_path,
+)
+from studio_mcp.outputs import (
+ AudioRow,
+ ImageRow,
+ MediaPage,
+ TranscriptRow,
+ VideoRow,
+ VoiceRow,
+ VoicesResult,
+)
+from studio_mcp.tools import DESTRUCTIVE, READ_ONLY, as_dict, number, opt_text, present, route_json
+
+MediaKind = Literal["image", "audio", "video", "transcript", "voice"]
+_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+_OFFSET = re.compile(r"^\d{1,9}$")
+_AUDIO_CURSOR = re.compile(r"^(-?[0-9.e+-]*)\|(-?[0-9.e+-]+)\|([A-Za-z0-9_-]{1,128})$")
+# The transcripts route's own cursor: the last row's created_at and id.
+_TRANSCRIPT_CURSOR = re.compile(r"^[0-9A-Za-z:.+_-]{1,40}\|[A-Za-z0-9_-]{1,59}$")
+
+
+def _rows(payload: Any, key: str) -> list[dict]:
+ rows = as_dict(payload).get(key)
+ return (
+ [r for r in rows if isinstance(r, dict) and opt_text(r.get("id"))]
+ if isinstance(rows, list)
+ else []
+ )
+
+
+def _finite(text: str) -> bool:
+ try:
+ return math.isfinite(float(text))
+ except ValueError:
+ return False
+
+
+def _cursor(kind: str, cursor: Optional[str]) -> Optional[str]:
+ """The kind-specific part of a cursor list_media returned, refused before any call when it belongs to another kind or is malformed."""
+ if cursor is None:
+ return None
+ prefix, _, rest = cursor.partition(":")
+ if prefix != kind:
+ raise ToolError(
+ f"This cursor is not from list_media(kind='{kind}'); pass the next_cursor that call returned."
+ )
+ if kind in ("image", "video", "voice"):
+ malformed = not _OFFSET.fullmatch(rest)
+ elif kind == "audio":
+ audio = _AUDIO_CURSOR.fullmatch(rest)
+ malformed = not audio or not all(_finite(n) for n in (audio[2], audio[1] or "0"))
+ else:
+ malformed = not _TRANSCRIPT_CURSOR.fullmatch(rest)
+ if malformed:
+ raise ToolError(
+ "The cursor is malformed; pass next_cursor exactly as list_media returned it."
+ )
+ return rest
+
+
+async def _with_links(caller: Caller, kind: str, rows: list[dict]) -> list[Optional[str]]:
+ return list(await asyncio.gather(*(signed_url(caller, kind, row["id"]) for row in rows)))
+
+
+async def _images(caller: Caller, limit: int, offset: int) -> tuple[list[Any], Optional[str]]:
+ params = {"limit": limit, "offset": offset}
+ payload = await route_json("GET", "/api/inference/images/gallery", caller = caller, params = params)
+ rows = _rows(payload, "images")
+ links = await _with_links(caller, "image", rows)
+ items = [
+ ImageRow.from_route(
+ row, url = public_url(caller, image_gallery_path(row["id"])), download_url = link
+ )
+ for row, link in zip(rows, links)
+ ]
+ more = as_dict(payload).get("has_more") is True
+ return items, f"image:{offset + len(rows)}" if more and rows else None
+
+
+async def _videos(caller: Caller, limit: int, offset: int) -> tuple[list[Any], Optional[str]]:
+ params = {"limit": limit, "offset": offset}
+ payload = await route_json("GET", "/api/inference/video/gallery", caller = caller, params = params)
+ rows = _rows(payload, "videos")
+ links = await _with_links(caller, "video", rows)
+ items = [
+ VideoRow.from_route(
+ row, url = public_url(caller, video_gallery_path(row["id"])), download_url = link
+ )
+ for row, link in zip(rows, links)
+ ]
+ more = as_dict(payload).get("has_more") is True
+ return items, f"video:{offset + len(rows)}" if more and rows else None
+
+
+async def _audio(
+ caller: Caller, limit: int, cursor: Optional[str]
+) -> tuple[list[Any], Optional[str]]:
+ params: dict[str, Any] = {"limit": limit}
+ if cursor is not None:
+ pin, mtime, clip_id = cursor.split("|")
+ params.update(present(before_pin = pin or None, before_mtime = mtime, before_id = clip_id))
+ payload = as_dict(
+ await route_json("GET", "/api/inference/audio/gallery", caller = caller, params = params)
+ )
+ rows = _rows(payload, "audio")
+ links = await _with_links(caller, "audio", rows)
+ items = [
+ AudioRow.from_route(
+ row, url = public_url(caller, audio_gallery_path(row["id"])), download_url = link
+ )
+ for row, link in zip(rows, links)
+ ]
+ mtime, last = number(payload.get("next_before_mtime")), opt_text(payload.get("next_before_id"))
+ pin = number(payload.get("next_before_pin"))
+ more = (
+ payload.get("has_more") is True
+ and mtime is not None
+ and last is not None
+ and _ID.match(last)
+ )
+ return items, f"audio:{'' if pin is None else repr(pin)}|{mtime!r}|{last}" if more else None
+
+
+async def _transcripts(
+ caller: Caller, limit: int, cursor: Optional[str]
+) -> tuple[list[Any], Optional[str]]:
+ params = present(limit = limit, before = cursor)
+ payload = as_dict(
+ await route_json("GET", "/api/inference/audio/transcripts", caller = caller, params = params)
+ )
+ items = [TranscriptRow.from_route(row) for row in _rows(payload, "transcripts")]
+ after = opt_text(payload.get("next_cursor"))
+ return items, f"transcript:{after}" if after and _TRANSCRIPT_CURSOR.match(after) else None
+
+
+def _voice(caller: Caller, row: Any) -> Optional[VoiceRow]:
+ row = as_dict(row)
+ if not opt_text(row.get("id")) or not opt_text(row.get("name")):
+ return None
+ return VoiceRow.from_route(row, url = public_url(caller, voice_path(row["id"], "/file")))
+
+
+async def _voice_list(caller: Caller) -> list[VoiceRow]:
+ payload = await route_json("GET", voice_path(), caller = caller)
+ rows = as_dict(payload).get("voices")
+ voices = [_voice(caller, row) for row in rows] if isinstance(rows, list) else []
+ return [voice for voice in voices if voice is not None]
+
+
+async def list_media(
+ kind: Annotated[MediaKind, Field(description = "Which Unsloth Studio library to list.")],
+ limit: Annotated[int, Field(ge = 1, le = 50, description = "Items per page.")] = 20,
+ cursor: Annotated[
+ Optional[str], Field(description = "next_cursor from the previous page of the same kind.")
+ ] = None,
+) -> MediaPage:
+ """List earlier work saved in Unsloth Studio, newest first: images, audio clips, videos, transcripts or saved voices. Each row has its id, which other tools take as gallery_id, clip_id, video_id or voice_id, and for images, audio and videos a download_url that works without the API key for about an hour. Pass next_cursor back as cursor for the next page; image and video pages count rows, so deleting items between calls can shift them by a row."""
+ caller = current_caller()
+ rest = _cursor(kind, cursor)
+ if kind == "image":
+ items, after = await _images(caller, limit, int(rest or 0))
+ return MediaPage(kind = kind, images = items, next_cursor = after)
+ if kind == "video":
+ items, after = await _videos(caller, limit, int(rest or 0))
+ return MediaPage(kind = kind, videos = items, next_cursor = after)
+ if kind == "audio":
+ items, after = await _audio(caller, limit, rest)
+ return MediaPage(kind = kind, audio = items, next_cursor = after)
+ if kind == "transcript":
+ items, after = await _transcripts(caller, limit, rest)
+ return MediaPage(kind = kind, transcripts = items, next_cursor = after)
+ voices, offset = await _voice_list(caller), int(rest or 0)
+ after = f"voice:{offset + limit}" if offset + limit < len(voices) else None
+ return MediaPage(kind = kind, voices = voices[offset : offset + limit], next_cursor = after)
+
+
+VOICE_NOT_FOUND = {404: "list_media(kind='voice') lists the saved voices."}
+
+
+async def voices(
+ action: Annotated[
+ Literal["list", "save", "rename", "delete"],
+ Field(
+ description = "list saved voices, save a new one from source, rename (or edit) one, or delete one."
+ ),
+ ],
+ voice_id: Annotated[Optional[str], Field(description = "The voice to rename or delete.")] = None,
+ source: Annotated[
+ Optional[AudioInput],
+ Field(
+ description = "For save: the reference audio, a few seconds of clean speech; not a voice_id."
+ ),
+ ] = None,
+ name: Annotated[
+ Optional[str], Field(min_length = 1, max_length = 80, description = "The voice's name.")
+ ] = None,
+ transcript: Annotated[
+ Optional[str], Field(max_length = 4000, description = "What the reference audio says.")
+ ] = None,
+ language: Annotated[
+ Optional[str], Field(max_length = 64, description = "The reference's language.")
+ ] = None,
+) -> VoicesResult:
+ """Manage the voices saved in Unsloth Studio, which generate_audio takes as reference={"voice_id": ...}. save stores source under name (with its transcript and language when known); rename changes a voice's name, transcript or language; delete removes it for good."""
+ caller = current_caller()
+ if action == "list":
+ return VoicesResult(action = action, voices = await _voice_list(caller))
+ if action == "save":
+ if source is None or name is None:
+ raise ToolError("save needs source and name.")
+ if source.voice_id is not None:
+ raise ToolError(
+ "A voice is saved from audio or an Audio history clip, not from another saved voice."
+ )
+ body = {"source": await audio_ref(caller, source), "name": name}
+ body.update(present(transcript = transcript, language = language))
+ saved = await route_json("POST", voice_path(), caller = caller, json_body = body)
+ return VoicesResult(action = action, voice = _voice(caller, saved))
+ if voice_id is None or not _ID.match(voice_id):
+ raise ToolError(
+ f"{action} needs voice_id, an Unsloth Studio voice id from list_media(kind='voice')."
+ )
+ if action == "rename":
+ changes = present(name = name, transcript = transcript, language = language)
+ if not changes:
+ raise ToolError("rename needs name, transcript or language.")
+ edited = await route_json(
+ "PATCH", voice_path(voice_id), caller = caller, json_body = changes, hints = VOICE_NOT_FOUND
+ )
+ return VoicesResult(action = action, voice = _voice(caller, edited))
+ await route_json("DELETE", voice_path(voice_id), caller = caller, hints = VOICE_NOT_FOUND)
+ return VoicesResult(action = action, removed = True)
+
+
+TOOLS = (
+ (list_media, READ_ONLY, MediaPage.model_json_schema()),
+ (voices, DESTRUCTIVE, VoicesResult.model_json_schema()),
+)
diff --git a/studio/backend/tests/multi_account/factories_media.py b/studio/backend/tests/multi_account/factories_media.py
index 8745b0da741..82f93636998 100644
--- a/studio/backend/tests/multi_account/factories_media.py
+++ b/studio/backend/tests/multi_account/factories_media.py
@@ -14,6 +14,7 @@ MODEL_ID = "media-local-model-Q4_K_M"
IMAGE_LINK_QUERY: dict[str, str] = {}
VIDEO_LINK_QUERY: dict[str, str] = {}
+AUDIO_LINK_QUERY: dict[str, str] = {}
def _image_meta() -> dict:
@@ -96,6 +97,7 @@ def _wav_bytes() -> bytes:
@seeder("media-audio")
def seed_audio(account) -> dict[str, str]:
from core.inference import audio_gallery
+ from routes.inference import _sign_audio_id
from utils.account_context import run_as
meta = {
@@ -107,6 +109,7 @@ def seed_audio(account) -> dict[str, str]:
"created_at": "2026-01-01T00:00:00+00:00",
}
record = run_as(account, audio_gallery.save, _wav_bytes(), meta)
+ AUDIO_LINK_QUERY["token"] = run_as(account, _sign_audio_id, record["id"])
return {"audio_id": record["id"]}
@@ -363,6 +366,9 @@ FACTORIES = {
unauthenticated = (200,),
reason = _LINK_IS_THE_CREDENTIAL,
),
+ "routes.inference:GET:/images/gallery/{image_id}/signed-url": Factory(
+ "media-image", fragment = "file-signed"
+ ),
"routes.inference:PATCH:/images/gallery/{image_id}": Factory(
"media-image", {"archived": True}, fragment = SENTINEL
),
@@ -375,6 +381,17 @@ FACTORIES = {
"media-image-project", {"project_id": MEDIA_PROJECT_ID}, fragment = "sandbox"
),
"routes.inference:GET:/audio/gallery/{audio_id}/file": Factory("media-audio"),
+ "routes.inference:GET:/audio/gallery/{audio_id}/signed-url": Factory(
+ "media-audio", fragment = "file-signed"
+ ),
+ "routes.inference:GET:/audio/gallery/{audio_id}/file-signed": Factory(
+ "media-audio",
+ query = AUDIO_LINK_QUERY,
+ owner = (200,),
+ wrong = (200,),
+ unauthenticated = (200,),
+ reason = _LINK_IS_THE_CREDENTIAL,
+ ),
"routes.inference:GET:/audio/gallery/{audio_id}/source/file": Factory("media-audio-converted"),
"routes.inference:PATCH:/audio/gallery/{audio_id}": Factory(
"media-audio", {"archived": True}, fragment = SENTINEL
@@ -423,6 +440,15 @@ FACTORIES = {
"media-video", fragment = "file-signed"
),
"routes.video:GET:/video/gallery/{video_id}/export": Factory("media-video"),
+ "routes.video:GET:/video/gallery/{video_id}/frame": Factory("media-video"),
+ "routes.video:POST:/video/gallery/{video_id}/audio-input": Factory(
+ "media-video",
+ {},
+ right = (400,),
+ self_expected = (400,),
+ fragment = "no audio track",
+ reason = "the seeded clip is silent, so past the ownership check the extract refuses",
+ ),
"routes.video:PATCH:/video/gallery/{video_id}": Factory(
"media-video", {"archived": True}, fragment = SENTINEL
),
diff --git a/studio/backend/tests/test_account_media_isolation.py b/studio/backend/tests/test_account_media_isolation.py
index 3934b81a174..f9a37df6959 100644
--- a/studio/backend/tests/test_account_media_isolation.py
+++ b/studio/backend/tests/test_account_media_isolation.py
@@ -97,8 +97,8 @@ def test_gallery_object_routes_do_not_resolve_another_accounts_ids(kind, account
assert client.patch(f"{root}/{record['id']}", json = {"starred": True}).status_code == 404
assert client.delete(f"{root}/{record['id']}").status_code == 404
assert record["id"] not in client.get(root).text
+ assert client.get(f"{root}/{record['id']}/signed-url").status_code == 404
if kind == "video":
- assert client.get(f"{root}/{record['id']}/signed-url").status_code == 404
assert client.get(f"{root}/{record['id']}/export").status_code == 404
with _client(account) as client:
assert client.get(f"{root}/{record['id']}/file").status_code == 200
@@ -124,10 +124,17 @@ def test_clear_and_paths_are_account_scoped(kind, module, tmp_path):
assert run_as(BOB, module.gallery_dir) == tmp_path / "accounts" / BOB.account_id / folder
[email protected]("kind,module", [("images", inference), ("video", video)])
-def test_signed_links_authorize_only_the_original_account_and_media(kind, module):
+ "kind,module,sign,verify",
+ [
+ ("images", inference, "_sign_image_id", "_verify_image_link_token"),
+ ("audio", inference, "_sign_audio_id", "_verify_audio_link_token"),
+ ("video", video, "_sign_video_id", "_verify_video_link_token"),
+ ],
+)
+def test_signed_links_authorize_only_the_original_account_and_media(kind, module, sign, verify):
record = run_as(ALICE, _save, kind)
- sign = module._sign_image_id if kind == "images" else module._sign_video_id
+ sign, verify = getattr(module, sign), getattr(module, verify)
token = run_as(ALICE, sign, record["id"])
root = f"/api/inference/{kind}/gallery"
with _client(BOB) as client:
@@ -141,9 +148,6 @@ def test_signed_links_authorize_only_the_original_account_and_media(kind, module
client.get(f"{root}/{record['id']}/file-signed", params = {"token": tampered}).status_code
== 401
)
- verify = (
- module._verify_image_link_token if kind == "images" else module._verify_video_link_token
- )
owner_token = run_as(OWNER, sign, record["id"])
assert owner_token.split(".")[0] == record["id"]
assert verify(owner_token) == record["id"]
diff --git a/studio/backend/tests/test_keyless_api_access.py b/studio/backend/tests/test_keyless_api_access.py
index 385ca7ff748..3de3f04856e 100644
--- a/studio/backend/tests/test_keyless_api_access.py
+++ b/studio/backend/tests/test_keyless_api_access.py
@@ -1100,7 +1100,12 @@ def test_protected_side_effect_guards_remain_wired():
)
assert all(
"request_admitted_without_credential" in inspect.getsource(handler)
- for handler in (video.get_gallery_video_signed_url, rag.document_file_url)
+ for handler in (
+ video.get_gallery_video_signed_url,
+ rag.document_file_url,
+ inference.get_gallery_image_signed_url,
+ inference.get_gallery_audio_signed_url,
+ )
)
assert "request_admitted_without_credential" in inspect.getsource(
inference.openai_image_generations
diff --git a/studio/backend/tests/test_mcp_media_links_e2e.py b/studio/backend/tests/test_mcp_media_links_e2e.py
new file mode 100644
index 00000000000..07899ceac08
--- /dev/null
+++ b/studio/backend/tests/test_mcp_media_links_e2e.py
@@ -0,0 +1,156 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""The MCP tools against the real Unsloth Studio gallery routes: links an agent can fetch with
+nothing else, a library that only shows the caller's own work, and a gallery video reused as the
+next shot's first frame and as a saved voice."""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+from urllib.parse import urlsplit
+
+import pytest
+from fastapi import FastAPI, Request
+from PIL import Image
+
+from auth.authentication import authenticated_via_api_key, get_current_subject
+from core.inference import image_gallery, video_gallery
+from routes import inference, video
+from utils.account_context import bind_account, reset_account, run_as
+
+from .mcp_harness import run_tool
+from .test_account_media_isolation import ALICE, BOB, isolated # noqa: F401
+from .test_media_signed_links import _app
+from .test_video_gallery import _real_mp4_bytes, _real_mp4_with_audio
+
+pytest.importorskip("av")
+
+
+def _studio(account) -> FastAPI:
+ """The real gallery, audio and video routes as ``account``, plus stand-ins for the GPU work."""
+ app = FastAPI()
+ app.state.video_bodies = []
+
+ async def subject():
+ token = bind_account(account)
+ try:
+ yield account.username
+ finally:
+ reset_account(token)
+
+ @app.post("/api/inference/images/generate")
+ async def generate(request: Request):
+ meta = {"prompt": "hero", "width": 8, "height": 8, "steps": 1, "guidance": 1.0}
+ meta.update(seed = 3, created_at = 100.0)
+ row = run_as(account, image_gallery.save, Image.new("RGB", (8, 8), (200, 10, 10)), meta)
+ return {"images": [{"id": row["id"], "width": 8, "height": 8, "seed": 3}]}
+
+ @app.post("/v1/videos")
+ async def create_video(request: Request):
+ app.state.video_bodies.append(json.loads(await request.body()))
+ return {"id": "video_next", "status": "queued"}
+
+ app.dependency_overrides[get_current_subject] = subject
+ app.dependency_overrides[authenticated_via_api_key] = lambda: False
+ for prefix in ("/api/inference", "/v1"):
+ app.include_router(inference.router, prefix = prefix)
+ app.include_router(inference.studio_router, prefix = "/api/inference")
+ app.include_router(video.router, prefix = "/api/inference")
+ return app
+
+
+def _clip(
+ account,
+ data: bytes,
+ prompt: str = "clip A",
+) -> str:
+ meta = {
+ "prompt": prompt,
+ "width": 64,
+ "height": 48,
+ "num_frames": 8,
+ "fps": 8,
+ "duration_s": 1.0,
+ "steps": 1,
+ "guidance": 1.0,
+ "seed": 7,
+ "model": "test/none",
+ "created_at": "2026-01-01T00:00:00+00:00",
+ }
+ return run_as(account, video_gallery.save, data, meta)["id"]
+
+
+def _fetch_bare(url: str):
+ """GET a link the way a stock client would: no Authorization, no cookies, no overrides."""
+ parts = urlsplit(url)
+ with _app() as bare:
+ return bare.get(f"{parts.path}?{parts.query}")
+
+
+def test_generated_and_listed_media_download_without_the_key(monkeypatch):
+ studio = _studio(ALICE)
+ made, _ = run_tool(
+ monkeypatch, studio, "generate_image", {"prompt": "hero", "return_media": "link"}
+ )
+ image = made["structuredContent"]["images"][0]
+ assert [c["type"] for c in made["content"]] == ["text", "resource_link"]
+ assert made["content"][1]["uri"] == image["download_url"]
+ fetched = _fetch_bare(image["download_url"])
+ assert fetched.status_code == 200, fetched.text
+ assert Image.open(io.BytesIO(fetched.content)).getpixel((0, 0)) == (200, 10, 10)
+ assert _fetch_bare(image["url"]).status_code in (401, 403)
+
+ listed, _ = run_tool(monkeypatch, studio, "list_media", {"kind": "image"})
+ rows = listed["structuredContent"]["images"]
+ assert [row["id"] for row in rows] == [image["id"]]
+ assert _fetch_bare(rows[0]["download_url"]).content == fetched.content
+ assert "/tmp" not in json.dumps(listed) and str(image_gallery.gallery_dir()) not in json.dumps(
+ listed
+ )
+ other, _ = run_tool(monkeypatch, _studio(BOB), "list_media", {"kind": "image"})
+ assert other["structuredContent"]["images"] == []
+
+
+def test_the_last_frame_of_one_clip_starts_the_next(monkeypatch):
+ # Frame i is grey (i * 30): the last of 8 frames is 210.
+ clip_a = _clip(ALICE, _real_mp4_bytes(frames = 8, size = (64, 48), rate = 8))
+ studio = _studio(ALICE)
+ result, _ = run_tool(
+ monkeypatch,
+ studio,
+ "generate_video",
+ {"prompt": "shot B", "first_frame": {"video_id": clip_a, "frame": "last"}},
+ )
+ assert not result.get("isError"), result
+ sent = studio.state.video_bodies[0]["input_reference"]
+ assert sent.startswith("data:image/png;base64,")
+ frame = Image.open(io.BytesIO(base64.b64decode(sent.split(",", 1)[1]))).convert("L")
+ assert abs(frame.getpixel((32, 24)) - 210) <= 12
+ refused, bob = run_tool(
+ monkeypatch,
+ _studio(BOB),
+ "generate_video",
+ {"prompt": "shot B", "first_frame": {"video_id": clip_a}},
+ )
+ assert refused.get("isError") and bob.state.video_bodies == []
+
+
+def test_a_clips_sound_becomes_a_saved_voice(monkeypatch):
+ clip = _clip(ALICE, _real_mp4_with_audio(seconds = 1), prompt = "narrator take")
+ studio = _studio(ALICE)
+ saved, _ = run_tool(
+ monkeypatch,
+ studio,
+ "voices",
+ {"action": "save", "name": "Narrator", "source": {"video_id": clip, "end_s": 0.8}},
+ )
+ assert not saved.get("isError"), saved
+ voice = saved["structuredContent"]["voice"]
+ assert voice["name"] == "Narrator" and 0.7 <= voice["duration_s"] <= 0.9
+ listed, _ = run_tool(monkeypatch, studio, "list_media", {"kind": "voice"})
+ assert [row["id"] for row in listed["structuredContent"]["voices"]] == [voice["id"]]
+ other, _ = run_tool(monkeypatch, _studio(BOB), "list_media", {"kind": "voice"})
+ assert other["structuredContent"]["voices"] == []
diff --git a/studio/backend/tests/test_mcp_no_host_paths.py b/studio/backend/tests/test_mcp_no_host_paths.py
index 4f1f19adf8a..d9b1c7dd54f 100644
--- a/studio/backend/tests/test_mcp_no_host_paths.py
+++ b/studio/backend/tests/test_mcp_no_host_paths.py
@@ -36,6 +36,8 @@ from .test_mcp_tools_audio import TRANSCRIPT, VERBOSE
from .test_mcp_tools_cancel import PAYLOADS as CANCEL_PAYLOADS
from .test_mcp_tools_datasets import PAYLOADS as DATASETS_PAYLOADS
from .test_mcp_tools_images import PAYLOADS as IMAGES_PAYLOADS
+from .test_mcp_tools_library import PAYLOADS as LIBRARY_PAYLOADS
+from .test_mcp_tools_library import VOICE_PAYLOADS
from .test_mcp_tools_loading import PAYLOADS as LOADING_PAYLOADS
from .test_mcp_tools_models import PAYLOADS as MODELS_PAYLOADS
from .test_mcp_tools_recipe import PAYLOADS as RECIPE_PAYLOADS
@@ -107,6 +109,15 @@ CASES: dict[str, Any] = {
"analyze_audio": (ANALYZE_PAYLOADS, {"audio": WAV_INPUT, "expected_text": "hello"}),
"transcribe": (TRANSCRIBE_PAYLOADS, {"audio": WAV_INPUT, "timestamps": True, "language": "en"}),
"generate_audio": (AUDIO_PAYLOADS, {"workflow": "clone", "text": "hi", "reference": WAV_INPUT}),
+ "list_media": [
+ (LIBRARY_PAYLOADS, {"kind": kind})
+ for kind in ("image", "audio", "video", "transcript", "voice")
+ ],
+ "voices": [
+ (VOICE_PAYLOADS, {"action": "list"}),
+ (VOICE_PAYLOADS, {"action": "save", "source": {"clip_id": "clip-1"}, "name": "n"}),
+ (VOICE_PAYLOADS, {"action": "rename", "voice_id": "voice-1", "name": "Host"}),
+ ],
}
# Output keys that carry model-written text, which is the model's to say and is never rewritten.
@@ -114,6 +125,7 @@ MODEL_TEXT = {
"chat": {"text"},
"transcribe": {"text"},
"get_job": {"data_rows"},
+ "list_media": {"text"},
"analyze_audio": {"transcript"},
}
diff --git a/studio/backend/tests/test_mcp_return_media.py b/studio/backend/tests/test_mcp_return_media.py
new file mode 100644
index 00000000000..820ee2d064b
--- /dev/null
+++ b/studio/backend/tests/test_mcp_return_media.py
@@ -0,0 +1,233 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""return_media on generate_image, generate_audio and get_job; key-free download links; transcript ids, clip lineage and gallery videos as inputs."""
+
+import asyncio
+import json
+
+import pytest
+from fastapi.responses import JSONResponse, Response
+
+from studio_mcp import media
+
+from .mcp_harness import PNG, WAV, WEBP, bodies, fake_studio, make_caller, queries, run_tool
+from .test_mcp_tools_audio import COMPLETE, _from_source
+
+IMAGES = "/api/inference/images/gallery"
+VIDEOS = "/api/inference/video/gallery"
+CLIPS = "/v1/audio/gallery"
+BASE = "http://testserver"
+
+
+def _minted(base, media_id):
+ return {
+ ("GET", f"{base}/{media_id}/signed-url"): {
+ "url": f"{base}/{media_id}/file-signed?token=t.1"
+ }
+ }
+
+
+def _files(studio, needle = ""):
+ return [c[1] for c in studio.state.calls if needle in c[1] and not c[1].endswith("/signed-url")]
+
+
+IMAGE_ROUTES = {
+ ("POST", "/api/inference/images/generate"): {
+ "images": [{"id": "img-1", "width": 512, "height": 512}]
+ },
+ ("GET", f"{IMAGES}/img-1/file"): lambda request, body: Response(
+ WEBP if request.query_params.get("thumb") else PNG
+ ),
+ **_minted(IMAGES, "img-1"),
+}
+
+
+# (return_media, preview_px, the content types after the JSON, the file queries made).
+ "mode,px,types,fetched",
+ [
+ ("inline", None, ["image"], [{}]),
+ ("preview", 256, ["image", "resource_link"], [{"thumb": "256"}]),
+ ("preview", None, ["image", "resource_link"], [{"thumb": "1024"}]),
+ ("link", 256, ["resource_link"], []),
+ ],
+)
+def test_image_return_media_modes(monkeypatch, mode, px, types, fetched):
+ args = {"prompt": "x", "return_media": mode, **({"preview_px": px} if px else {})}
+ result, studio = run_tool(monkeypatch, IMAGE_ROUTES, "generate_image", args)
+ content = result["content"]
+ assert [c["type"] for c in content[1:]] == types
+ assert queries(studio, f"{IMAGES}/img-1/file") == fetched
+ download = f"{BASE}{IMAGES}/img-1/file-signed?token=t.1"
+ assert result["structuredContent"]["images"][0]["download_url"] == download
+ assert all(c["uri"] == download for c in content if c["type"] == "resource_link")
+
+
[email protected]("px", [31, 1025])
+def test_preview_px_out_of_range_is_refused_without_a_call(monkeypatch, px):
+ for tool, args in (
+ ("generate_image", {"prompt": "x"}),
+ ("get_job", {"kind": "video", "id": "v"}),
+ ):
+ result, studio = run_tool(monkeypatch, {}, tool, {**args, "preview_px": px}, fallback = {})
+ assert result["isError"] is True and studio.state.calls == []
+
+
+SECOND = 48_000
+AUDIO_ROUTES = {
+ ("POST", "/v1/audio/run"): {
+ "clips": [
+ {
+ "id": "clip-1",
+ "duration_s": 1.0,
+ "sample_rate": 24000,
+ "workflow": "speak",
+ "seed": 5,
+ }
+ ],
+ "model": "m",
+ },
+ ("GET", f"{CLIPS}/clip-1/file"): lambda request, body: Response(
+ WAV + b"\x00" * SECOND, media_type = "audio/wav"
+ ),
+ **_minted(CLIPS, "clip-1"),
+}
+
+
[email protected]("mode", [None, "preview", "link", "inline"])
+def test_audio_is_a_link_unless_asked_inline(monkeypatch, mode):
+ args = {"workflow": "speak", "text": "Hi", **({"return_media": mode} if mode else {})}
+ result, studio = run_tool(monkeypatch, AUDIO_ROUTES, "generate_audio", args)
+ size = len(json.dumps(result))
+ clip = result["structuredContent"]["clips"][0]
+ assert clip["download_url"] == f"{BASE}{CLIPS}/clip-1/file-signed?token=t.1"
+ assert (clip["workflow"], clip["seed"], clip["voice_id"]) == ("speak", 5, None)
+ if mode == "inline":
+ assert [c["type"] for c in result["content"][1:]] == ["audio"] and size > SECOND
+ else:
+ assert [c["type"] for c in result["content"][1:]] == ["resource_link"]
+ assert result["content"][1]["uri"] == clip["download_url"]
+ assert _files(studio, "/gallery/") == [] and size < 2048
+
+
+VIDEO_ROUTES = {
+ ("GET", "/v1/videos/video-1"): {"id": "video-1", "status": "completed", "progress": 100},
+ ("GET", "/v1/videos/video-1/content"): Response(WEBP, media_type = "image/webp"),
+ ("GET", f"{VIDEOS}/video-1/frame"): Response(PNG, media_type = "image/png"),
+ **_minted(VIDEOS, "video-1"),
+}
+
+
+ "mode,px,mime,fetched",
+ [
+ ("inline", None, "image/webp", ["/v1/videos/video-1/content"]),
+ ("preview", 320, "image/png", [f"{VIDEOS}/video-1/frame"]),
+ ("link", None, None, []),
+ ],
+)
+def test_video_return_media_modes(monkeypatch, mode, px, mime, fetched):
+ args = {
+ "kind": "video",
+ "id": "video-1",
+ "return_media": mode,
+ **({"preview_px": px} if px else {}),
+ }
+ result, studio = run_tool(monkeypatch, VIDEO_ROUTES, "get_job", args)
+ images = [c for c in result["content"] if c["type"] == "image"]
+ assert [c["mimeType"] for c in images] == ([mime] if mime else [])
+ assert _files(studio, "/video") == ["/v1/videos/video-1", *fetched]
+ if px:
+ assert queries(studio, f"{VIDEOS}/video-1/frame") == [{"at": "first", "max_px": "320"}]
+ video = result["structuredContent"]["video"]
+ assert video["download_url"] == f"{BASE}{VIDEOS}/video-1/file-signed?token=t.1"
+ assert video["thumbnail_inline"] is bool(mime)
+
+
+def _mint(answer, kind = "image"):
+ studio = fake_studio({("GET", f"{media.SIGNED_BASES[kind]}/a/signed-url"): answer})
+ return asyncio.run(media.signed_url(make_caller(studio_app = studio), kind, "a")), studio
+
+
+def test_signed_url_keeps_only_the_token_and_rebuilds_the_path():
+ url, _studio = _mint({"url": "/elsewhere/x/file-signed?token=acct:a.1760000000.f00d"})
+ assert (
+ url
+ == "http://127.0.0.1:8888/api/inference/images/gallery/a/file-signed?token=acct:a.1760000000.f00d"
+ )
+ url, studio = _mint({"url": f"{VIDEOS}/a/file-signed?token=t.1"}, "video")
+ assert url.endswith(f"{VIDEOS}/a/file-signed?token=t.1")
+ assert queries(studio, f"{VIDEOS}/a/signed-url") == [{"ttl_s": str(media.MCP_LINK_TTL_S)}]
+
+
+ "answer",
+ [
+ JSONResponse(
+ {"detail": "Image links can only be created from the Unsloth UI or with an API key."},
+ 403,
+ ),
+ {"url": "/x/file-signed?token=a/../b"},
+ {"url": "/x/file-signed"},
+ {"url": 5},
+ Response(b"not json"),
+ ],
+)
+def test_a_mint_that_fails_or_looks_wrong_gives_no_link(answer):
+ assert _mint(answer)[0] is None
+
+
+def test_a_saved_transcript_returns_its_id(monkeypatch):
+ result, _studio = _from_source(monkeypatch, {"audio": {"clip_id": "clip-7"}})
+ assert result["structuredContent"]["transcript_id"] == "tr-1"
+ unsaved = {**COMPLETE, "record": None}
+ result, _studio = _from_source(monkeypatch, {"audio": {"clip_id": "clip-7"}}, [unsaved])
+ assert result["structuredContent"]["transcript_id"] is None
+
+
[email protected]("frame,at", [(None, "first"), ("last", "last"), (2.5, "2.5")])
+def test_a_video_frame_is_an_image_input(monkeypatch, frame, at):
+ source = {"video_id": "video-1", **({"frame": frame} if frame is not None else {})}
+ args = {"prompt": "next shot", "init_image": source, "return_media": "link"}
+ result, studio = run_tool(monkeypatch, {**IMAGE_ROUTES, **VIDEO_ROUTES}, "generate_image", args)
+ assert result["isError"] is False, result
+ assert queries(studio, f"{VIDEOS}/video-1/frame") == [{"at": at}]
+ (body,) = bodies(studio, "/api/inference/images/generate")
+ assert body["init_image"].startswith("data:image/png;base64,")
+
+
+def test_a_video_sound_is_an_audio_input(monkeypatch):
+ routes = {**AUDIO_ROUTES, ("POST", f"{VIDEOS}/video-1/audio-input"): {"id": "in-5"}}
+ source = {"video_id": "video-1", "start_s": 1, "end_s": 3.5}
+ args = {"workflow": "clone", "text": "Hi", "reference": source}
+ result, studio = run_tool(monkeypatch, routes, "generate_audio", args)
+ assert result["isError"] is False, result
+ assert bodies(studio, f"{VIDEOS}/video-1/audio-input") == [{"start_s": 1.0, "end_s": 3.5}]
+ assert bodies(studio, "/v1/audio/run")[0]["inputs"]["reference"] == {"input_id": "in-5"}
+
+
+def test_another_accounts_video_is_the_routes_404(monkeypatch):
+ missing = {
+ ("POST", f"{VIDEOS}/video-9/audio-input"): JSONResponse({"detail": "Video not found."}, 404)
+ }
+ result, _studio = run_tool(
+ monkeypatch, missing, "transcribe", {"audio": {"video_id": "video-9"}}
+ )
+ assert result["isError"] is True and result["content"][0]["text"].startswith("Video not found.")
+
+
+ "tool,args",
+ [
+ ("generate_image", {"prompt": "x", "init_image": {"gallery_id": "g", "frame": "last"}}),
+ ("generate_image", {"prompt": "x", "init_image": {"video_id": "v", "frame": -1}}),
+ ("generate_image", {"prompt": "x", "init_image": {"video_id": "../v"}}),
+ ("transcribe", {"audio": {"clip_id": "c", "start_s": 1}}),
+ ("transcribe", {"audio": {"video_id": "v", "start_s": 3, "end_s": 2}}),
+ ("transcribe", {"audio": {"video_id": "v", "clip_id": "c"}}),
+ ],
+)
+def test_a_bad_video_input_is_refused_without_a_call(monkeypatch, tool, args):
+ result, studio = run_tool(monkeypatch, {}, tool, args, fallback = {})
+ assert result["isError"] is True and studio.state.calls == []
diff --git a/studio/backend/tests/test_mcp_server.py b/studio/backend/tests/test_mcp_server.py
index 0ca00609e57..8695f68919c 100644
--- a/studio/backend/tests/test_mcp_server.py
+++ b/studio/backend/tests/test_mcp_server.py
@@ -11,6 +11,7 @@ READ_ONLY = {
"embed",
"get_job",
"list_models",
+ "list_media",
"list_training_runs",
"studio_status",
"system_one",
@@ -18,6 +19,7 @@ READ_ONLY = {
DESTRUCTIVE = {
"cancel",
"unload_model",
+ "voices",
}
OTHERS = {
"analyze_audio",
diff --git a/studio/backend/tests/test_mcp_tool_contract.py b/studio/backend/tests/test_mcp_tool_contract.py
index 3fa1ff1e498..e2d4056d389 100644
--- a/studio/backend/tests/test_mcp_tool_contract.py
+++ b/studio/backend/tests/test_mcp_tool_contract.py
@@ -322,7 +322,7 @@ PATH_CALLS = [
("POST", "/v1/audio/inputs"): JSONResponse({"id": "in-1"}, status_code = 201),
("POST", "/v1/audio/run"): {"clips": [CLIP]},
},
- ["/v1/audio/inputs", "/v1/audio/run", "/v1/audio/gallery/clip-1/file"],
+ ["/v1/audio/inputs", "/v1/audio/run", "/v1/audio/gallery/clip-1/signed-url"],
lambda result, studio: call_to(studio, "/v1/audio/inputs")[3] == WAV,
),
(
@@ -339,6 +339,16 @@ PATH_CALLS = [
and form(studio, "/v1/audio/transcriptions")["file"] == ("mcp-input.wav", WAV)
),
),
+ (
+ "voices",
+ lambda path: {"action": "save", "source": {"path": path}, "name": "Narrator"},
+ {
+ ("POST", "/v1/audio/inputs"): JSONResponse({"id": "in-1"}, status_code = 201),
+ ("POST", "/v1/audio/voices"): {"id": "voice-1", "name": "Narrator"},
+ },
+ ["/v1/audio/inputs", "/v1/audio/voices"],
+ lambda result, studio: result["structuredContent"]["voice"]["id"] == "voice-1",
+ ),
(
"analyze_audio",
lambda path: {"audio": {"path": path}},
@@ -353,7 +363,11 @@ PATH_CALLS = [
"generate_image",
lambda path: {"prompt": "x", "init_image": {"path": path}},
{IMAGES: {"images": [{"id": "img-1", "width": 8, "height": 8}]}},
- ["/api/inference/images/generate", "/api/inference/images/gallery/img-1/file"],
+ [
+ "/api/inference/images/generate",
+ "/api/inference/images/gallery/img-1/signed-url",
+ "/api/inference/images/gallery/img-1/file",
+ ],
None,
),
(
@@ -367,7 +381,7 @@ PATH_CALLS = [
def _input_file(tmp_path, tool):
- audio = tool in ("generate_audio", "transcribe", "analyze_audio")
+ audio = tool in ("generate_audio", "transcribe", "voices", "analyze_audio")
path = tmp_path / ("mcp-input.wav" if audio else "mcp-input.png")
path.write_bytes(WAV if audio else PNG)
return str(path)
diff --git a/studio/backend/tests/test_mcp_tools_audio.py b/studio/backend/tests/test_mcp_tools_audio.py
index 45684bf1be3..5e424c4d177 100644
--- a/studio/backend/tests/test_mcp_tools_audio.py
+++ b/studio/backend/tests/test_mcp_tools_audio.py
@@ -124,7 +124,7 @@ WORKFLOWS = [
lambda body, result: (
[c["role"] for c in result["structuredContent"]["clips"]] == list(STEMS)
and result["structuredContent"]["group_id"] == "grp-1"
- and [c["type"] for c in result["content"][1:]] == ["audio"] * 4
+ and [c["type"] for c in result["content"][1:]] == ["resource_link"] * 4
),
),
]
@@ -201,7 +201,11 @@ def test_short_clips_are_inline_and_long_ones_are_links_never_fetched(monkeypatc
or Response(WAV)
}
result, _studio = _generate(
- monkeypatch, {"workflow": "speak", "text": "Hi"}, run, long_file, **REMOTE
+ monkeypatch,
+ {"workflow": "speak", "text": "Hi", "return_media": "inline"},
+ run,
+ long_file,
+ **REMOTE,
)
content = result["content"]
assert [c["type"] for c in content[1:]] == ["audio", "resource_link"]
@@ -451,6 +455,7 @@ def test_a_stored_clip_is_transcribed_by_id_with_the_loaded_model(
timestamps = args.get("timestamps", False)
assert result["structuredContent"] == {
"text": "A long meeting.",
+ "transcript_id": "tr-1",
"language": "en",
"model": model,
"segments": [{"start": 0.0, "end": 5.0, "text": "A long meeting.", "speaker": None}]
diff --git a/studio/backend/tests/test_mcp_tools_images.py b/studio/backend/tests/test_mcp_tools_images.py
index d1fb5dcb96a..2c8b4179d2d 100644
--- a/studio/backend/tests/test_mcp_tools_images.py
+++ b/studio/backend/tests/test_mcp_tools_images.py
@@ -74,6 +74,12 @@ def _studio(overrides = None):
**PAYLOADS,
("GET", f"{GALLERY}/img-small/file"): _png,
("GET", f"{GALLERY}/img-large/file"): _webp,
+ **{
+ ("GET", f"{GALLERY}/{i}/signed-url"): {
+ "url": f"{GALLERY}/{i}/file-signed?token=t.{i}"
+ }
+ for i in ("img-small", "img-large")
+ },
**(overrides or {}),
}
)
@@ -98,6 +104,7 @@ def test_txt2img_returns_ids_urls_and_inline_images(monkeypatch):
{
"id": i,
"url": f"{remote}/{i}/file",
+ "download_url": f"{remote}/{i}/file-signed?token=t.{i}",
"width": side,
"height": side,
"seed": seed,
@@ -114,14 +121,14 @@ def test_txt2img_returns_ids_urls_and_inline_images(monkeypatch):
assert content[1]["mimeType"] == "image/png"
assert base64.b64decode(content[2]["data"]) == WEBP
assert content[2]["mimeType"] == "image/webp"
- assert content[3]["uri"] == f"{remote}/img-large/file"
+ assert content[3]["uri"] == f"{remote}/img-large/file-signed?token=t.img-large"
assert bodies(studio, "/api/inference/images/generate") == [
{"prompt": "a red fox", "width": 512, "steps": 4}
]
# A large image is never fetched in full; gallery files are fetched as the caller.
assert queries(studio, f"{GALLERY}/img-large/file") == [{"thumb": "1024"}]
fetches = [c[2] for c in studio.state.calls if "/gallery/" in c[1]]
- assert len(fetches) == 2
+ assert len(fetches) == 4
for headers in fetches:
assert headers["authorization"] == "Bearer sk-unsloth-test"
assert headers["host"] == "unsloth-mcp.invalid"
diff --git a/studio/backend/tests/test_mcp_tools_library.py b/studio/backend/tests/test_mcp_tools_library.py
new file mode 100644
index 00000000000..0cae70622b5
--- /dev/null
+++ b/studio/backend/tests/test_mcp_tools_library.py
@@ -0,0 +1,300 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import pytest
+from fastapi.responses import JSONResponse
+
+from .mcp_harness import REMOTE, bodies, queries, run_tool
+
+IMAGES = "/api/inference/images/gallery"
+VIDEOS = "/api/inference/video/gallery"
+AUDIO = "/api/inference/audio/gallery"
+TRANSCRIPTS = "/api/inference/audio/transcripts"
+VOICES = "/v1/audio/voices"
+BASE = "http://192.168.1.20:8888"
+WHEN = "2026-10-17T00:00:00Z"
+
+
+def _minted(base, media_id):
+ return {
+ ("GET", f"{base}/{media_id}/signed-url"): {
+ "url": f"{base}/{media_id}/file-signed?token=t.1"
+ }
+ }
+
+
+def _voice(n):
+ return {
+ "id": f"voice-{n}",
+ "name": f"Narrator {n}",
+ "transcript": "Hello there.",
+ "language": "en",
+ "duration_s": 3.0,
+ "sample_rate": 24000,
+ "created_at": WHEN,
+ "url": f"/api/inference/audio/voices/voice-{n}/file",
+ }
+
+
+# Undeclared route fields (loras, gguf_filename, settings) can hold host paths and are never copied.
+PAYLOADS = {
+ ("GET", IMAGES): {
+ "images": [
+ {
+ "id": "img-1",
+ "url": f"{IMAGES}/img-1/file",
+ "prompt": "a red fox",
+ "model": "flux",
+ "width": 512,
+ "height": 512,
+ "seed": 7,
+ "created_at": 1.5,
+ "loras": ["/srv/lora:1"],
+ "gguf_filename": "/srv/flux.gguf",
+ }
+ ],
+ "has_more": True,
+ },
+ ("GET", VIDEOS): {
+ "videos": [
+ {"id": "video-1", "prompt": "waves", "fps": 24, "has_audio": True, "created_at": WHEN}
+ ],
+ "has_more": False,
+ },
+ ("GET", AUDIO): {
+ "audio": [
+ {
+ "id": "clip-1",
+ "prompt": "Hi",
+ "model": "kokoro",
+ "workflow": "clone",
+ "voice_id": "voice-1",
+ "duration_s": 1.0,
+ "created_at": WHEN,
+ "settings": {"options": {"speaker": "/srv/x.wav"}},
+ }
+ ],
+ "has_more": True,
+ "next_before_mtime": 1760000000.5,
+ "next_before_id": "clip-1",
+ "next_before_pin": None,
+ },
+ ("GET", TRANSCRIPTS): {
+ "transcripts": [
+ {"id": "tr-1", "title": "meeting.wav", "text": "Hello.", "segment_count": 1}
+ ],
+ "next_cursor": f"{WHEN}|tr-1",
+ },
+ ("GET", VOICES): {"voices": [_voice(1), _voice(2), _voice(3)]},
+ **_minted(IMAGES, "img-1"),
+ **_minted(VIDEOS, "video-1"),
+ **_minted("/v1/audio/gallery", "clip-1"),
+}
+
+# (kind, the list key, its first row, next_cursor).
+KINDS = [
+ (
+ "image",
+ "images",
+ {
+ "id": "img-1",
+ "url": f"{BASE}{IMAGES}/img-1/file",
+ "download_url": f"{BASE}{IMAGES}/img-1/file-signed?token=t.1",
+ "prompt": "a red fox",
+ "model": "flux",
+ "workflow": None,
+ "width": 512,
+ "height": 512,
+ "seed": 7,
+ "created_at": 1.5,
+ "pinned": False,
+ },
+ "image:1",
+ ),
+ (
+ "video",
+ "videos",
+ {"download_url": f"{BASE}{VIDEOS}/video-1/file-signed?token=t.1", "fps": 24.0},
+ None,
+ ),
+ (
+ "audio",
+ "audio",
+ {"url": f"{BASE}/v1/audio/gallery/clip-1/file", "workflow": "clone", "voice_id": "voice-1"},
+ "audio:|1760000000.5|clip-1",
+ ),
+ (
+ "transcript",
+ "transcripts",
+ {"id": "tr-1", "title": "meeting.wav", "text": "Hello."},
+ f"transcript:{WHEN}|tr-1",
+ ),
+ ("voice", "voices", {"name": "Narrator 1", "url": f"{BASE}{VOICES}/voice-1/file"}, "voice:2"),
+]
+
+
[email protected]("kind,key,first,after", KINDS)
+def test_each_kind_lists_typed_rows_and_a_cursor(monkeypatch, kind, key, first, after):
+ args = {"kind": kind, "limit": 2}
+ result, _studio = run_tool(monkeypatch, PAYLOADS, "list_media", args, **REMOTE)
+ out = result["structuredContent"]
+ assert out["kind"] == kind and out["next_cursor"] == after
+ assert first.items() <= out[key][0].items()
+ assert [k for k, v in out.items() if isinstance(v, list)] == [key]
+
+
+# (cursor, the route it reaches, the query sent, the next cursor).
+PAGES = [
+ ("image:20", IMAGES, {"limit": "2", "offset": "20"}, "image:21"),
+ ("video:4", VIDEOS, {"limit": "2", "offset": "4"}, None),
+ (
+ "audio:3.0|1760000001.25|clip-9",
+ AUDIO,
+ {"limit": "2", "before_pin": "3.0", "before_mtime": "1760000001.25", "before_id": "clip-9"},
+ "audio:|1760000000.5|clip-1",
+ ),
+ (
+ "audio:|1760000001.25|clip-9",
+ AUDIO,
+ {"limit": "2", "before_mtime": "1760000001.25", "before_id": "clip-9"},
+ "audio:|1760000000.5|clip-1",
+ ),
+ (
+ f"transcript:{WHEN}|tr-0",
+ TRANSCRIPTS,
+ {"limit": "2", "before": f"{WHEN}|tr-0"},
+ f"transcript:{WHEN}|tr-1",
+ ),
+]
+
+
[email protected]("cursor,path,query,after", PAGES)
+def test_a_cursor_maps_to_the_routes_own_paging(monkeypatch, cursor, path, query, after):
+ kind = cursor.partition(":")[0]
+ args = {"kind": kind, "limit": 2, "cursor": cursor}
+ result, studio = run_tool(monkeypatch, PAYLOADS, "list_media", args)
+ assert queries(studio, path) == [query]
+ assert result["structuredContent"]["next_cursor"] == after
+
+
+def test_voices_are_paged_locally(monkeypatch):
+ args = {"kind": "voice", "limit": 2, "cursor": "voice:2"}
+ result, _studio = run_tool(monkeypatch, PAYLOADS, "list_media", args)
+ out = result["structuredContent"]
+ assert [v["id"] for v in out["voices"]] == ["voice-3"] and out["next_cursor"] is None
+
+
+def test_a_failed_mint_leaves_download_url_empty(monkeypatch):
+ routes = {**PAYLOADS, ("GET", f"{IMAGES}/img-1/signed-url"): JSONResponse({}, status_code = 403)}
+ result, _studio = run_tool(monkeypatch, routes, "list_media", {"kind": "image"})
+ assert result["structuredContent"]["images"][0]["download_url"] is None
+
+
+ "args,message",
+ [
+ ({"kind": "image", "cursor": "audio:|1.0|clip-1"}, "not from list_media(kind='image')"),
+ ({"kind": "audio", "cursor": "image:5"}, "not from list_media(kind='audio')"),
+ ({"kind": "image", "cursor": "image:-1"}, "malformed"),
+ ({"kind": "audio", "cursor": "audio:1.0|clip-1"}, "malformed"),
+ ({"kind": "audio", "cursor": "audio:|1.0|../x"}, "malformed"),
+ ({"kind": "transcript", "cursor": "transcript:"}, "malformed"),
+ ({"kind": "audio", "cursor": "audio:|e|clip-1"}, "malformed"),
+ ({"kind": "audio", "cursor": "audio:|1e999|clip-1"}, "malformed"),
+ ({"kind": "audio", "cursor": "audio:..|1.0|clip-1"}, "malformed"),
+ ({"kind": "audio", "cursor": "audio:|1.0|clip-1\n"}, "malformed"),
+ ({"kind": "image", "cursor": "image:5\n"}, "malformed"),
+ ({"kind": "image", "limit": 0}, None),
+ ({"kind": "image", "limit": 51}, None),
+ ({"kind": "album"}, None),
+ ],
+)
+def test_a_bad_list_media_call_is_refused_without_a_call(monkeypatch, args, message):
+ result, studio = run_tool(monkeypatch, {}, "list_media", args, fallback = {})
+ assert result["isError"] is True
+ assert message is None or message in result["content"][0]["text"]
+ assert studio.state.calls == []
+
+
+SAVED = {("POST", VOICES): JSONResponse(_voice(4), status_code = 201)}
+VOICE_PAYLOADS = {
+ **PAYLOADS,
+ **SAVED,
+ ("PATCH", f"{VOICES}/voice-1"): {**_voice(1), "name": "Host"},
+ ("DELETE", f"{VOICES}/voice-1"): {"removed": True},
+}
+# (args, the call made as (method, path), its JSON body or None, a check on the result).
+LIFECYCLE = [
+ ({"action": "list"}, ("GET", VOICES), None, lambda out: len(out["voices"]) == 3),
+ (
+ {"action": "save", "source": {"clip_id": "clip-1"}, "name": "Narrator 4", "language": "en"},
+ ("POST", VOICES),
+ {"source": {"clip_id": "clip-1"}, "name": "Narrator 4", "language": "en"},
+ lambda out: out["voice"]["id"] == "voice-4",
+ ),
+ (
+ {"action": "rename", "voice_id": "voice-1", "name": "Host"},
+ ("PATCH", f"{VOICES}/voice-1"),
+ {"name": "Host"},
+ lambda out: out["voice"]["name"] == "Host",
+ ),
+ (
+ {"action": "delete", "voice_id": "voice-1"},
+ ("DELETE", f"{VOICES}/voice-1"),
+ None,
+ lambda out: out["removed"] is True,
+ ),
+]
+
+
[email protected]("args,call,body,check", LIFECYCLE)
+def test_voices_list_save_rename_and_delete(monkeypatch, args, call, body, check):
+ result, studio = run_tool(monkeypatch, VOICE_PAYLOADS, "voices", args)
+ assert result["isError"] is False, result
+ assert [c[:2] for c in studio.state.calls] == [call]
+ assert body is None or bodies(studio, call[1]) == [body]
+ assert check(result["structuredContent"])
+
+
+def test_a_voice_saved_from_a_video_uses_its_sound(monkeypatch):
+ routes = {**SAVED, ("POST", f"{VIDEOS}/video-1/audio-input"): {"id": "in-7"}}
+ args = {"action": "save", "source": {"video_id": "video-1", "end_s": 4}, "name": "Narrator 4"}
+ result, studio = run_tool(monkeypatch, routes, "voices", args)
+ assert result["isError"] is False
+ assert bodies(studio, f"{VIDEOS}/video-1/audio-input") == [{"end_s": 4.0}]
+ assert bodies(studio, VOICES)[0]["source"] == {"input_id": "in-7"}
+
+
+ "args,message",
+ [
+ (
+ {"action": "save", "source": {"voice_id": "voice-1"}, "name": "x"},
+ "not from another saved voice",
+ ),
+ ({"action": "save", "source": {"clip_id": "clip-1"}}, "save needs source and name"),
+ ({"action": "rename", "name": "x"}, "rename needs voice_id"),
+ ({"action": "delete", "voice_id": "../voice-1"}, "delete needs voice_id"),
+ ({"action": "rename", "voice_id": "voice-1"}, "rename needs name, transcript or language"),
+ ({"action": "save", "source": {"clip_id": "c"}, "name": "x" * 81}, None),
+ ],
+)
+def test_a_bad_voices_call_is_refused_without_a_call(monkeypatch, args, message):
+ result, studio = run_tool(monkeypatch, {}, "voices", args, fallback = {})
+ assert result["isError"] is True
+ assert message is None or message in result["content"][0]["text"]
+ assert studio.state.calls == []
+
+
+def test_a_missing_voice_points_at_the_listing(monkeypatch):
+ missing = {
+ ("DELETE", f"{VOICES}/voice-9"): JSONResponse(
+ {"detail": "Voice not found."}, status_code = 404
+ )
+ }
+ result, _studio = run_tool(
+ monkeypatch, missing, "voices", {"action": "delete", "voice_id": "voice-9"}
+ )
+ assert result["isError"] is True
+ text = result["content"][0]["text"]
+ assert text.startswith("Voice not found.") and "list_media(kind='voice')" in text
diff --git a/studio/backend/tests/test_mcp_tools_video.py b/studio/backend/tests/test_mcp_tools_video.py
index 739239e5277..2b925f1c650 100644
--- a/studio/backend/tests/test_mcp_tools_video.py
+++ b/studio/backend/tests/test_mcp_tools_video.py
@@ -52,9 +52,18 @@ def _thumbnail(request, body):
return Response(WEBP, media_type = "image/webp")
+SIGNED = "/api/inference/video/gallery/video-1/signed-url"
+
+
def _studio(overrides = None):
+ minted = {"url": "/api/inference/video/gallery/video-1/file-signed?token=t.1"}
return fake_studio(
- {**PAYLOADS, ("GET", "/v1/videos/video-1/content"): _thumbnail, **(overrides or {})}
+ {
+ **PAYLOADS,
+ ("GET", "/v1/videos/video-1/content"): _thumbnail,
+ ("GET", SIGNED): minted,
+ **(overrides or {}),
+ }
)
@@ -104,6 +113,7 @@ def test_a_completed_job_returns_its_thumbnail_and_a_link_never_the_mp4(monkeypa
"error": None,
"video": {
"url": "http://192.168.1.20:8888/v1/videos/video-1/content",
+ "download_url": "http://192.168.1.20:8888/api/inference/video/gallery/video-1/file-signed?token=t.1",
"thumbnail_inline": True,
},
"recipe": None,
@@ -113,10 +123,11 @@ def test_a_completed_job_returns_its_thumbnail_and_a_link_never_the_mp4(monkeypa
content = result["content"]
assert [c["type"] for c in content[1:]] == ["image", "resource_link"]
assert base64.b64decode(content[1]["data"]) == WEBP
- assert content[2]["uri"] == "http://192.168.1.20:8888/v1/videos/video-1/content"
+ assert content[2]["uri"] == out["video"]["download_url"]
assert content[2]["mimeType"] == "video/mp4"
assert queries(studio, "/v1/videos/video-1/content") == [{"variant": "thumbnail"}]
- assert not [c for c in studio.state.calls if "/gallery/" in c[1]]
+ assert queries(studio, SIGNED) == [{"ttl_s": "3600"}]
+ assert [c[1] for c in studio.state.calls if "/gallery/" in c[1]] == [SIGNED]
def test_an_unavailable_thumbnail_leaves_only_the_link(monkeypatch):
diff --git a/studio/backend/tests/test_media_signed_links.py b/studio/backend/tests/test_media_signed_links.py
new file mode 100644
index 00000000000..c04447e57f4
--- /dev/null
+++ b/studio/backend/tests/test_media_signed_links.py
@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Key-free signed links for gallery images, audio and video: mint with the bearer, fetch with
+nothing but the link, and only for the minting account while it is active and the link is fresh."""
+
+from __future__ import annotations
+
+import sqlite3
+import time
+import types
+from contextlib import closing
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from auth import policy, storage as auth_storage
+from auth.authentication import authenticated_via_api_key, get_current_subject
+from routes import inference, video
+from utils.account_context import bind_account, reset_account, run_as
+
+from .test_account_media_isolation import ALICE, BOB, _save, isolated # noqa: F401
+
+# kind -> (module holding the signer and its clock, signer, mount the links are fetched on)
+KINDS = {
+ "images": (inference, "_sign_image_id", "time", "/api/inference/images/gallery"),
+ "audio": (inference, "_sign_audio_id", "time", "/v1/audio/gallery"),
+ "video": (video, "_sign_video_id", "_time", "/api/inference/video/gallery"),
+}
+
+
+def _app(account = None) -> TestClient:
+ """Mounted like main.py; with no account, the real auth dependency runs (no overrides)."""
+ app = FastAPI()
+ if account is not None:
+
+ async def subject():
+ token = bind_account(account)
+ try:
+ yield account.username
+ finally:
+ reset_account(token)
+
+ app.dependency_overrides[get_current_subject] = subject
+ app.dependency_overrides[authenticated_via_api_key] = lambda: False
+ for prefix in ("/api/inference", "/v1"):
+ app.include_router(inference.router, prefix = prefix)
+ app.include_router(inference.studio_router, prefix = "/api/inference")
+ app.include_router(video.router, prefix = "/api/inference")
+ return TestClient(app)
+
+
+def _mint(
+ kind,
+ media_id,
+ account = ALICE,
+ **params,
+):
+ with _app(account) as client:
+ return client.get(f"{KINDS[kind][3]}/{media_id}/signed-url", params = params)
+
+
+def _exp_left(url: str) -> int:
+ return int(url.split("token=", 1)[1].rsplit(".", 2)[1]) - int(time.time())
+
+
[email protected]("kind", list(KINDS))
+def test_a_minted_link_fetches_with_no_credential_at_all(kind):
+ media_id = run_as(ALICE, _save, kind)["id"]
+ root = KINDS[kind][3]
+ minted = _mint(kind, media_id)
+ assert minted.status_code == 200, minted.text
+ url = minted.json()["url"]
+ assert url.startswith(f"{root}/{media_id}/file-signed?token=")
+ with _app() as bare:
+ fetched = bare.get(url)
+ assert fetched.status_code == 200, fetched.text
+ assert "immutable" in fetched.headers["cache-control"]
+ # Control: the same client is refused on the bearer route, so the link is the credential.
+ assert bare.get(f"{root}/{media_id}/file").status_code in (401, 403)
+ with _app(ALICE) as client:
+ assert fetched.content == client.get(f"{root}/{media_id}/file").content
+
+
+def test_audio_link_serves_ranges_and_follows_the_mount_called():
+ audio_id = run_as(ALICE, _save, "audio")["id"]
+ with _app(ALICE) as client:
+ url = client.get(f"/api/inference/audio/gallery/{audio_id}/signed-url").json()["url"]
+ assert url.startswith(f"/api/inference/audio/gallery/{audio_id}/file-signed?token=")
+ ranged = _app().get(_mint("audio", audio_id).json()["url"], headers = {"Range": "bytes=0-3"})
+ assert ranged.status_code == 206
+ assert ranged.headers["content-type"] == "audio/wav"
+ assert len(ranged.content) == 4
+
+
[email protected]("kind", list(KINDS))
+def test_a_link_works_until_its_expiry_and_not_after(kind, monkeypatch):
+ module, sign, clock, root = KINDS[kind]
+ media_id = run_as(ALICE, _save, kind)["id"]
+ token = run_as(ALICE, getattr(module, sign), media_id)
+ exp = int(token.rsplit(".", 2)[1])
+ url = f"{root}/{media_id}/file-signed"
+ with _app() as bare:
+ for now, status in ((exp - 1, 200), (exp + 1, 401)):
+ monkeypatch.setattr(module, clock, types.SimpleNamespace(time = lambda now = now: now))
+ response = bare.get(url, params = {"token": token})
+ assert response.status_code == status, (now, response.text)
+ assert response.json()["detail"].startswith("Invalid or expired")
+
+
[email protected]("kind", list(KINDS))
+def test_links_serve_only_the_minting_account_and_die_with_it(kind):
+ module, sign, _clock, root = KINDS[kind]
+ media_id = run_as(ALICE, _save, kind)["id"]
+ assert _mint(kind, media_id, BOB).status_code == 404
+ assert _mint(kind, "missing", ALICE).status_code == 404
+ token = run_as(ALICE, getattr(module, sign), media_id)
+ url = f"{root}/{media_id}/file-signed"
+ with _app() as bare:
+ tampered = token.replace(ALICE.account_id, BOB.account_id)
+ assert bare.get(url, params = {"token": tampered}).status_code == 401
+ assert bare.get(f"{root}/guessed/file-signed", params = {"token": token}).status_code == 401
+ assert bare.get(url, params = {"token": token[:-1] + "x"}).status_code == 401
+ assert bare.get(url, params = {"token": token}).status_code == 200
+ with closing(sqlite3.connect(auth_storage.DB_PATH)) as conn:
+ conn.execute("UPDATE auth_user SET is_active=0 WHERE username='alice'")
+ conn.commit()
+ policy.invalidate_account_cache()
+ assert bare.get(url, params = {"token": token}).status_code == 401
+
+
[email protected]("kind", list(KINDS))
+def test_mcp_links_last_an_hour_and_the_ui_video_link_twelve(kind):
+ media_id = run_as(ALICE, _save, kind)["id"]
+ params = {"ttl_s": 3600} if kind == "video" else {}
+ assert 3590 <= _exp_left(_mint(kind, media_id, **params).json()["url"]) <= 3600
+ if kind == "video":
+ assert 43190 <= _exp_left(_mint(kind, media_id).json()["url"]) <= 43200
+ for ttl_s in (59, 43201):
+ assert _mint(kind, media_id, ttl_s = ttl_s).status_code == 422
+
+
[email protected]("kind", ["images", "audio"])
+def test_keyless_callers_cannot_mint_links(kind, monkeypatch):
+ import auth.authentication
+
+ media_id = run_as(ALICE, _save, kind)["id"]
+ monkeypatch.setattr(auth.authentication, "request_admitted_without_credential", lambda r: True)
+ response = _mint(kind, media_id)
+ assert response.status_code == 403
+ assert "API key" in response.json()["detail"]
+
+
+def test_an_audio_link_with_a_non_ascii_signature_is_refused_not_a_crash():
+ audio_id = run_as(ALICE, _save, "audio")["id"]
+ token = run_as(ALICE, inference._sign_audio_id, audio_id)
+ url = f"/v1/audio/gallery/{audio_id}/file-signed"
+ with _app() as bare:
+ response = bare.get(url, params = {"token": token[:-1] + "é"})
+ assert response.status_code == 401, response.text
diff --git a/studio/backend/tests/test_video_gallery_inputs.py b/studio/backend/tests/test_video_gallery_inputs.py
new file mode 100644
index 00000000000..33d11cef155
--- /dev/null
+++ b/studio/backend/tests/test_video_gallery_inputs.py
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""A gallery video as an input: one frame as PNG, or its audio track as an audio input."""
+
+from __future__ import annotations
+
+import io
+
+import pytest
+from PIL import Image
+
+from core.inference import audio_inputs, video_gallery
+from utils.account_context import run_as
+
+from .test_account_media_isolation import ALICE, BOB, _client, isolated # noqa: F401
+from .test_video_gallery import _real_mp4_bytes, _real_mp4_with_audio
+
+pytest.importorskip("av")
+
+
+def _clip(data: bytes, prompt: str = "a grey ramp") -> str:
+ meta = {
+ "prompt": prompt,
+ "width": 64,
+ "height": 48,
+ "num_frames": 8,
+ "fps": 8,
+ "duration_s": 1.0,
+ "steps": 1,
+ "guidance": 1.0,
+ "seed": 7,
+ "model": "test/none",
+ "created_at": "2026-01-01T00:00:00+00:00",
+ }
+ return run_as(ALICE, video_gallery.save, data, meta)["id"]
+
+
+def _grey(png: bytes) -> int:
+ image = Image.open(io.BytesIO(png)).convert("L")
+ return image.getpixel((image.width // 2, image.height // 2))
+
+
+def test_frames_pick_first_last_and_a_time():
+ # Frame i is grey (i * 30): 8 frames at 8 fps, so 0.5 s shows frame 4.
+ video_id = _clip(_real_mp4_bytes(frames = 8, size = (64, 48), rate = 8))
+ url = f"/api/inference/video/gallery/{video_id}/frame"
+ with _client(ALICE) as client:
+ for at, grey in (("first", 0), ("last", 210), ("0.5", 120), ("0", 0)):
+ response = client.get(url, params = {"at": at})
+ assert response.status_code == 200, response.text
+ assert response.headers["content-type"] == "image/png"
+ assert abs(_grey(response.content) - grey) <= 12, (at, _grey(response.content))
+ assert Image.open(io.BytesIO(client.get(url).content)).size == (64, 48)
+ small = client.get(url, params = {"at": "last", "max_px": 32})
+ assert Image.open(io.BytesIO(small.content)).size == (32, 24)
+ past = client.get(url, params = {"at": "5"})
+ assert past.status_code == 400
+ assert "past the end" in past.json()["detail"]
+ for bad in ("middle", "-1", "nan"):
+ assert client.get(url, params = {"at": bad}).status_code == 400
+ assert client.get(url, params = {"max_px": 8}).status_code == 422
+ with _client(BOB) as client:
+ assert client.get(url).status_code == 404
+
+
+def test_frame_times_count_from_a_stream_that_does_not_start_at_zero(tmp_path):
+ # Frame i is grey (i * 30) at 8 fps, with timestamps starting at 1 s: 0.5 s is still frame 4.
+ av = pytest.importorskip("av")
+ np = pytest.importorskip("numpy")
+ path = tmp_path / "offset.mp4"
+ with av.open(str(path), "w", format = "mp4") as out:
+ stream = out.add_stream("mpeg4", rate = 8)
+ stream.width, stream.height, stream.pix_fmt = 64, 48, "yuv420p"
+ for i in range(8):
+ frame = av.VideoFrame.from_ndarray(
+ np.full((48, 64, 3), i * 30, dtype = np.uint8), format = "rgb24"
+ )
+ frame.pts = i + 8
+ for packet in stream.encode(frame):
+ out.mux(packet)
+ for packet in stream.encode():
+ out.mux(packet)
+ with av.open(str(path)) as src:
+ assert src.streams.video[0].start_time # the fixture really is offset
+ for at, grey in (("first", 0), ("0.5", 120), ("0", 0), ("last", 210)):
+ assert abs(_grey(video_gallery.frame_png(path, at)) - grey) <= 12, at
+
+
+def test_a_clip_that_cannot_be_read_gets_a_plain_error_without_server_paths(monkeypatch, tmp_path):
+ video_id = _clip(b"not an mp4 at all, only bytes")
+ url = f"/api/inference/video/gallery/{video_id}/frame"
+ with _client(ALICE) as client:
+ broken = client.get(url)
+ assert broken.status_code == 400
+ assert broken.json()["detail"] == "This clip could not be decoded."
+ # The file can go away between the ownership check and the decode.
+ monkeypatch.setattr(video_gallery, "owned_video_path", lambda _id: tmp_path / "gone.mp4")
+ gone = client.get(url)
+ assert gone.status_code == 404
+ assert gone.json()["detail"] == "Video not found."
+
+
+def test_audio_track_becomes_a_trimmed_idempotent_audio_input():
+ video_id = _clip(_real_mp4_with_audio(seconds = 1))
+ url = f"/api/inference/video/gallery/{video_id}/audio-input"
+ body = {"start_s": 0.25, "end_s": 0.75}
+ with _client(ALICE) as client:
+ first = client.post(url, json = body)
+ assert first.status_code == 201, first.text
+ record = first.json()
+ assert abs(record["duration_s"] - 0.5) <= 0.02
+ assert record["name"] == "a grey ramp (audio).wav"
+ again = client.post(url, json = body)
+ assert again.status_code == 200
+ assert again.json()["id"] == record["id"]
+ assert client.get(record["url"]).status_code == 200
+ whole = client.post(url, json = {})
+ assert whole.status_code == 201
+ assert whole.json()["duration_s"] >= 0.95
+ past = client.post(url, json = {"start_s": 5})
+ assert past.status_code == 400
+ assert "past the end" in past.json()["detail"]
+ for invalid in ({"start_s": 0.5, "end_s": 0.5}, {"start_s": -1}, {"name": "x"}):
+ assert client.post(url, json = invalid).status_code == 422
+ with _client(BOB) as client:
+ assert client.post(url, json = body).status_code == 404
+ leftovers = list(run_as(ALICE, audio_inputs.inputs_dir).glob(".*.tmp"))
+ assert leftovers == []
+
+
+def test_an_audio_input_name_keeps_a_prompt_with_slashes_and_line_breaks():
+ video_id = _clip(_real_mp4_with_audio(seconds = 1), prompt = "cats/dogs\nat dusk")
+ with _client(ALICE) as client:
+ response = client.post(f"/api/inference/video/gallery/{video_id}/audio-input", json = {})
+ assert response.status_code == 201, response.text
+ assert response.json()["name"] == "cats dogs at dusk (audio).wav"
+
+
+def test_a_silent_video_has_no_audio_track_to_extract():
+ video_id = _clip(_real_mp4_bytes())
+ with _client(ALICE) as client:
+ response = client.post(f"/api/inference/video/gallery/{video_id}/audio-input", json = {})
+ assert response.status_code == 400
+ assert response.json()["detail"].startswith("This video has no audio track")
+ assert list(run_as(ALICE, audio_inputs.inputs_dir).iterdir()) == []