장면 검색 요청

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

텍스트, 이미지, 인물, 대사 조건을 이용하여 장면을 검색합니다.

참고

장면 검색 요청 API 는 비동기 API 이며, 장면 검색 결과 조회 API 를 통해 확인할 수 있습니다.
쿼리는 1개만 입력 가능하며, textQuery 또는 imageQuery 중 하나만 사용해야 합니다.
필터는 인물(persons) 및 대사(dialogues) 기준으로 must/any/not 조건을 설정할 수 있습니다.

요청

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

메서드	URI
POST	/api/v1/scene-search

요청 헤더

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

요청 바디

요청 바디는 query, queryOption, filter의 세 개 객체로 구성됩니다.

필드	타입	필수 여부	설명
`query`	Object	Required	장면 검색 조건 (텍스트, 이미지, 인물, 대사)
`queryOption`	Object	Optional	유사도 신뢰 수준 설정
`filter`	Object	Optional	검색 대상 프로젝트, 비디오, 인덱스 수정일 필터

query

필드	타입	필수 여부	설명
`textQuery`	String	Conditional	장면에 대한 텍스트 쿼리 `textQuery` 또는 `imageQuery` 중 하나는 필수 세미콜론(`;`), 버티컬바(`\|`), 백틱(`) 사용 불가
`imageQuery`	String	Conditional	업로드 완료한 이미지 파일의 키값 `textQuery` 또는 `imageQuery` 중 하나는 필수
`personQuery`	Object	Optional	장면 내 포함되거나 제외할 인물 조건
`personQuery.must`	Array<Integer>	Optional	반드시 포함해야 할 인물 ID 목록
`personQuery.any`	Array<Integer>	Optional	하나 이상 포함되어야 할 인물 ID 목록
`personQuery.not`	Array<Integer>	Optional	포함되지 않아야 할 인물 ID 목록
`dialogQuery`	Object	Optional	장면 내 포함되거나 제외할 대사 조건 세미콜론(`;`), 버티컬바(`\|`), 백틱(`) 사용 불가
`dialogQuery.must`	Array<String>	Optional	반드시 포함해야 할 대사 목록
`dialogQuery.any`	Array<String>	Optional	하나 이상 포함되어야 할 대사 목록
`dialogQuery.not`	Array<String>	Optional	포함되지 않아야 할 대사 목록

queryOption

필드	타입	필수 여부	설명
`confidenceLevel`	String	Optional	유사도 신뢰 수준 `LOW` \| `MEDIUM`(기본값) \| `HIGH`

filter

필드	타입	필수 여부	설명
`projectIds`	Array<Integer>	Conditional	검색할 프로젝트 ID 목록 `projectIds` 또는 `videoAssetIds` 중 하나는 필수
`videoAssetIds`	Array<Integer>	Conditional	검색할 비디오 에셋 ID 목록 `projectIds` 또는 `videoAssetIds` 중 하나는 필수
`indexModifiedFrom`	String	Optional	인덱스 수정 시작일시 ISO 8601 형식
`indexModifiedTo`	String	Optional	인덱스 수정 종료일시 ISO 8601 형식

요청 예시

{
  "query": {
    "textQuery": "어두운 골목",
    "imageQuery": null,
    "personQuery": {
      "must": [101, 102],
      "any": [103],
      "not": [104]
    },
    "dialogQuery": {
      "must": ["도망쳐"],
      "any": ["위험해"],
      "not": ["조용히 해"]
    }
  },
  "queryOption": {
    "confidenceLevel": "MEDIUM"
  },
  "filter": {
    "projectIds": [201],
    "indexModifiedFrom": "2025-08-01T00:00:00Z",
    "indexModifiedTo": "2025-08-07T23:59:59Z"
  }
}

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`code`	String	Required	API 처리 결과 코드
`message`	String	Required	API 처리 결과 메시지
`result`	Object	Required	검색 요청 결과 정보
`result.searchId`	String	Required	생성된 장면 검색 식별자 장면 검색 결과 조회 API에서 사용

응답 예시

응답 예시는 다음과 같습니다.

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

참고

호출 제한: API는 분당 1,000건까지 호출할 수 있습니다.
문의: 호출량 조정이 필요한 경우 고객지원으로 문의해 주십시오.