Video sources & formats
What video sources can I ingest?
What video sources can I ingest?
Three ways, all via
POST /videos (or the file / resumable variants):- By URL — a direct, publicly-fetchable HTTPS media URL.
- By file — upload the file directly; use the resumable flow for large files.
- Live streams — attach an
rtsp/rtmp/httppull source with Open Stream.
Which containers / formats are supported?
Which containers / formats are supported?
mp4, m4v, mov, mkv, webm, avi, flv, f4v, wmv, mpg, mpeg, 3gp, ts, m2ts. A non-video file returns 415 unsupported_media.Can I ingest videos from TikTok, YouTube, Instagram, or X?
Can I ingest videos from TikTok, YouTube, Instagram, or X?
You provide each video as a direct, fetchable media URL (the actual video file) or upload the file yourself. We don’t pull from a TikTok / YouTube / Instagram / X page or account link — resolve it to the underlying media URL first, then pass that as
source_url. A platform page URL will fail with source_unresolved. Each video is ingested independently, so a batch is just many POST /videos calls.Processing time & throughput
How long does it take to index a video?
How long does it take to index a video?
Indexing runs
preprocess → index → derive and scales with the content processed = duration × fps (default fps: 1.0, i.e. ~1 frame/second). Short clips finish quickly; long video takes proportionally longer. Watch it live by polling GET /operations/{id} — the progress field reports each stage and a percentage.How many videos can be processed at the same time?
How many videos can be processed at the same time?
Videos index in parallel. Submit them all up front — each returns its own
operation immediately (202) and they process concurrently, up to the concurrency allowed on your plan (a rolling 2-hour concurrent-indexing cap). You don’t wait for one to finish before starting the next.How do I estimate time for a batch — e.g. 50 clips of 30s?
How do I estimate time for a batch — e.g. 50 clips of 30s?
Because processing is parallel, a batch does not take N × single-video time. A useful estimate:So 50 short clips complete in a handful of parallel waves, not 50 sequential runs. For a guaranteed volume throughput / SLA, contact us with your expected daily volume and clip length and we’ll size it.
Does fps change how long it takes (and what it costs)?
Does fps change how long it takes (and what it costs)?
Yes — indexing works on frames = duration ×
fps, so fps is your main speed/cost lever. Lower fps (e.g. 0.5) indexes faster and cheaper with coarser temporal detail; raise it for fast action where you need finer moments. Default is 1.0; range 0.1–30.Do safety detection or face recognition add time?
Do safety detection or face recognition add time?
A little. They’re opt-in collection flags that run extra derivation per video, so a collection with them enabled takes somewhat longer than a plain index. Leave them off on collections that don’t need them.
What if I submit more videos than my concurrency allows?
What if I submit more videos than my concurrency allows?
Each
POST /videos still returns immediately, but ingests beyond your plan’s concurrent-indexing cap come back 429 rate_limited with a Retry-After. Back off per that header (or throttle client-side) and the queue drains as slots free up — nothing is lost.When can I start searching a video — before it's fully done?
When can I start searching a video — before it's fully done?
A video becomes searchable once its operation reaches
ready. While it’s still processing you can pull derived content incrementally with ?since= — the response’s live: true means indexing is still running, so keep paging until it clears.How fast are results on a live stream?
How fast are results on a live stream?
Live captioning and events are near-real-time — they surface as the stream plays, rather than after a whole file is uploaded. Latency tracks your
fps and any enabled detectors. There’s no fixed session-duration cap.What happens if a video fails or times out?
What happens if a video fails or times out?
The operation ends with
done: true and a non-null error (e.g. source_unresolved for an unreachable link, unsupported_media for a bad format). Fix the source and re-submit — reuse the same idempotency_key so a retry never double-charges or double-ingests.Results & notifications
How do I know when a video is ready?
How do I know when a video is ready?
Every slow operation returns
202 + an operation. Either poll GET /operations/{id} until done: true, or attach a webhook (callback_url) and get a signed POST on completion — no polling. done is the only completion signal.What can I read back from an indexed video?
What can I read back from an indexed video?
Per moment or whole video: captions, transcripts, frames, clips, titles, summaries, speakers, face entities, and safety events (if a detector is enabled). Read any time-slice with Get Moment, or search across a collection with Search.
What languages are supported?
What languages are supported?
Search and retrieval run on OmniRetriever, a multilingual embedding model — you can query in one language and match content in another.
Billing & limits
Where do I see usage and billing?
Where do I see usage and billing?
In the Console → Usage & billing — balance, usage, and invoices. Your live balance is also available at
GET /usage/balance.What are the main limits?
What are the main limits?
fps 0.1–30 (default 1.0) · list limit 1–100 · Search 5 QPS/user, top_k ≤ 200 · search image ≤ 10 MB · person reference faces 1–20/call, ≤15 MB each. Full table in Errors & Rate Limits.How long do returned media URLs stay valid?
How long do returned media URLs stay valid?
Signed URLs expire — clip cache ~5h, detail
source_url / face image ~24h, search thumbnails ~15 min. Re-fetch on demand; never cache past expiry.Don’t see your question? Talk to us or point your agent at the MCP Server and just ask.