Overview
Video Clipping Search is the API surface for 9Pic Motion. It finds the moments where a participant appears in the event’s videos and returns short playable clip URLs for those moments. Participants are found by selfie (POST /video-clipping/search-by-selfie), by bib number (POST /video-clipping/search-by-bib) or, on events set to video name search, by the name of their video (POST /video-clipping/search-by-name); all return a request_id that you read with the same GET endpoint.
For a selfie search, the participant uploads a selfie (or reuses a Face Search request_id) and the API:
- Matches the selfie against faces detected across the event’s source videos.
- Groups matched frames into continuous time segments.
- Creates a clip from each matched source video: the participant’s earliest appearance, or every separate appearance in time order when the organiser turns on Multiple clips per video.
- Returns playable clip URLs you can hand to your UI.
POST call starts clip creation and returns a request_id. The GET endpoint reads the stored result by request_id, so clients can safely poll, recover, or refresh the final clip payload. The same request_id is shared with Face Search, so a single selfie upload can power both photo and video discovery — and once Face Search has run, you can start a clip with just that request_id and no file upload, because the matching frames were already computed.
For a bib search, the organiser has told 9Pic where each bib appears: a CSV of bib numbers and video times uploaded in the dashboard, bib numbers found in the videos automatically, or both (for each video, the CSV wins). The API turns those moments into clips. Everyone who searches the same bib on an event shares one result, so the first search cuts the clips and later searches reuse them.
For a video name search, the organiser has set the event to video name search: each uploaded video has a search name (its file name unless the organiser renamed it), and a participant finds their own video by typing a name or bib that appears in it. The result is the whole video, as one clip. See POST /video-clipping/search-by-name.
Video Clipping Search must be enabled for the event, and the organisation’s plan must include 9Pic Motion (Pro and above); on Trial and Pay As You Go every endpoint returns
403. Check Event Details first: video_search (the event-level toggle) must be true, plus video_selfie_search for selfie searches or video_bib_search for bib searches. Video name search is exclusive: while an event is set to it, selfie and bib searches are off (Event Details shows video_selfie_search and video_bib_search as false) and they answer 404 with “This search isn’t available for this event.” Event Details reports the mode as video_name_search; POST /video-clipping/search-by-name answers 404 with the same message when the event is not in it.Why Start and Read Are Separate
Producing a video clip is substantially more expensive than searching for photos: it has to find the matching moments, decide on the time window for each appearance in each source video, and generate playable video clips. We split this into:POST /video-clipping/search-by-selfie— accepts the selfie or a Face Searchrequest_id, persists the record, and starts clip generation.POST /video-clipping/search-by-bib— accepts a bib number, finds or creates the event’s shared result for that bib, and starts clip generation when clips are needed.POST /video-clipping/search-by-name— accepts what the participant typed, finds or creates the shared result for that name, and starts clip generation when clips are needed.GET /video-clipping/{request_id}— reads the cached result and returns a structured status payload with clip URLs once available.
request_id follows the same idempotency model as Face Search — see Conventions.
Endpoints
POST /video-clipping/search-by-selfie — Start a Search
Accepts either a selfie image or a Face Searchrequest_id, persists the request, and starts video clip generation. Returns the request_id and current status.
Path Parameters
Multipart Form Fields
You must provide a
file, a request_id, or both. A request_id with no file only works after a Face Search has run for that request_id (so the matching frames exist); otherwise the call returns 400.Example Request
request_id (for example one returned by Face Search) while still uploading a selfie, add -F "request_id=<uuid>" (cURL), data={"request_id": "<uuid>"} (Python), or formData.append("request_id", "<uuid>") (JavaScript).
To recreate deleted or expired clips for an existing request, send the same request_id with force_recreate=true. After failed or clip_failed, or once the clips have expired, a plain POST with the same request_id starts clipping again; a job that is processing or completed (with clips that have not expired) returns its current status instead.
To clip without re-uploading — the recommended flow right after a Face Search — send only the request_id and omit the file. 9Pic reuses the matching frames it already computed and starts clipping:
Example Response
processing means the request was accepted and clip generation has started. Use the returned request_id with the GET endpoint to read the latest stored state. If no video frames match, POST can return a terminal empty state such as no_matches.
POST /video-clipping/search-by-bib — Start a Bib Search
Accepts a bib number as JSON and returns therequest_id of the event’s shared result for that bib. Clip generation starts only when the bib has no usable clips yet; read the clips with the GET endpoint.
Path Parameters
JSON Body
No other field is accepted. There is no
force_recreate: the result is shared by everyone who searches that bib, so 9Pic recuts only clips that expired or failed, and keeps the old clips until the new ones exist. See VideoBibSearchRequest.
What a Bib Search Returns
- One clip per CSV row for that bib on the event’s current videos, cut at the organiser’s exact start and end times (up to 20 per bib).
- For a bib found automatically, a clip of the bib’s earliest pass on each video, or of every pass in time order when the event’s “Multiple clips per video” setting is on, cut with the event’s clip length (at most 20 clips per bib). A video where the CSV has that bib uses the CSV row instead. Bibs the organiser’s list hides return nothing.
- When the organiser prepares CSV clips ahead, ready clips come back at once (
statuscompletedon the POST); otherwise the first search for a bib takes about a minute. - The
request_idis deterministic for the event, the bib and the clip settings. A new CSV, a changed watermark or preview quality, or a re-uploaded video gives a newrequest_id(fresh clips) on the next search.
Example Request
Example Responses
- processing
- completed (clips exist)
- no_matches
no_matches means no current clip has that bib. Nothing is stored, so request_id is null and there is nothing to poll. The same bib can match later, after the organiser uploads a CSV or more videos are read.
A bib search shares its
request_id with everyone who searches that bib, and that request_id cannot be reused for a selfie search: POST /video-clipping/search-by-selfie with a bib search’s request_id returns 400.POST /video-clipping/search-by-name — Start a Video Name Search
Video name search events only. Accepts what the participant typed as JSON and returns therequest_id of the event’s shared result for that text. Clip generation starts only when the matching videos have no usable clips yet; read the clips with the GET endpoint.
Path Parameters
JSON Body
No other field is accepted. There is no
force_recreate: the result is shared by everyone who types the same text, so 9Pic recuts only clips that expired or failed. See VideoNameSearchRequest.
How a Name Is Matched
- Matching ignores case.
_,-,.and runs of spaces all count as one space, and a file extension is dropped from the video’s name. - A video matches when the typed words are the video’s whole name or an unbroken run of whole words in it, in order.
rahul sharmaand1234both findRAHUL_SHARMA_1234.mp4;rahandsharma rahulfind nothing. - At most 20 videos are returned, an exact full-name match first, then in upload order. Two videos with the same name are both returned.
- Each match is the whole video as one clip (
segment_index0). Only videos that are processed, current and 1 second to 3 minutes long can match. Clips the organiser prepared ahead come back at once; others are cut when first searched. - The
request_idis deterministic for the event, the cleaned text and the clips that match it. A changed watermark or preview quality, a re-uploaded video, or a change in which videos match gives a newrequest_id(fresh clips) on the next search.
Example Request
Example Responses
- processing
- completed (clips exist)
- no_matches
no_matches means no video matched. Nothing is stored, so request_id is null and there is nothing to poll. The same text can match later, after the organiser renames a video or uploads more.
A name search shares its
request_id with everyone who types the same text, and the GET endpoint reads it only while the event is in video name search.GET /video-clipping/ — Read Stored Results
Returns the current stored status of the search and any generated clips. Safe to call repeatedly.Path Parameters
A selfie result needs
video_selfie_search on, and a bib result needs bib video search on; an event that offers only bib search can read its bib results. A video name result is served only while the event is in video name search; in that mode a selfie or bib result answers 404 “This search isn’t available for this event.”, and in any other mode a name result does too. Each clip of a name result carries name (the video’s search name); on selfie and bib results name is null.
Status Lifecycle
Example Request
Example Response
- completed
- processing
- no_matches
- no_segments
- clip_failed
- failed
start_time 00:00:00, segment_index 0 and name set, for example "name": "Rahul Sharma 1234".Recommended Integration Sequence — “POST once, GET many”
1
Confirm video clipping is enabled
Call Event Details. Offer selfie clips when
video_search and video_selfie_search are true, and bib clips when video_search and video_bib_search are true. If neither applies, do not show the video clipping CTA.2
POST once
Upload the selfie to
POST /video-clipping/search-by-selfie, send the bib to POST /video-clipping/search-by-bib, or (video name search events) send the typed text to POST /video-clipping/search-by-name. Persist the request_id from the response (URL state, local storage, or your DB).
If you already have a request_id from Face Search, send only that request_id (no file) to clip from the segments Face Search already computed. Repeating a bib or name POST is safe: it returns the same shared result.3
Read stored results
If the POST response is not terminal, or if the user refreshes the page, call
GET /video-clipping/{request_id} to read the stored status and clips.4
Render or fall back
On
completed, render the clips from videos[].video_url. Use videos[].download_url for downloads only when videos[].download_status is ready; it is paywalled when a purchase is required and disabled when the organiser turned off clip downloads.
On no_matches / no_segments, show a friendly empty state (the selfie or bib did not produce a clip).
On clip_failed / failed, surface a retry CTA — a fresh POST (with a new selfie) is the most reliable next step.Response Models
Error Responses
See Errors for canonical descriptions and retry guidance.

