Request asset search

Available in VPC

Search assets using text, image, person, or dialogue criteria.

Note

Request asset search is processed asynchronously and can be checked via the Get asset search result.
You can only enter one query, and you must use either textQuery or imageQuery.
Filters can be set to must/any/not conditions based on persons and dialogues.
Up to 1000 calls can be made per minute. If you need to adjust the call volume, contact Support.

Request

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

Method	URI
POST	/api/v1/workspaces/{workspace_name}/assets/search

Request headers

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

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`query`	Object	Required	Media asset search condition (text, image, person, dialogue)
`query.textQuery`	String	Conditional	Text query for the media asset Either `textQuery` or `imageQuery` is required. Semicolons (`;`), vertical bars (`\|`), and backticks (`) can't be used.
`query.imageQuery`	String	Conditional	Key value of the uploaded image file Either `textQuery` or `imageQuery` is required.
`query.personQuery`	Object	Optional	Person criteria for inclusion or exclusion in the media asset
`query.personQuery.must`	Array[Integer]	Optional	List of person IDs that must be included
`query.personQuery.any`	Array[Integer]	Optional	List of person IDs that must be included at least one
`query.personQuery.not`	Array[Integer]	Optional	List of person IDs that should not be included
`query.dialogQuery`	Object	Optional	Conditions for dialogues to be included or excluded from the video Semicolons (`;`), vertical bars (`\|`), and backticks (`) can't be used. Image assets are displayed as 0.
`query.dialogQuery.must`	Array[String]	Optional	List of dialogues that must be included in the video Image assets are displayed as 0.
`query.dialogQuery.any`	Array[String]	Optional	List of dialogues that must be included at least once in the video Image assets are displayed as 0.
`query.dialogQuery.not`	Array[String]	Optional	List of dialogues that should not be included in the video Image assets are displayed as 0.
`queryOption`	Object	Optional	Similarity confidence level settings
`queryOption.confidenceLevel`	String	Optional	Similarity confidence level `LOW` \| `MEDIUM` (default) \| `HIGH`
`filter`	Object	Optional	Search target project, video, and index modification date filters
`filter.projectIds`	Array[Integer]	Conditional	List of project IDs to search Either `projectIds` or `assetIds` is required.
`filter.assetIds`	Array[Integer]	Conditional	List of media asset IDs to search Either `projectIds` or `assetIds` is required.
`filter.asseTypes`	Array[enum]	Optional	Asset type to search (if not specified, search all asset types) `IMAGE` \| `VIDEO` `IMAGE`: Image `VIDEO`: Video
`filter.indexModifiedFrom`	String	Optional	Index modification start date and time ISO 8601 format
`filter.indexModifiedTo`	String	Optional	Index modification end date and time ISO 8601 format

Request example

The request example is as follows:

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/{workspace_name}/assets/search' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "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	-	API processing result code
`message`	String	-	API processing result message
`result`	Object	-	Search request result information
`result.searchId`	String	-	Created asset search identifier Use in Get asset search result API.

Response example

The response example is as follows:

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