Azure AI Video Indexer API를 사용하여 얼굴 편집

Azure AI Video Indexer를 사용하여 비디오 속의 얼굴을 감지하고 식별할 수 있습니다. 개인의 얼굴을 흐리게 처리(편집)하도록 비디오를 수정하려면 API를 사용하면 됩니다.

여러 사람의 얼굴이 나오는 몇 분 길이의 영상을 수동으로 편집하려면 몇 시간이 걸릴 수 있지만, Video Indexer API의 사전 설정을 사용하면 몇 번의 간단한 단계를 통해 얼굴을 편집할 수 있습니다.

이 문서에서는 API를 사용하여 얼굴을 편집하는 방법을 보여줍니다. Video Indexer API에는 클라우드에서 확장성 있는 얼굴 감지 및 편집(흐리게 처리)을 제공하는 얼굴 편집 사전 설정이 포함되어 있습니다. 이 문서에서는 API를 사용하여 얼굴을 편집하는 각 단계를 자세히 설명합니다.

다음 비디오에서는 Azure AI Video Indexer API를 사용하여 비디오를 편집하는 방법을 보여줍니다.

규정 준수, 프라이버시 및 보안

다시 강조하지만, Video Indexer를 사용하여 얻은 분석 또는 인사이트를 사용할 때 모든 관련 법률을 준수해야 합니다.

Face 서비스 액세스는 Microsoft 책임 있는 AI 원칙을 지원하기 위해 자격 및 사용 기준에 따라 제한됩니다. Face 서비스는 Microsoft 관리 고객 및 파트너만 사용할 수 있습니다. 얼굴 인식 접수 양식을 사용하여 액세스를 적용합니다. 자세한 내용은 얼굴 제한 액세스 페이지를 참조하세요.

얼굴 편집 용어 및 계층 구조

Video Indexer의 얼굴 편집은 비디오 표준 및 고급 분석 사전 설정에 제공되는 기존 Video Indexer 얼굴 감지 결과의 출력을 사용합니다.

비디오를 편집하려면 먼저 Video Indexer에 비디오를 업로드하고 표준 또는 고급 비디오 사전 설정을 사용하여 분석을 완료해야 합니다. Azure AI Video Indexer 웹 사이트 또는 API를 사용하여 이 작업을 수행할 수 있습니다. 그 후 얼굴 편집 API에서 videoId 값을 사용하여 이 비디오를 참조할 수 있습니다. Microsoft에서는 표시된 얼굴이 편집되는 새 비디오를 만듭니다. 비디오 분석과 얼굴 편집 둘 다 별도로 요금이 청구될 수 있는 작업입니다. 자세한 내용은 가격 책정 페이지를 참조하세요.

흐리게 처리 유형

얼굴 편집에서 다양한 흐리게 처리 유형을 선택할 수 있습니다. 유형을 선택하려면 요청 본문에서 blurringKind 매개 변수의 이름 또는 대표 번호를 사용합니다.

blurringKind 번호	blurringKind 이름	예시
0	MediumBlur
1	HighBlur
2	LowBlur
3	BoundingBox
4	검정

요청 본문에서 blurringKind 매개 변수를 사용하여 흐리게 처리 종류를 지정할 수 있습니다.

예를 들면 다음과 같습니다.

{
    "faces": {
        "blurringKind": "HighBlur"
    }
}

또는 앞의 표에 설명된 흐리게 처리 유형을 나타내는 숫자를 사용합니다.

{
    "faces": {
        "blurringKind": 1
    }
}

필터

필터를 적용하여 흐리게 표시할 얼굴 ID를 설정할 수 있습니다. JSON 파일 본문의 쉼표로 구분된 배열에서 얼굴 ID를 지정할 수 있습니다. scope 매개 변수를 사용하여 이러한 얼굴을 편집 대상에서 제외하거나 편집 대상에 포함할 수 있습니다. ID를 지정한 후에는 사용자가 나타내는 ID를 제외한 모든 얼굴을 편집할 수도 있고, 해당 ID만 편집할 수도 있습니다. 다음 섹션의 예제를 참조하세요.

Exclude 범위

다음 예제에서는 얼굴 ID 1001 및 1016을 제외한 모든 얼굴을 편집하기 위해 Exclude 범위를 사용합니다.

{
    "faces": {
        "blurringKind": "HighBlur",
        "filter": {
            "ids": [1001, 1016],
            "scope": "Exclude"
        }
    }
}

Include 범위

다음 예제에서는 얼굴 ID 1001 및 1016만 편집하기 위해 Include 범위를 사용합니다.

{
    "faces": {
        "blurringKind": "HighBlur",
        "filter": {
            "ids": [1001, 1016],
            "scope": "Include"
        }
    }
}

모든 얼굴 편집

모든 얼굴을 편집하려면 다음과 같이 범위 필터를 제거합니다.

{
    "faces": {
        "blurringKind": "HighBlur",
    }
}

얼굴 ID를 검색하려면 인덱싱된 비디오로 이동하여 아티팩트 파일을 검색하면 됩니다. 아티팩트는 비디오에서 감지된 모든 얼굴이 들어 있는 faces.json 파일과 썸네일 .zip 파일을 포함하고 있습니다. 얼굴을 ID와 매칭하고 편집할 얼굴 ID를 결정할 수 있습니다.

편집 작업 만들기

편집 작업을 만들려면 다음 API 호출을 호출합니다.

POST https://api.videoindexer.ai/{location}/Accounts/{accountId}/Videos/{videoId}/redact[?name][&priority][&privacy][&externalId][&streamingPreset][&callbackUrl][&accessToken]

다음 값은 필수입니다.

다음은 요청 예시입니다.

https://api.videoindexer.ai/westeurope/Accounts/{id}/Videos/{id}/redact?priority=Low&name=testredaction&privacy=Private&streamingPreset=Default 

토큰을 bearertoken:{token} 키 값 형식의 인증 헤더로 지정할 수도 있고, ?token={token}을 사용하여 쿼리 매개 변수로 제공할 수도 있습니다.

또한 적용할 편집 작업 옵션을 사용하여 JSON 형식의 요청 본문을 추가해야 합니다. 예를 들면 다음과 같습니다.

{
    "faces": {
        "blurringKind": "HighBlur"
    }
}

요청이 성공하면 HTTP 202 ACCEPTED 응답을 받게 됩니다.

작업 상태 모니터링

작업 만들기 요청의 응답에서는 작업에 대한 URL이 있는 HTTP 헤더 Location을 받게 됩니다. 동일한 토큰을 사용하여 이 URL에 대한 GET 요청을 만들면 편집 작업의 상태를 확인할 수 있습니다.

다음은 URL 예시입니다.

https://api.videoindexer.ai/westeurope/Accounts/<id>/Jobs/<id>

다음은 응답의 예입니다.

{
    "creationTime": "2023-05-11T11:22:57.6114155Z",
    "lastUpdateTime": "2023-05-11T11:23:01.7993563Z",
    "progress": 20,
    "jobType": "Redaction",
    "state": "Processing"
}

Location 헤더에서 편집 작업이 완료될 때 동일한 URL을 호출하면 편집된 비디오에 대한 스토리지 SAS(공유 액세스 서명) URL을 받게 됩니다. 예시:

https://api.videoindexer.ai/westeurope/Accounts/<id>/Videos/<id>/SourceFile/DownloadUrl 

이 URL은 Azure Storage 계정에 저장된 .mp4 파일로 리디렉션됩니다.

FAQ

오류 코드

다음 섹션에서는 얼굴 편집을 사용할 때 발생할 수 있는 오류에 대해 설명합니다.

응답: 404 찾을 수 없음

계정을 찾을 수 없거나 비디오를 찾을 수 없습니다.

응답 헤더

응답 본문

기본 JSON

{
    "ErrorType": "GENERAL",
    "Message": "string"
}

응답: 400 잘못된 요청

입력이 잘못되었습니다. 또는 원래 업로드가 실패하여 비디오를 편집할 수 없습니다. 비디오를 다시 업로드하세요.

입력이 잘못되었습니다. 또는 원래 업로드가 실패하여 비디오를 편집할 수 없습니다. 비디오를 다시 업로드하세요.

응답 헤더

응답 본문

기본 JSON

{
    "ErrorType": "GENERAL",
    "Message": "string"
}

응답: 409 충돌

비디오를 이미 인덱싱 중입니다.

응답 헤더

응답 본문

기본 JSON

{
    "ErrorType": "GENERAL",
    "Message": "string"
}

응답: 401 권한 없음

액세스 토큰이 계정에 액세스할 권한이 없습니다.

응답 헤더

응답 본문

기본 JSON

{
    "ErrorType": "USER_NOT_ALLOWED",
    "Message": "Access token is not authorized to access account 'SampleAccountId'."
}

응답: 500 내부 서버 오류.

서버에서 오류가 발생했습니다.

응답 헤더

응답 본문

기본 JSON

{
    "ErrorType": "GENERAL",
    "Message": "There was an error."
}

응답: 429 요청이 너무 많음

너무 많은 요청이 전송되었습니다. Retry-After 응답 헤더를 사용하여 다음 요청을 보낼 시기를 결정합니다.

응답 헤더

응답: 504 게이트웨이 시간 초과

서버가 예상 시간 내에 게이트웨이에 응답하지 않았습니다.

응답 헤더

기본 JSON

{
    "ErrorType": "SERVER_TIMEOUT",
    "Message": "Server did not respond to gateway within expected time"
}