다음을 통해 공유


Person Group Operations - Add Person Group Person Face

얼굴 식별 또는 확인을 위해 사람 그룹에 얼굴을 추가합니다.
여러 얼굴이 포함된 이미지를 처리하기 위해 입력 얼굴을 targetFace 사각형이 있는 이미지로 지정할 수 있습니다. 추가된 얼굴을 나타내는 persistedFaceId를 반환합니다. 이미지가 저장되지 않습니다. "사람 그룹 사람 얼굴 삭제", "사람 그룹 사람 삭제" 또는 "사람 그룹 삭제"가 호출될 때까지 추출된 얼굴 기능만 서버에 저장됩니다.

persistedFaceId는 "Detect"에서 생성된 faceId와 다릅니다.

    • 얼굴 이미지 품질이 높을수록 인식 정밀도를 높일 수 있습니다. 고품질 얼굴을 고려하세요. 정면, 투명 및 얼굴 크기는 200x200픽셀(눈 사이에 100픽셀) 이상입니다.
    • 각 사람 항목은 최대 248개의 얼굴을 보유할 수 있습니다.
    • JPEG, PNG, GIF(첫 번째 프레임) 및 BMP 형식이 지원됩니다. 허용되는 이미지 파일 크기는 1KB에서 6MB까지입니다.
    • "targetFace" 사각형은 하나의 얼굴을 포함해야 합니다. 0개 또는 여러 얼굴은 오류로 간주됩니다. 제공된 "targetFace" 사각형이 "Detect"에서 반환되지 않으면 얼굴을 감지하고 성공적으로 추가해야 합니다.
    • 감지 가능한 얼굴 크기(36x36 - 4096x4096 픽셀), 큰 머리 포즈 또는 큰 폐색으로 인해 오류가 발생합니다.
    • 감지 가능한 최소 얼굴 크기는 1920x1080픽셀 이하의 이미지에서 36x36픽셀입니다. 크기가 1920x1080 픽셀보다 큰 이미지에는 비례적으로 더 큰 최소 얼굴 크기가 필요합니다.
    • 다양한 'detectionModel' 값을 제공할 수 있습니다. 다양한 검색 모델을 사용하고 비교하려면 다음을 참조하세요. https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces
POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces?_overload=addPersonGroupPersonFace&targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

URI 매개 변수

Name In(다음 안에) 필수 형식 Description
apiVersion
path True

string

API 버전

endpoint
path True

string

uri

지원되는 Cognitive Services 엔드포인트(프로토콜 및 호스트 이름: https://{resource-name}.cognitiveservices.azure.com).

personGroupId
path True

string

컨테이너의 ID입니다.

regex 패턴: ^[a-z0-9-_]+$

personId
path True

string

uuid

사용자의 ID입니다.

detectionModel
query

DetectionModel

검색된 faceId와 연결된 'detectionModel'입니다. 지원되는 'detectionModel' 값에는 'detection_01', 'detection_02' 및 'detection_03'가 포함됩니다. 기본값은 'detection_01'입니다.

targetFace
query

integer[]

사람에게 추가할 대상 얼굴을 'targetFace=left,top,width,height' 형식으로 지정하는 얼굴 사각형입니다.

userData
query

string

얼굴에 연결된 사용자 제공 데이터입니다. 크기 제한은 1K입니다.

요청 본문

Media Types: "application/octet-stream"

Name 형식 Description
imageContent

string

분석할 이미지

응답

Name 형식 Description
200 OK

AddFaceResult

호출이 성공하면 새로운 persistedFaceId가 반환됩니다.

Other Status Codes

FaceErrorResponse

예기치 않은 오류 응답입니다.

헤더

x-ms-error-code: string

보안

Ocp-Apim-Subscription-Key

Azure AI Face 구독의 비밀 키입니다.

형식: apiKey
In(다음 안에): header

AADToken

Azure Active Directory OAuth2 흐름

형식: oauth2
Flow: accessCode
권한 부여 URL: https://api.example.com/oauth2/authorize
토큰 URL: https://api.example.com/oauth2/token

범위

Name Description
https://cognitiveservices.azure.com/.default

예제

Add Face to PersonGroup Person

샘플 요청

POST {endpoint}/face/v1.1-preview.1/persongroups/your_person_group_id/persons/25985303-c537-4467-b41d-bdb45cd95ca1/persistedfaces?_overload=addPersonGroupPersonFace&targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

"<your-image-bytes-here>"

샘플 응답

{
  "persistedFaceId": "43897a75-8d6f-42cf-885e-74832febb055"
}

정의

Name Description
AddFaceResult

얼굴을 추가하기 위한 응답 본문입니다.

DetectionModel

검색된 faceId와 연결된 'detectionModel'입니다. 지원되는 'detectionModel' 값에는 'detection_01', 'detection_02' 및 'detection_03'가 포함됩니다. 기본값은 'detection_01'입니다.

FaceError

Error 개체. Face Service에서 반환된 오류 코드 및 메시지에 대한 포괄적인 세부 정보는 링크를 https://aka.ms/face-error-codes-and-messages참조하세요.

FaceErrorResponse

오류 세부 정보가 포함된 응답입니다.

AddFaceResult

얼굴을 추가하기 위한 응답 본문입니다.

Name 형식 Description
persistedFaceId

string

지속되고 만료되지 않는 추가된 얼굴의 지속형 얼굴 ID입니다. "검색"에서 만들어지고 검색 호출 후 24시간 후에 만료되는 faceId와 다릅니다.

DetectionModel

검색된 faceId와 연결된 'detectionModel'입니다. 지원되는 'detectionModel' 값에는 'detection_01', 'detection_02' 및 'detection_03'가 포함됩니다. 기본값은 'detection_01'입니다.

Name 형식 Description
detection_01

string

기본 검색 모델입니다. 가까운 정면 얼굴 감지에 권장합니다. 매우 큰 각도(머리 포즈) 얼굴, 가려진 얼굴 또는 잘못된 이미지 방향을 가진 시나리오의 경우 이러한 경우 얼굴이 감지되지 않을 수 있습니다.

detection_02

string

2019년 5월에 출시된 감지 모델은 특히 작고 측면 및 흐릿한 얼굴에서 정확도가 향상되었습니다.

detection_03

string

2021년 2월에 출시된 감지 모델은 특히 작은 얼굴에서 정확도가 향상되었습니다.

FaceError

Error 개체. Face Service에서 반환된 오류 코드 및 메시지에 대한 포괄적인 세부 정보는 링크를 https://aka.ms/face-error-codes-and-messages참조하세요.

Name 형식 Description
code

string

서버 정의 오류 코드 집합 중 하나입니다.

message

string

사람이 읽을 수 있는 오류 표현입니다.

FaceErrorResponse

오류 세부 정보가 포함된 응답입니다.

Name 형식 Description
error

FaceError

Error 개체.