Media AI Understanding 개요

Prev Next

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

Media AI Understanding 서비스는 기존에 수동으로 작업하던 영상 분석을 자동화한 네이버 클라우드 플랫폼의 미디어 AI 분석 솔루션입니다. Media AI Understanding 서비스에서는 프로젝트 관리, 비디오 에셋 관리 및 분석, 인덱스 관리에 대한 API를 RETSTful 형태로 제공합니다.

Media AI Understanding 공통 설정

Media AI Understanding API에서 공통으로 사용하는 요청 형식과 응답 형식을 설명합니다.

요청

공통 요청 형식을 설명합니다.

API URL

요청 API URL은 다음과 같습니다.

https://maiu.apigw.ntruss.com

요청 헤더

요청 헤더에 대한 설명은 다음과 같습니다.

필드 필수 여부 설명
x-ncp-apigw-timestamp Required 1970년 1월 1일 00:00:00 협정 세계시(UTC)부터의 경과 시간(밀리초)
  • API Gateway 서버와 5분 이상 시간차 발생 시 유효하지 않은 요청으로 간주
    		•
    x-ncp-iam-access-key Required 네이버 클라우드 플랫폼에서 발급받은 Access Key
  • Access Key 발급 및 확인: 인증키 생성 참조
  • 서브 계정의 Access Key 발급 및 확인: 서브 계정 생성 참조
    		•
    x-ncp-apigw-signature-v2 Required 네이버 클라우드 플랫폼에서 발급받은 Access Key에 맵핑되는 Secret Key 및 HMAC 암호화 알고리즘(HmacSHA256)으로 요청 정보를 암호화한 후 Base64로 인코딩한 서명
  • Secret Key 발급 및 확인: 인증키 생성 참조
  • 서명 생성: 시그니처 생성 참조
    		•
    Content-type Required 요청 데이터의 형식
  • application/json
    		•

    응답

    공통 응답 형식을 설명합니다.

    응답 바디

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

    responseError
    responseError는 API 호출 실패 정보를 정의합니다. responseError에 대한 설명은 다음과 같습니다.

    필드 타입 필수 여부 설명
    code String Required 오류 코드
    message String Required 오류 메시지

    응답 상태 코드

    응답 상태 코드에 대한 설명은 다음과 같습니다.

    응답 상태 코드

    응답 상태 코드에 대한 설명은 다음과 같습니다.

    HTTP 상태 코드 코드 메시지 설명
    200 0 success 요청 처리 성공
    400 10001 Invalid Request. 요청 파라미터 오류
    400 10014 Select the video you want to analyze. 분석할 비디오가 없음
    400 10016 Select the bucket to integrate (folder selection not available). 폴더 항목은 등록할 수 없음
    400 10023 You can request up to 10 videos at a time. 등록 가능한 비디오 수를 초과함 (최대 10개)
    400 10027 The base project name can't be changed. 기본 프로젝트 이름은 변경할 수 없음
    400 10033 The base project can't be deleted. 기본 프로젝트는 삭제할 수 없음
    400 10041 The bucket integration is invalid. Check the bucket information again in the NAVER Cloud Platform console. 버킷 정보가 유효하지 않음 (콘솔에서 확인 필요)
    400 10046 Failed to set object storage ACL. Object Storage ACL 설정 실패
    400 10048 Check the linked Object Storage settings Object Storage 파일이 존재하지 않음
    400 50003 Analyze result not exists. 분석 결과가 존재하지 않음
    400 50010 Either projectIds or videoAssetIds should be provided, not both. projectIds 또는 videoAssetIds 중 하나만 제공해야 함
    400 50011 Either imageQuery or textQuery should be provided, not both. imageQuery 또는 textQuery 중 하나만 제공해야 함
    400 50012 Person query limit reached. You can only pass a maximum of 100 personIds at a time. 인물 ID는 한 번에 최대 100개까지만 전송 가능
    400 50013 Script query limit reached. You can only pass a maximum of 100 scripts at a time. 대사는 한 번에 최대 100개까지만 전송 가능
    400 10069 Please upload a large, clear image of your face, looking straight ahead. 정면을 바라보는 고해상도 얼굴 이미지를 업로드하세요
    400 10072 Invalid file format. 잘못된 파일 형식
    400 10073 Image crop error. 이미지 자르기 오류
    400 10074 Image cover upload failed. 이미지 커버 업로드 실패
    400 10075 Representative thumbnail not exist. 대표 썸네일이 존재하지 않음
    400 10077 Can not delete all thumbnails. 모든 썸네일을 삭제할 수 없음
    401 10003 Failed to check permissions. 권한 확인 실패
    404 10010 The video file does not exist. 영상 파일이 존재하지 않음
    404 10025 The project does not exist. 프로젝트가 존재하지 않음
    404 10030 The workspace does not exist. 워크스페이스가 존재하지 않음
    404 10038 Unanalyzed videos can't be canceled. 분석되지 않은 영상은 취소할 수 없음
    404 40002 The video analysis job does not exist. 영상 분석 작업이 존재하지 않음
    409 10026 This project name already exists. 프로젝트 이름이 이미 존재함
    409 10045 Can create up to 1,000 items per workspace. 워크스페이스당 최대 생성 가능 개수(1,000개)를 초과함
    409 10049 The project name exceeds the maximum length(100). 프로젝트 이름이 최대 길이(100자)를 초과함
    409 20012 Exist Workspace Name. 동일한 워크스페이스 이름이 존재함
    409 10062 Tag already registered. 태그가 이미 등록됨
    409 10068 You can register up to 500 items. 최대 등록 개수(500개)를 초과함
    409 10076 Primary thumbnail exceeded the limit. 대표 썸네일 최대 개수를 초과함
    409 50005 The name is already in use. Please enter a different name. 이름이 이미 사용 중입니다. 다른 이름을 입력하세요
    422 10017 Analyzing video. 영상 분석 중
    422 10072 Invalid file format. 잘못된 파일 형식
    500 99999 An error has occurred. 내부 서버 오류
    참고

    네이버 클라우드 플랫폼에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Ncloud API 응답 상태 코드를 참조해 주십시오.

    응답 예시

    호출이 성공한 경우의 응답 예시는 각 API 명세에서 확인해 주십시오. 호출이 실패한 경우의 응답 예시는 다음과 같습니다.

    {
    "code": "10001",
    "message": "Invalid request."
}

    Media AI Understanding API

    Media AI Understanding 서비스에서 제공하는 API에 대한 설명은 다음과 같습니다.

    프로젝트 관리

    API 설명
    프로젝트 생성 비디오 에셋과 분석 결과를 관리할 수 있는 공간인 프로젝트 생성
    프로젝트 목록 조회 워크스페이스 내 프로젝트 목록 조회
    프로젝트 상세 조회 워크스페이스 내 프로젝트에 대해 상세 정보 조회
    프로젝트 정보 수정 워크스페이스 내 프로젝트 정보 수정
    프로젝트 삭제 워크스페이스에서 프로젝트 삭제

    비디오 에셋 관리

    API 설명
    비디오 에셋 등록 Object Storage 버킷에 업로드한 영상 파일을 프로젝트에 추가
    비디오 에셋 목록 조회 프로젝트 내 비디오 에셋 목록 조회
    비디오 에셋 상세 조회 프로젝트 내 비디오 에셋에 대해 상세 정보 조회
    비디오 에셋 등록 상태 조회 프로젝트에 등록한 비디오 에셋의 상태 조회
    비디오 에셋 프로젝트 이동 비디오 에셋을 다른 프로젝트로 이동
    비디오 에셋 삭제 프로젝트에서 비디오 에셋 삭제

    비디오 에셋 분석

    API 설명
    비디오 에셋 분석 요청 비디오 에셋을 분석하여 영상 분석 결과인 인덱스 생성
    비디오 에셋 분석 상태 조회 프로젝트에 등록한 비디오 에셋의 분석 상태 조회
    비디오 에셋 분석 취소 진행 중인 비디오 에셋의 분석 요청 취소

    인덱스 관리

    API 설명
    인덱스 목록 조회 비디오 에셋의 인덱스 목록 조회
    인덱스 상세 조회 비디오 에셋의 인덱스에 대해 상세 정보 조회
    인덱스 삭제 비디오 에셋의 인덱스 삭제

    인물 태그 관리

    API 설명
    인물 태그 등록 워크스페이스에 인물 태그를 등록
    인물 태그 목록 조회 워크스페이스 내 인물 태그 목록 조회
    인물 태그 삭제 워크스페이스에서 인물 태그 삭제

    인물 관리

    API 설명
    인물 등록 워크스페이스에 신규 인물을 등록
    인물 상세 조회 인물의 상세 정보 조회
    인물 정보 수정 인물 이름, 설명 등의 정보 수정
    인물 수정 태그 설정 인물에 태그를 설정
    인물 수정 태그 제거 인물에서 태그를 제거
    인물 수정 썸네일 설정 인물 썸네일을 설정
    인물 수정 썸네일 제거 인물 썸네일을 제거
    인물 삭제 워크스페이스에서 인물 제거
    인물 목록 조회 워크스페이스 내 인물 목록 조회
    썸네일 Presigned URL 발급 인물 썸네일 업로드를 위한 Presigned URL 발급
    썸네일 업로드 상태 조회 썸네일 업로드 완료 상태 조회

    장면 검색

    API 설명
    검색 에셋 Presigned URL 발급 장면 검색을 위한 쿼리 에셋 업로드 Presigned URL 발급
    검색 에셋 업로드 상태 조회 업로드된 쿼리 에셋의 업로드 완료 여부 확인
    장면 검색 요청 영상에서 조건에 맞는 장면 검색
    장면 검색 결과 조회 장면 검색 요청에 대한 결과(장면 목록)를 조회

    Media AI Understanding 연관 리소스

    Media AI Understanding API에 대한 사용자의 이해를 돕기 위해 다양한 연관 리소스를 제공하고 있습니다.