Search for a video using text or media query

POST

/search

• Kubrick API

Request Body ^required

object

query_type

required

Specifies the input modality for the search query: text, image, video, or audio. Supported audio formats: WAV (uncompressed), MP3 (lossy), FLAC (lossless).

string

Allowed values: text image video audio

query_text

Text query used when query_type is set to “text”.

string

query_media_url

URL of the media file to use for search when using image, video, or audio queries.

string format: url

query_media_file

Upload a media file (image, video, or audio) for search.

string format: binary

query_modality

Specifies the semantic modality of the query.

• “visual-text”: Search based on visual captions or scene descriptions.
• “audio”: Search based on audio features or speech.

string

Allowed values: visual-text audio

filter

Optional JSON string to filter search results.

string

Example

{
  "scope": [
    "video",
    "clip"
  ],
  "modality": [
    "visual-text",
    "audio"
  ]
}

min_similarity

Minimum similarity threshold (0–1) required to include a result in the response.

number

limit

Maximum number of results to return per page.

integer

Responses

200

Video search results have been successfully returned.

object

data

Array<object>

object

id

integer

Example

1197

modality

string

Allowed values: visual-text audio

scope

string

Allowed values: video clip

start_time

number

Example

54

end_time

number

Example

60

similarity

number

Example

0.95

video

Represents a video stored in the Kubrick video library, including its metadata and accessible URL. Videos can be searched, retrieved, and linked to processing tasks.

object

id

integer

Example

14

s3_bucket

string

Example

kubrick-video-library-09885bf7f493aa87

s3_key

string

Example

uploads/34a23d0b-3c70-4bda-b068-038b7e6944e1/example.mp4

filename

string

Example

example.mp4

duration

number

Example

155.82912

created_at

string

Example

2025-08-05T20:00:58.336478

updated_at

string

Example

2025-08-05T20:00:58.336478

height

integer

nullable

width

integer

nullable

url

string format: url

Example

https://kubrick-video-library.s3.ap-southeast-2.amazonaws.com/uploads/abc123/example.mp4

metadata

Pagination information.

object

page

integer

0

limit

integer

Example

10

total

integer

Example

10

400

Bad Request — Invalid search parameters or file upload.

Error response object.

object

error

object

code

string

Example

INVALID_REQUEST

message

string

Example

Missing query parameters

500

Internal Server Error — Search request failed.

Error response object.

object

message

string

Example

Internal Server Error