장면 검색 결과 조회

Prev Next

VPC 환경에서 이용 가능합니다.

장면 검색 결과를 조회합니다.

참고
  • 장면 검색은 비동기로 처리되는 API이며, 장면 검색 요청 API 호출 후 발급된 searchId를 이용해 결과를 조회합니다.
  • status"COMPLETED" 상태인 경우에만 totalCountresults를 반환합니다.
  • 쿼리 스코어, 인덱스 생성 순으로 정렬됩니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드 URI
GET /api/v1/workspaces/{workspace_name}/scene-search/{searchId}

요청 헤더

Media AI Understanding API 에서 공통으로 사용하는 헤더에 대한 정보는 Media AI Understanding 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

필드 타입 필수 여부 설명
workspace_name String Required 워크스페이스 이름
searchId String Required 장면 검색 요청 시 발급된 검색 식별자

요청 쿼리 파라미터

필드 타입 필수 여부 설명
pageSize Integer Optional 페이지당 결과 개수
  • 기본값: 50
  • 허용 범위: 1 ~ 100
pageNum Integer Optional 조회할 페이지 번호
  • 기본값: 1

요청 예시

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}'

응답

응답 형식을 설명합니다.

응답 바디

필드 타입 필수 여부 설명
code String Required API 처리 결과 코드
message String Required API 처리 결과 메시지
result Object Required 장면 검색 결과 정보

result

필드 타입 필수 여부 설명
searchId String Required 장면 검색 요청 시 발급된 검색 식별자
status String Required 검색 상태 코드
  • RUNNING | COMPLETED | FAILED
    • RUNNING: 검색중
    • COMPLETED: 완료
    • FAILED: 실패
totalCount Integer Conditional 검색된 장면의 총 개수
  • statusCOMPLETED일 경우 포함
totalPage Integer Conditional 전체 페이지 수
  • statusCOMPLETED일 경우 포함
pageNo Integer Conditional 현재 페이지 번호
  • statusCOMPLETED일 경우 포함
pageSize Integer Conditional 페이지당 결과 개수
  • statusCOMPLETED일 경우 포함
content Array Conditional 씬 단위 검색 결과 목록
  • statusCOMPLETED일 경우 포함

result.content

필드 타입 필수 여부 설명
jobId Integer Required 검색 대상 인덱스(Job) ID
engine String Required 인덱스 엔진 버전
videoAssetId Integer Required 검색 대상 비디오 에셋 ID
videoAssetName String Optional 비디오 에셋명
scene Integer Required 검색된 장면 ID
score Number Optional 장면 유사도 스코어
startMs Number Optional 장면 시작 시간 (밀리초)
endMs Number Optional 장면 종료 시간 (밀리초)
videoUrl String Optional 비디오 재생 URL
  • (유효시간 1시간)
sceneThumbnailUrl String Optional 장면 썸네일 이미지 URL
  • (유효시간 1시간)
shots Array Optional 해당 장면에 포함된 샷 정보 목록

result.content.shots

필드 타입 필수 여부 설명
shot Integer Required 샷 ID
startMs Number Required 샷 시작 시간 (밀리초)
endMs Number Required 샷 종료 시간 (밀리초)
score Number Optional 샷 유사도 점수
persons Array Optional 샷에 등장하는 인물 목록
scripts Array Optional 샷에 포함된 대사 정보 목록
queryRef Array Optional 유저 쿼리와의 매칭 정보 목록

result.content.shots.persons

필드 타입 설명
personId Integer 인물 ID
name String 인물 이름
profileUrl String 인물 프로필 썸네일 URL
  • (유효시간 1시간)

result.content.shots.scripts

필드 타입 설명
startMs Number 대사 시작 시간 (밀리초)
endMs Number 대사 종료 시간 (밀리초)
text String 대사 텍스트
name String 발화자 이름
  • 익명일 경우 화자1, 화자2 등으로 노출
personId Integer 발화자 인물 ID
  • 익명일 경우 null

result.content.shots.queryRef

필드 타입 설명
queryType String 쿼리 타입
  • TEXT | IMAGE | PERSON | DIALOGUE
    • TEXT: 텍스트 검색 결과
    • IMAGE: 이미지 검색 결과
    • PERSON: 인물 검색 결과
    • DIALOGUE: 대사 검색 결과
conditionType String 쿼리 조건
  • MUST | ANY
matchedValues Array<String> 입력된 쿼리 중 해당 샷과 매칭된 값

응답 예시

{
  "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": "도시의 추격",
        "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": "유재석",
                "profileUrl": "https://kr.object.ncloudstorage.com/.../jiho0.jpg?X-Amz-..."
              }
            ],
            "scripts": [
              {
                "startMs": 121500,
                "endMs": 122000,
                "text": "이쪽이야, 어서!",
                "name": "화자1",
                "personId": null
              }
            ],
            "queryRef": [
              {
                "queryType": "TEXT",
                "conditionType": "MUST",
                "matchedValues": ["어두운 골목"]
              }
            ]
          },
          {
            "shot": 71,
            "startMs": 123000,
            "endMs": 125000,
            "score": 95.8,
            "persons": [
              {
                "personId": 1001,
                "name": "유재석",
                "profileUrl": "https://kr.object.ncloudstorage.com/.../jiho0.jpg?X-Amz-..."
              }
            ],
            "scripts": [
              {
                "startMs": 124000,
                "endMs": 124500,
                "text": "위험해, 숨어!",
                "name": "화자2",
                "personId": 1001
              }
            ],
            "queryRef": [
              {
                "queryType": "DIALOGUE",
                "conditionType": "ANY",
                "matchedValues": ["위험해"]
              }
            ]
          }
        ]
      }
    ]
  }
}