Skip to main content
Video clipping identifies when an event occurs. Ask for a moment when you need one event boundary, or an interval when you need the duration of an action. Visual events use the video frames; audible events require soundtrack analysis. The response contains temporal annotations; it does not create a new video file.

Find a basketball event

This example asks two different questions about the same shot: when the ball passes through the hoop, and the interval covering the shot attempt. Each request defines what to include so the model can distinguish the event from the surrounding play. Install the perceptron>=0.4.0 Python package and set PERCEPTRON_API_KEY before running:

Locate an audible cue

The basketball sample also contains audio. Reuse locate_event with include_soundtrack=True to locate an audible event on the same video timeline:
This sets vision_config.enable_audio_in_video alongside annotation_format: "clip"; the default remains frames only. Define the cue you want, such as an audible phrase, an alarm, or a change in background sound. Do not treat a visible action as proof that its expected sound occurred. Returned times are estimates, so review the source audio before making a precise cut. Both the frames and soundtrack belong to video asset 0. Timestamped frames alone cannot supply audio evidence. Use the original video or an excerpt that retains its soundtrack when refining an audible boundary, and preserve any offset to the original timeline. See video soundtracks for input handling and limits.

Interpret moments and intervals

These examples illustrate the markup; the times are not measured predictions for the sample video:
The first annotation is a moment. The second is an interval with a start and end. Both refer to the video at asset 0. A moment is an approximate location in time; it does not establish a playable duration. To create a highlight, your application can add a chosen amount of time before and after it, clamped to the video boundaries. For repeated events, request a separate clip for each occurrence. A collection can describe the group with mention and supply an inherited asset selector:
This is also an illustrative format example. See annotation format for timestamp parsing and asset selector inheritance.

Use temporal evidence

Before seeking, cutting, or displaying a returned clip, validate its asset selector and timestamps. Check that times are finite, within the chosen video’s timeline, and ordered for an interval. A response ending with finish_reason: "length" may contain unfinished annotations; do not treat it as a complete result. Frame sampling can miss a short event or leave its boundary uncertain. Avoid promising frame-exact cuts from an estimated timestamp. For a closer look, provide frames around the candidate interval using timestamped video frames, preserving the timeline or recording any excerpt offset. Use video Q&A when you need an explanation of the event. Use video tracking when you also need an object’s location over time.