Skip to main content

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.
Building a participant-facing gallery or search app? Follow the Participant App guide (coding agents get it in the 9pic-integration skill): call the API only from your backend, save each search ID, check Event Details first, keep one search identifier per search, and show previews rather than originals.
For a selfie search, the participant uploads a selfie (or reuses a Face Search request_id) and the API:
  1. Matches the selfie against faces detected across the event’s source videos.
  2. Groups matched frames into continuous time segments.
  3. 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.
  4. Returns playable clip URLs you can hand to your UI.
The 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 Search request_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.
This lets your client trigger the expensive operation once, then read the stored result without re-uploading the selfie or re-sending the bib. The request_id follows the same idempotency model as Face Search — see Conventions.
Reuse a request_id returned by Face Search when you start a video clipping search. The same selfie record is updated, so the user gets photo and video results from a single upload.

Endpoints

POST /video-clipping/search-by-selfie — Start a Search

Accepts either a selfie image or a Face Search request_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

To reuse an existing 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

On a successful POST, 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 the request_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 (status completed on the POST); otherwise the first search for a bib takes about a minute.
  • The request_id is 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 new request_id (fresh clips) on the next search.

Example Request

Example Responses

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 the request_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 sharma and 1234 both find RAHUL_SHARMA_1234.mp4; rah and sharma rahul find 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_index 0). 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_id is 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 new request_id (fresh clips) on the next search.

Example Request

Example Responses

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

Treat POST as the start step. Use the GET endpoint to poll while status is processing and to recover stored results after refreshes or retries.

Example Request

Example Response

For a video name search each clip is the whole video, with start_time 00:00:00, segment_index 0 and name set, for example "name": "Rahul Sharma 1234".
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.
A new POST (with a fresh request_id or no request_id) re-runs the full pipeline and is treated as a new billable search. Avoid issuing fresh POSTs on every refresh — use GET to recover stored results.

Response Models

Error Responses

See Errors for canonical descriptions and retry guidance.