Use Mux Shots to provide visual context to LLMs and AI workflows
Shots are Mux's approach to breaking a video down into its visual building blocks. Rather than sampling frames at fixed time intervals, Mux analyzes pixel-level changes between frames to detect each shot or continuous, uncut recording from a single camera angle. For each detected shot, Mux generates a compressed WebP preview image that represents its visual content.
Shot preview images are composed of up to one frame per second of shot duration, capped at 100 frames. For shots longer than 100 seconds, frames are sampled evenly across the full duration. For shots shorter than one second, a single frame is used.
Set "generate_shots": true when you create a Mux AssetAPI.
curl https://api.mux.com/video/v1/assets \
-H "Content-Type: application/json" \
-X POST \
-d '{
"inputs": [{ "url": "YOUR_VIDEO_URL" }],
"playback_policies": ["public"],
"generate_shots": true
}' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}When using direct uploads, set "generate_shots": true inside new_asset_settings:
curl https://api.mux.com/video/v1/uploads \
-H "Content-Type: application/json" \
-X POST \
-d '{
"cors_origin": "*",
"new_asset_settings": {
"playback_policies": ["public"],
"generate_shots": true
}
}' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}To add shots to an asset that was created without them, POST to the shots endpoint including the asset_id:
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/shots \
-X POST \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}This request is asynchronous. The POST returns immediately with the job in pending status. Listen for the video.asset.shots.ready webhook — the payload confirms when the manifest is ready. If webhooks aren't an option, poll GET /video/v1/assets/{ASSET_ID}/shots until status is completed.
Once shots are ready, fetch the manifest using your asset_id:
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/shots \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}The response includes a shots_manifest_url pointing to a JSON file hosted on artifacts.mux.com. Fetch that URL to get the full list of shots boundaries and shot preview images.
{
"data": {
"status": "completed",
"shots_manifest_url": "https://artifacts.mux.com/a/{ASSET_ID}/shots.json?skid=default&signature=...",
"created_at": "1774477977"
}
}Fetching shots_manifest_url returns a JSON array of shot objects:
{
"shots": [
{
"start_time": 0.0416667,
"shot_preview_image_url": "https://artifacts.mux.com/a/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/shot_0.webp?skid=default&signature=NjlkNWY4ZDRfYWFlYzI2Y2Y2Yjc1ZjJiYmQwNTUwNWQ0MDZlOWYxYzY0MDQ2NTY5YWE2ODRmNzM3NTIyNTAyNWQ1YzU0MTVkYQ=="
},
{
"start_time": 8.875,
"shot_preview_image_url": "https://artifacts.mux.com/a/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/shot_1.webp?skid=default&signature=NjlkNWY4ZDRfODU0ZTAxZDMxNmNkYzdmMTk1OTFjOWRiZDdjNTRjMTA1ZTg4YzJlNjdhYzgwYTNhZTNjYTM4MmY0ZDYwMTBkZg=="
},
{
"start_time": 21.333,
"shot_preview_image_url": "https://artifacts.mux.com/a/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/shot_2.webp?skid=default&signature=NjlkNWY5ZTZfMzI1ZDgwMjhhODZmZTA3NTYwNjRkZDk3NmUzZDY5Y2RjZjJkM2ZiZmMxN2ZkYzMzMjllY2RmMzhhMjg5OQ=="
},
{
"start_time": 34.708,
"shot_preview_image_url": "https://artifacts.mux.com/a/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/shot_3.webp?skid=default&signature=NjlkNWY5ZTZfYTFiMmMzZDRlNWY2YjdjOGQ5ZTBmMWEyYjNjNGQ1ZTZmN2E4YjljMGQxZTJmM2E0YjVjNmQ3ZQ=="
},
{
"start_time": 49.125,
"shot_previewimage_url": "https://artifacts.mux.com/a/DS00Spx1CV902MCtPj5WknGlR102V5HFkDe/shot_4.webp?skid=default&signature=NjlkNWY5ZTZfYjJjM2Q0ZTVmNmI3YzhkOWUwZjFhMmIzYzRkNWU2ZjdhOGI5YzBkMWUyZjNhNGI1YzZkN2U4YQ=="
}
]
}How much does generating Shots cost?
Shots are priced at $0.001 per minute of source video, billed each time you generate them. See shots pricing for details.
Is there a storage charge?
No. There is no ongoing storage charge for shot images.
Can I remove shots from an asset?
Yes. Send a DELETE to the shots endpoint to remove the shot metadata and images from an asset:
curl https://api.mux.com/video/v1/assets/${ASSET_ID}/shots \
-X DELETE \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}If you regenerate shots on the same asset later, you will be billed again for the new generation.