---
title: "Request asset search"
slug: "maiu-search-asset"
updated: 2026-09-17T10:12:40Z
published: 2026-09-17T10:12:40Z
canonical: "api.ncloud-docs.com/maiu-search-asset"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/en/maiu-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](https://www.ncloud.com/support/question/service?parentCode=O2O_MEDIA&code=O2O_MEDIA_012).

## 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](/docs/en/maiu-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### 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) |
| `queryOption` | Object | Optional | Similarity confidence level settings |
| `filter` | Object | Optional | Search target project, video, and index modification date filters |

#### `query`

The following describes `query`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `textQuery` | String | Conditional | Text query for the media asset - Either `textQuery` or `imageQuery` is required. - Semicolons (`;`), vertical bars (`\\|`), and backticks (```) can't be used. |
| `imageQuery` | String | Conditional | Key value of the uploaded image file - Either `textQuery` or `imageQuery` is required. |
| `personQuery` | Object | Optional | Person criteria for inclusion or exclusion in the media asset |
| `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 video - Semicolons (`;`), vertical bars (`\\|`), and backticks (```) can't be used. - Image assets are displayed as 0. |
| `dialogQuery.must` | Array<String> | Optional | List of dialogues that must be included in the video - Image assets are displayed as 0. |
| `dialogQuery.any` | Array<String> | Optional | List of dialogues that must be included at least once in the video - Image assets are displayed as 0. |
| `dialogQuery.not` | Array<String> | Optional | List of dialogues that should not be included in the video - Image assets are displayed as 0. |

#### `queryOption`

The following describes `queryOption`.

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

#### `filter`

The following describes `filter`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `projectIds` | Array<Integer> | Conditional | List of project IDs to search - Either `projectIds` or `assetIds` is required. |
| `assetIds` | Array<Integer> | Conditional | List of media asset IDs to search - Either `projectIds` or `assetIds` is required. |
| `assetTypes` | Array<enum> | Optional | Asset type to search (if not specified, search all asset types) - `IMAGE` \| `VIDEO` - `IMAGE`: Image - `VIDEO`: Video |
| `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

The request example is as follows:

```
{
    "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](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) |
| `message` | String | - | [API processing result message](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) |
| `result` | Object | - | Search request result information |
| `result.searchId` | String | - | Created asset search identifier - Use in [Get asset search result API](/docs/en/maiu-get-asset-search-result). |

### Response example

The response example is as follows:

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