403s. So Torii hosts every media URL: an Item’s thumb
and media[].url point at /v1/media, and a video item also carries a small /v1/preview clip.
Media proxy
Streams a platform CDN image or video through Torii, from the same egress that resolved it. Public — an<img> or <video> can point straight at it. The url values inside an Item are already in
this shape; you rarely build one by hand.
string
The origin CDN URL (present in the Item’s media URLs, allowlisted).
string
video routes to the node that holds the session.string
The platform (for session-gated video).
string
Optional ffmpeg pass — strip metadata / a static logo.
206), so a <video> can seek.
Preview clips (hover-to-scrub)
A low-res, muted, keyframe-dense, full-length clip for a video item — the asset that makes a hover-to-scrub card (cursor X → playback position) cheap without streaming the full media. It is the whole clip, capped at 240 s; a keyframe every ~1 s makes seeking cheap. Public. Point a<video> straight at it. Returns 200 video/mp4 (h264 baseline, short side
240 px, no audio, +faststart so the duration is readable from the head), 206 on Range.
Because a full-length render is heavy, the cold path is asynchronous: a first request for an
uncached clip returns 202 {"status":"rendering"} with a Retry-After — poll the same URL until
it’s a 200. A X-Torii-Preview: hit|rendered header tells you which on a 200. Cached 14 days.
string
required
The platform.
string
required
The bare item id (from
Item.id minus the platform: prefix).Item.preview.seconds reports the rendered length (the clip’s duration, capped at 240) — map
cursor→time against it, or read the served mp4’s own duration. The Item.preview.url is already this
path and is stable across crawls (keyed on platform + id, not the rotating CDN URL). When a clip
can’t be rendered, it returns:
404
reason is one of expired | blocked | session_expired | no_stream | unsupported — fall back
to the cover, and the reason tells you why. Never a placeholder clip.
Warm a page
Render (in the background) the previews for a page you’re about to show, so the first hover is a cache hit. Requires a token (a server-to-server trigger).Request
202 Accepted
Render at crawl time
Passpreview: "eager" in a crawl’s params (for platforms whose CDN URL expires fast, like
TikTok/Douyin) and Torii renders each new video item’s preview at crawl time — before the URL dies —
bounded and best-effort, never delaying the crawl.
Account health
Lists the stored accounts and their livestatus per platform (ready, session_expired, …).
This — not a per-task error.code — is the signal to prompt a re-login: a task’s blocked is a
transient challenge, whereas /v1/profiles reporting session_expired means the account genuinely
needs a human to log back in.
Preview cache stats
Beyond liveness,/v1/health surfaces the preview cache counters so you can graph its effectiveness: