---
title: "Search from Private Library"
method: POST
path: "/serve/api/v1/search"
---

# Search from Private Library

`POST /serve/api/v1/search`

## Request body

- SearchPrivateRequest
  - `search_param` string, required — Natural-language search query. Must be non-empty.
  - `search_type` 'BY_VIDEO' | 'BY_CLIP' | 'BY_AUDIO' | 'BY_IMAGE' | 'BY_CAPTION' — Search modality. BY_VIDEO is treated as BY_CLIP internally. BY_CAPTION performs vector search over the video_transcript table and returns a different item shape (see response).
  - `top_k` integer — Maximum number of results to return. Range 1-1000 for BY_CLIP/BY_AUDIO/BY_IMAGE. For BY_CAPTION the range is 1-200 (server-side default is 10 when null).
  - `filtering_level` 'low' | 'medium' | 'high' — Similarity-score filter. low=0.15, medium=0.225, high=0.4.
  - `video_nos` string[] — Optional list of video numbers to restrict the search to. Max 100.
  - `tag` string — Optional tag filter.
  - `camera_tag` string — Optional camera/device model filter. Matches the camera_model supplied at upload time.
  - `datetime_taken` string — Optional capture-time filter in format yyyy-MM-dd HH:mm:ss.
  - `latitude` number, double — Optional latitude filter. Must be supplied together with longitude.
  - `longitude` number, double — Optional longitude filter. Must be supplied together with latitude.
  - `folder_id` integer — Optional. Restrict results to a single folder. Omit to query across your entire account. -1 is the Default folder; a positive id must belong to your account.

## Response `200`

Successful response

- SearchPrivateResponse — Response shape depends on search_type. For BY_CLIP / BY_VIDEO / BY_AUDIO `data` is an array of video-search items (carries video_bucket/video_blob and, for BY_CLIP, keyframe_bucket/keyframe_blob); for BY_IMAGE `data` is a paginated image-search object (items carry bucket/blob); for BY_CAPTION `data` is an array of caption-search items carrying the embedding vector, text, user_id, and time range.
  - `code` string
  - `msg` string
  - `data` union
    - object[]
      - `videoNo` string
      - `videoName` string
      - `startTime` string — Matched segment start time in seconds.
      - `endTime` string — Matched segment end time in seconds.
      - `audio_ts` string — Matched audio transcript (BY_AUDIO).
      - `score` number, double
      - `video_bucket` string — GCS bucket of the original video file. Omitted when the storage location cannot be resolved.
      - `video_blob` string — GCS blob path of the original video. Use with video_bucket at GET /serve/api/v2/download to fetch the file directly.
      - `keyframe_bucket` string — GCS bucket of the matched keyframe image (BY_CLIP only).
      - `keyframe_blob` string — GCS blob path of the matched keyframe image.
    - object
      - `current_page` integer
      - `page_size` integer
      - `total_count` integer
      - `item` object[]
        - `id` integer
        - `name` string
        - `img_url` string
        - `datetime_taken` integer
        - `camera_model` string
        - `latitude` number, double
        - `longitude` number, double
        - `score` number, double
        - `bucket` string — GCS bucket of the image.
        - `blob` string — GCS blob path of the image. Use with bucket at GET /serve/api/v2/download to fetch the file directly.
    - object[] — BY_CAPTION response items.
      - `video_no` string
      - `text` string — Matched caption segment text.
      - `vector` number[] — Stored embedding vector of the matched caption row. Dimensionality depends on the embedding model.
      - `user_id` string — Internal MD5-encoded user namespace identifier.
      - `start_time` number, double — Caption start time in seconds.
      - `end_time` number, double — Caption end time in seconds.
      - `score` number, double — Similarity score (1 - distance).
  - `success` boolean
  - `failed` boolean

---

[API](https://skmtc.net/memories/apis/screenplay-extraction-api.md) · [All operations](https://skmtc.net/memories/apis/screenplay-extraction-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/memories/screenplay-extraction-api/versions/720c8c144ddc/schema)