Video Clipping Search

Overview

Video Clipping Search is the API surface for 9Pic Motion, our selfie + BIB-driven video clipping pipeline. It finds the moments where a participant appears in the event’s videos and returns short playable clip URLs for those moments. 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 one clip per matched source video.
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.

Video Clipping Search must be enabled for the event. Both video_search (the event-level toggle) and video_selfie_search (the selfie-driven video toggle) returned by Event Details must be true.

Why Two Endpoints?

Producing a video clip is substantially more expensive than searching for photos: it has to scan every video frame index, run face matching, decide on the best time window per 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.
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. 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 /api/v1/ext/{org_id}/event/{event_id}/video-clipping/search-by-selfie
GET  /api/v1/ext/{org_id}/event/{event_id}/video-clipping/{request_id}

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

Parameter	Type	Required	Description
`org_id`	number	Yes	Your organisation ID.
`event_id`	number	Yes	The event to search within.

Multipart Form Fields

Field	Type	Required	Description
`file`	file	No	Selfie image (JPEG/PNG). The clearest single-face image gives best results. Optional — omit it and pass a `request_id` from a completed Face Search to reuse the segments already computed for that selfie.
`request_id`	string	No	UUID of the selfie record. Pass a Face Search `request_id` to reuse the same record. Required when no `file` is uploaded — sending it alone reuses the precomputed segments and starts clipping. If omitted (with a `file`), 9Pic generates one and returns it.
`force_recreate`	boolean	No	Set to `true` only when recreating clips for an existing `request_id`, for example after generated clips were deleted or expired. Defaults to `false`.

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

curl -i \
  -H "X-API-Key: <your_9pic_api_key>" \
  -F "file=@selfie.jpg" \
  "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/search-by-selfie"

import requests

with open("selfie.jpg", "rb") as f:
    response = requests.post(
        "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/search-by-selfie",
        headers={"X-API-Key": "<your_9pic_api_key>"},
        files={"file": ("selfie.jpg", f, "image/jpeg")},
    )

data = response.json()
print(data["data"]["request_id"], data["data"]["status"])

const formData = new FormData();
formData.append("file", selfieFile);

const response = await fetch(
  "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/search-by-selfie",
  {
    method: "POST",
    headers: { "X-API-Key": "<your_9pic_api_key>" },
    body: formData,
  }
);

const result = await response.json();
console.log(result.data.request_id, result.data.status);

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. 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:

curl -i \
  -H "X-API-Key: <your_9pic_api_key>" \
  -F "request_id=ddc661a7-8861-4793-9437-af42a82d12f8" \
  "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/search-by-selfie"

import requests

response = requests.post(
    "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/search-by-selfie",
    headers={"X-API-Key": "<your_9pic_api_key>"},
    data={"request_id": "ddc661a7-8861-4793-9437-af42a82d12f8"},
)
print(response.json()["data"]["status"])

const formData = new FormData();
formData.append("request_id", "ddc661a7-8861-4793-9437-af42a82d12f8");

const response = await fetch(
  "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/search-by-selfie",
  {
    method: "POST",
    headers: { "X-API-Key": "<your_9pic_api_key>" },
    body: formData,
  }
);
console.log((await response.json()).data.status);

Example Response

{
  "responseType": "success",
  "message": "Video clipping search started. Use GET /api/v1/ext/{org_id}/event/{event_id}/video-clipping/{request_id} to read the stored clip details.",
  "data": {
    "status": "processing",
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "progress_percentage": 0
  }
}

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.

GET /video-clipping/ — Read Stored Results

Returns the current stored status of the search and any generated clips. Safe to call repeatedly.

Path Parameters

Parameter	Type	Required	Description
`org_id`	number	Yes	Your organisation ID.
`event_id`	number	Yes	The event the search belongs to.
`request_id`	string	Yes	UUID returned by a previous `POST /video-clipping/search-by-selfie` call.

Status Lifecycle

Status	Terminal?	Meaning
`processing`	No	Clip generation has started, but at least one clip is still being prepared. `progress_percentage` carries the approximate overall progress when available.
`completed`	Yes	One or more clips were generated. `videos[]` is populated.
`no_matches`	Yes	The selfie did not match any frames in the event videos. No clips generated.
`no_segments`	Yes	The selfie matched frames, but the matches were too sparse or scattered to form a usable clip window.
`clip_failed`	Yes	The selfie matched and a window was selected, but the clipping service failed to produce one or more clips. `clip_errors[]` carries per-source detail.
`failed`	Yes	The job failed before any clips could be generated. `error` carries a human-readable message.

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

curl -i \
  -H "X-API-Key: <your_9pic_api_key>" \
  "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/ddc661a7-8861-4793-9437-af42a82d12f8"

import time
import requests

URL = "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/ddc661a7-8861-4793-9437-af42a82d12f8"
HEADERS = {"X-API-Key": "<your_9pic_api_key>"}

for delay in (3, 5, 10, 15):
    response = requests.get(URL, headers=HEADERS)
    payload = response.json()["data"]
    if payload["status"] != "processing":
        print(payload["status"], payload.get("videos", []))
        break
    time.sleep(delay)
else:
    while payload["status"] == "processing":
        time.sleep(15)
        payload = requests.get(URL, headers=HEADERS).json()["data"]
    print(payload["status"], payload.get("videos", []))

const url =
  "https://api.9pic.ai/api/v1/ext/903/event/456/video-clipping/ddc661a7-8861-4793-9437-af42a82d12f8";
const headers = { "X-API-Key": "<your_9pic_api_key>" };

const delays = [3000, 5000, 10000, 15000];
let payload;

for (const delay of delays) {
  payload = (await (await fetch(url, { headers })).json()).data;
  if (payload.status !== "processing") break;
  await new Promise((resolve) => setTimeout(resolve, delay));
}

while (payload.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 15000));
  payload = (await (await fetch(url, { headers })).json()).data;
}

console.log(payload.status, payload.videos);

Example Response

{
  "responseType": "success",
  "message": "Video clipping completed",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "completed",
    "videos": [
      {
        "uuid": "5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08",
        "video_url": "https://video-cdn.9pic.ai/clips/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08/manifest/video.m3u8",
        "download_url": "https://video-cdn.9pic.ai/clips/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08/downloads/default.mp4?filename=ddc661a7-8861-4793-9437-af42a82d12f8-source-12-event-456",
        "download_status": "ready",
        "stream_uid": "5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08",
        "thumbnail_url": "https://video-cdn.9pic.ai/clips/5e9a7cc1-0bcb-4a4d-b6e3-6c0b25c57a08/thumbnails/thumbnail.jpg",
        "expires_at": "2026-07-24T10:15:00Z",
        "ready_to_stream": true,
        "progress_percentage": 100,
        "source_video_key": "12",
        "start_time": "00:00:42",
        "end_time": "00:00:52"
      }
    ],
    "error": null,
    "clip_errors": []
  }
}

{
  "responseType": "success",
  "message": "Video clip search is still processing. Check again shortly.",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "processing",
    "progress_percentage": 42,
    "videos": [],
    "error": null,
    "clip_errors": []
  }
}

{
  "responseType": "success",
  "message": "No frames in the event videos matched the uploaded selfie.",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "no_matches",
    "videos": [],
    "error": null,
    "clip_errors": []
  }
}

{
  "responseType": "success",
  "message": "Matches were found but no continuous video segment could be extracted.",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "no_segments",
    "videos": [],
    "error": null,
    "clip_errors": [
      {
        "video_key": "12",
        "error": "no usable segment",
        "status_code": null
      }
    ]
  }
}

{
  "responseType": "success",
  "message": "Selfie matched but the video clipping service could not produce one or more clips.",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "clip_failed",
    "videos": [],
    "error": null,
    "clip_errors": [
      {
        "video_key": "34",
        "error": "Clipping service returned 500",
        "status_code": 500
      }
    ]
  }
}

{
  "responseType": "success",
  "message": "Video clip search failed before any clips could be generated.",
  "data": {
    "request_id": "ddc661a7-8861-4793-9437-af42a82d12f8",
    "status": "failed",
    "videos": [],
    "error": "Failed to start processing",
    "clip_errors": []
  }
}

Recommended Integration Sequence — “POST once, GET many”

Confirm video clipping is enabled

Call Event Details and check that both video_search and video_selfie_search are true. If either is false, do not show the video clipping CTA.

POST once

Upload the selfie to POST /video-clipping/search-by-selfie. 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.

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.

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. On no_matches / no_segments, show a friendly empty state (the selfie 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

Model	Description
VideoClippingStartResponse	Returned by `POST /video-clipping/search-by-selfie`.
VideoClippingResultResponse	Returned by `GET /video-clipping/{request_id}`.
VideoClipItem	Each entry inside `videos[]`.
VideoClipErrorItem	Each entry inside `clip_errors[]`.

Error Responses

Status	Meaning
`400`	`request_id` is not a valid UUID; the uploaded selfie file is empty; neither a `file` nor a `request_id` was provided; or a `request_id` was sent with no file but has no precomputed segments (run Face Search first).
`401`	API key is missing.
`403`	API key is invalid, inactive, token/event ownership mismatch, or video clipping (event-level or selfie-driven) is disabled for this event.
`404`	Event configuration not found, video search configuration not found, or `request_id` is unknown (on GET, or on the file-less reuse POST).
`429`	Rate limit exceeded. Back off and retry with the same `request_id` to hit the cache.
`500`	Internal failure that prevented video clipping from starting or completing. The selfie record is marked `failed`; a fresh `POST` is the safest retry after configuration is fixed.

See Errors for canonical descriptions and retry guidance.

Get Started

Events

Memories

Browse Photos

Search

Video

Downloads

Pipeline

Models

Overview

Why Two Endpoints?

Endpoints

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

Path Parameters

Multipart Form Fields

Example Request

Example Response

GET /video-clipping/ — Read Stored Results

Path Parameters

Status Lifecycle

Example Request

Example Response

Recommended Integration Sequence — “POST once, GET many”

Response Models

Error Responses

​Overview

​Why Two Endpoints?

​Endpoints

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

​Path Parameters

​Multipart Form Fields

​Example Request

​Example Response

​GET /video-clipping/ — Read Stored Results

​Path Parameters

​Status Lifecycle

​Example Request

​Example Response

​Recommended Integration Sequence — “POST once, GET many”

​Response Models

​Error Responses

Overview

Why Two Endpoints?

Endpoints

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

Path Parameters

Multipart Form Fields

Example Request

Example Response

GET /video-clipping/ — Read Stored Results

Path Parameters

Status Lifecycle

Example Request

Example Response

Recommended Integration Sequence — “POST once, GET many”

Response Models

Error Responses