Request scene search

The latest service changes have not yet been reflected in this content. We will update the content as soon as possible. Please refer to the Korean version for information on the latest updates.

Available in VPC

Search a scene using text, image, person, or dialogue criteria.

Note

The Request scene search API is an asynchronous API and can be checked via the Get scene search result API.
You can only enter one query, and you must use either textQuery or imageQuery.
Filters can set to must/any/not conditions based on persons and dialogues.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/api/v1/scene-search

Request headers

For information about the headers common to all Media Intelligence APIs, see Media Intelligence request headers.

Request body

The request body consists of three objects: query, queryOption, and filter.

Field	Type	Required	Description
`query`	Object	Required	Scene search condition (text, image, person, dialogue)
`queryOption`	Object	Optional	Similarity confidence level settings
`filter`	Object	Optional	Search target project, video, and index modification date filters

query

Field	Type	Required	Description
`textQuery`	String	Conditional	Text query for the scene One of `textQuery` or `imageQuery` is required. Semicolons (`;`), vertical bars (`\\|`), and backticks (`) can't be used.
`imageQuery`	String	Conditional	Key value of the uploaded image file One of `textQuery` or `imageQuery` is required.
`personQuery`	Object	Optional	Person criteria for inclusion or exclusion in the scene
`personQuery.must`	Array<Integer>	Optional	List of person IDs that must be included
`personQuery.any`	Array<Integer>	Optional	List of person IDs that must be included at least one
`personQuery.not`	Array<Integer>	Optional	List of person IDs that should not be included
`dialogQuery`	Object	Optional	Conditions for dialogues to be included or excluded from the scene Semicolons (`;`), vertical bars (`\\|`), and backticks (`) can't be used.
`dialogQuery.must`	Array<String>	Optional	List of dialogues that must be included
`dialogQuery.any`	Array<String>	Optional	List of dialogues that must be included at least one
`dialogQuery.not`	Array<String>	Optional	List of dialogues that should not be included

queryOption

Field	Type	Required	Description
`confidenceLevel`	String	Optional	Similarity confidence level `LOW` \| `MEDIUM` (default) \| `HIGH`

filter

Field	Type	Required	Description
`projectIds`	Array<Integer>	Conditional	List of project IDs to search One of `projectIds` or `videoAssetIds` is required.
`videoAssetIds`	Array<Integer>	Conditional	List of video asset IDs to search One of `projectIds` or `videoAssetIds` is required.
`indexModifiedFrom`	String	Optional	Index modification start date and time ISO 8601 format
`indexModifiedTo`	String	Optional	Index modification end date and time ISO 8601 format

Request example

{
  "query": {
    "textQuery": "Dark alley",
    "imageQuery": null,
    "personQuery": {
      "must": [101, 102],
      "any": [103],
      "not": [104]
    },
    "dialogQuery": {
      "must": ["Run"],
      "any": ["Danger"],
      "not": ["Be quiet"]
    }
  },
  "queryOption": {
    "confidenceLevel": "MEDIUM"
  },
  "filter": {
    "projectIds": [201],
    "indexModifiedFrom": "2025-08-01T00:00:00Z",
    "indexModifiedTo": "2025-08-07T23:59:59Z"
  }
}

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`code`	String	Required	API processing result code
`message`	String	Required	API processing result message
`result`	Object	Required	Search request result information
`result.searchId`	String	Required	Created scene search identifier Use in Get scene search result API.

Response example

The response example is as follows:

{
  "code": "0",
  "message": "success",
  "result": {
    "searchId": "JtWJKTDCKknMHP8Id4Gt"
  }
}

Note

Call limit: The API can be called up to 1000 times per minute.
Inquiry: If you need to adjust call volume, contact Support.