Whole-video re-identification
The object is found again after scene cuts, camera changes and re-entries, in every scene of the searched range.
CatalogLatency Async; roughly 0.8-1x the length of the searched range Async true Rate Limit Per API key; jobs run one at a time per GPU Max Input Searched range up to 600 seconds, file up to 500 MB
cn8/object-tracking
Draw a box around an object (a product, a cap, a bag...) on one frame of your video. The
Learn more about Object Tracking Videoasync (job)Instant previewvideotrackinginteractive
Track an object
Sign in to upload and track. Create a free account →
Result
The tracked video shows up here
Upload → mark the object → pick the range → track.
Overview
Draw a box around an object (a product, a cap, a bag...) on one frame of your video. The service finds that same object in every scene where it appears, not just until the next cut, and tracks it frame by frame. Similar objects of the same kind are told apart, so a blue cap is not confused with the green one you marked. You get, for every frame where the object is visible, its box or its exact outline as polygon points, in percent of the frame, so a clickable area drawn from them fits any screen size or player. Optionally publish the result as a public JSON manifest (frames + your link) that your own player can load without an API key. This is an async job: submit it, poll until it's ready, then read the frames.
Key capabilities
Tells look-alikes apart
Only the object you marked is followed; other objects of the same kind with a different look are ignored.
Box or exact outline
outputType box returns a rectangle per frame; polygon adds the object's outline as points (1-4 polygons per frame).
Resolution-independent
All coordinates are percent of the frame (0-100), so the clickable area scales to any player size.
Public manifest for your player
Publish a finished job to get a public JSON manifest (frames, link, fresh video URL) that a web player can load without your API key.
When to use it
Shoppable video
Make the product in an ad clickable everywhere it appears and send viewers to the product page.
Hotspots and annotations
Attach a label or link to an object for interactive tutorials, catalogs or sports replays.
Object timelines
Get the exact time ranges where a product or logo is on screen for reporting or editing.
Input & output
input
Video URL, the second where the box is drawn, the box in percent, a short object name, optional range and output type
JSON body
output
Appearances (time ranges) and per-frame box / polygon points in percent (async job result)
JSON
Guides & tips
How it works
- The object inside your box is segmented on the reference frame and its look is remembered.
- The searched range is split into scenes; in each scene, objects of the same kind are found and compared with your object.
- In scenes where it matches, the object is tracked forward and backward frame by frame until it leaves the frame.
Getting good results
- Draw the box tightly around the object on a frame where it is large and clearly visible.
- Name the object with its color: "green cap" works better than "cap".
- Search only the part you need with startTime/endTime: it is faster and cheaper.
- Objects that differ only by a logo or print (same color and shape) may be confused.
Errors
- The submit is always accepted and returns a job id; the request is checked when the job starts.
- A wrong request (missing objectName, time outside the range, range over 600 s, video too large or not reachable) ends as status failed, with the reason in the job's error field.
- Failed jobs are not billed; the reserved credits are released.
Using the coordinates
- All values are percent of the frame: left = x% of the player width, top = y% of its height.
- frames lists only the frames where the object is visible. Draw frames[i] from frames[i].time until the next frame; if the next entry is more than one frame later (1/fps), the object is off screen in between.
- polygons is a list of outlines, each a list of [x, y] points; box is the rectangle around them.
Publishing for your player
- POST /v1/interactive-videos with {job_id, video_object_key, title?, hotspot: {label?, url?}}.
- video_object_key is the object_key upload-media returned for the same video; job_id must be a completed job of this service on the same account.
- The response's manifest_url is public (no API key): it returns the frames, appearances, hotspot and a video_url signed for 24 hours, renewed on every request. Your player draws the clickable area from it and opens hotspot.url on click.
- hotspot.url must be an http(s) link.
Specs
Schema
Request body
videoUrlrequiredstringPublicly reachable video URL (e.g. upload-media public_url). MP4 (H.264) recommended.
timerequirednumberSecond where the box is drawn. The object should be clearly visible on that frame.
boxrequiredobjectBox around the object in percent of the frame: {x, y, w, h} (top-left corner + size, 0-100).
objectNamerequiredstringShort English name of the object, 2-4 words with its color (e.g. 'green cap', 'red handbag').
startTimenumberStart of the searched range in seconds. Default 0.
endTimenumberEnd of the searched range in seconds. Default: end of the video. The range may be at most 600 s and must contain time, so for videos longer than 10 minutes always send startTime/endTime.
outputTypestringbox (default) or polygon. polygon adds the object's outline points to every frame.
Pricing
0.2 credits per second of the searched range, minimum 10 seconds. An 80-second video searched end to end costs about 16 credits. Failed jobs are not billed.
| Service | Unit | Price |
|---|---|---|
| Video Object Tracking | second | 0.2 credits/second |
Box and polygon output cost the same.
Publishing the manifest (/v1/interactive-videos) is free.