Get scene search result

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

Get the scene search result.

Note

Scene search is an asynchronous API, and results are retrieved using the searchId issued after calling the Request scene search API.
totalCount and results are returned only if status is in the "COMPLETED" status.
It is sorted by query score, followed by index creation.

Request

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

Method	URI
GET	/api/v1/workspaces/{workspace_name}/scene-search/{searchId}

Request headers

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

Request path parameters

Field	Type	Required	Description
`workspace_name`	String	Required	Workspace name
`searchId`	String	Required	Search identifier issued when requesting scene search

Request query parameters

Field	Type	Required	Description
`pageSize`	Integer	Optional	Number of results per page Default: 50 Allowed range: 1-100
`pageNum`	Integer	Optional	Page number to query Default: 1

Request example

curl --location --request GET 'https://maiu.apigw.ntruss.com/api/v1/workspaces/betatest/scene-search/JtWJKTDCKknMHP8Id4Gt?pageSize=50&pageNum=1' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'

Response

This section describes the response format.

Response body

Field	Type	Required	Description
`code`	String	Required	API processing result code
`message`	String	Required	API processing result message
`result`	Object	Required	Scene search result information

result

Field	Type	Required	Description
`searchId`	String	Required	Search identifier issued when requesting scene search
`status`	String	Required	Search status code `RUNNING` \| `COMPLETED` \| `FAILED` `RUNNING`: Searching `COMPLETED`: Completed `FAILED`: Failed
`totalCount`	Integer	Conditional	Total number of scenes searched Included if `status` is `COMPLETED`
`totalPage`	Integer	Conditional	Total page count Included if `status` is `COMPLETED`
`pageNo`	Integer	Conditional	Current page number Included if `status` is `COMPLETED`
`pageSize`	Integer	Conditional	Number of results per page Included if `status` is `COMPLETED`
`content`	Array	Conditional	Scene-level search result list Included if `status` is `COMPLETED`

result.content

Field	Type	Required	Description
`jobId`	Integer	Required	Search target index (job) ID
`engine`	String	Required	Index engine version
`videoAssetId`	Integer	Required	Search target video asset ID
`videoAssetName`	String	Optional	Video asset name
`scene`	Integer	Required	Searched scene ID
`score`	Number	Optional	Scene similarity score
`startMs`	Number	Optional	Scene start time (millisecond)
`endMs`	Number	Optional	Scene end time (millisecond)
`videoUrl`	String	Optional	Video playback URL (Valid for 1 hour)
`sceneThumbnailUrl`	String	Optional	Scene thumbnail image URL (Valid for 1 hour)
`shots`	Array	Optional	List of shot information included in the scene

result.content.shots

Field	Type	Required	Description
`shot`	Integer	Required	Shot ID
`startMs`	Number	Required	Shot start time (millisecond)
`endMs`	Number	Required	Shot end time (millisecond)
`score`	Number	Optional	Shot similarity score
`persons`	Array	Optional	List of people in the shot
`scripts`	Array	Optional	List of dialogues included in the shot
`queryRef`	Array	Optional	List of matching information with user query

result.content.shots.persons

Field	Type	Description
`personId`	Integer	Person ID
`name`	String	Person name
`profileUrl`	String	Person thumbnail image URL (Valid for 1 hour)

result.content.shots.scripts

Field	Type	Description
`startMs`	Number	Dialogue start time (millisecond)
`endMs`	Number	Dialogue end time (millisecond)
`text`	String	Dialogue text
`name`	String	Speaker name If anonymous, displayed as `Speaker 1`, `Speaker 2`, etc.
`personId`	Integer	Speaker person ID Null if anonymous

result.content.shots.queryRef

Field	Type	Description
`queryType`	String	Query type `TEXT` \| `IMAGE` \| `PERSON` \| `DIALOGUE` `TEXT`: Text search result `IMAGE`: Image search result `PERSON`: Person search result `DIALOGUE`: Dialogue search result
`conditionType`	String	Query condition `MUST` \| `ANY`
`matchedValues`	Array<String>	Matching values of the entered query with the corresponding shot

Response example

{
  "code": "0",
  "message": "success",
  "result": {
    "searchId": "JtWJKTDCKknMHP8Id4Gt",
    "status": "COMPLETED",
    "totalCount": 1,
    "totalPage": 1,
    "pageNo": 1,
    "pageSize": 50,
    "content": [
      {
        "jobId": 12345,
        "engine": "v2.1.0",
        "videoAssetId": 67890,
        "videoAssetName": "Urban chase",
        "scene": 7,
        "score": 98.3,
        "startMs": 120000,
        "endMs": 135000,
        "videoUrl": "https://kr.object.ncloudstorage.com/.../12345/video.mp4?X-Amz-...",
        "sceneThumbnailUrl": "https://kr.object.ncloudstorage.com/.../12345/7.jpg?X-Amz-...",
        "shots": [
          {
            "shot": 70,
            "startMs": 121000,
            "endMs": 123000,
            "score": 98.3,
            "persons": [
              {
                "personId": 1001,
                "name": "Jae-suk Yoo",
                "profileUrl": "https://kr.object.ncloudstorage.com/.../jiho0.jpg?X-Amz-..."
              }
            ],
            "scripts": [
              {
                "startMs": 121500,
                "endMs": 122000,
                "text": "This way, come on!",
                "name": "Speaker 1",
                "personId": null
              }
            ],
            "queryRef": [
              {
                "queryType": "TEXT",
                "conditionType": "MUST",
                "matchedValues": ["Dark alley"]
              }
            ]
          },
          {
            "shot": 71,
            "startMs": 123000,
            "endMs": 125000,
            "score": 95.8,
            "persons": [
              {
                "personId": 1001,
                "name": "Jae-suk Yoo",
                "profileUrl": "https://kr.object.ncloudstorage.com/.../jiho0.jpg?X-Amz-..."
              }
            ],
            "scripts": [
              {
                "startMs": 124000,
                "endMs": 124500,
                "text": "Danger, hide!",
                "name": "Speaker 2",
                "personId": 1001
              }
            ],
            "queryRef": [
              {
                "queryType": "DIALOGUE",
                "conditionType": "ANY",
                "matchedValues": ["Danger"]
              }
            ]
          }
        ]
      }
    ]
  }
}