API 문서 · 에셋

에셋 유형과 실제 인물 인증

trust_class, 가상 인물, 실제 인물 사진의 얼굴 인증.

에셋을 만들 때 trust_class로 에셋 유형을 선언합니다. 플랫폼은 인물을 자동으로 판별하지 않으며 선언한 값을 따릅니다. 생성 후에는 바꿀 수 없으니, 잘못 선언했다면 삭제 후 다시 업로드하세요.

trust_class	용도	사용 조건
`normal`	일반 이미지, 동영상, 오디오(기본값)	처리 후 바로 사용 가능
`virtual_avatar`	AI 생성 또는 캐릭터 이미지 등 가상 인물, 인물 일관성 유지용	처리 후 바로 사용 가능. 작업에 처음 사용할 때 플랫폼이 처리 채널의 에셋 라이브러리로 동기화하며(작업 상태 preparing), 에셋 라이브러리를 지원하는 경로에만 배정됩니다
`real_person`	실제 인물 사진(이미지만)	처음에는 authorization_required이며, 사진 속 본인이 실제 인물 인증을 마쳐야 사용 가능

실제 인물 인증 절차

POST /v1/assets/{id}/portrait-authorizations를 { "model": "…" }(이 에셋을 사용할 모델)와 함께 호출합니다. 201과 인증 객체가 반환되며, status는 pending이고 h5_link와 expires_at(30분 후)이 포함됩니다.
h5_link를 사진 속 본인에게 전달하세요(예: QR 코드). 본인이 휴대폰으로 열어 안내에 따라 얼굴 인증을 완료합니다. 완료되면 이 사이트의 안내 페이지로 이동하니, 앱에서 결과를 기다리면 됩니다.
GET /v1/portrait-authorizations/{id}를 5초 정도마다 조회해 status가 verified, failed, expired 중 하나가 될 때까지 기다립니다. 플랫폼도 백그라운드에서 확인하므로 조회하지 않아도 상태는 갱신됩니다.
verified가 되면 에셋이 available로 바뀌어 해당 모델의 작업에 사용할 수 있습니다.

콘솔 · 에셋의 에셋 상세에서 바로 시작할 수도 있습니다. 페이지에 QR 코드가 표시되고 결과가 자동으로 갱신됩니다.GET /v1/assets/{id}/portrait-authorizations는 에셋의 최근 인증 기록을 나열합니다.

인증 상태

status	의미
`pending`	본인의 얼굴 인증을 기다리는 중. h5_link는 이 상태에서만 반환
`verified`	인증 통과. verified_at은 통과 시각
`failed`	인증 실패. error에 원인이 표시되며 다시 시작할 수 있음
`expired`	30분 안에 완료되지 않음. 다시 시작할 수 있음

인증은 모델별로 적용

인증은 시작할 때 선택한 모델에만 유효합니다. 이 에셋으로 다른 모델의 작업을 제출하면 422 authorization_required가 반환되니 , 그 모델로 인증을 한 번 더 시작하세요. 같은 에셋이 같은 모델에서 이미 인증되었다면 다시 시작해도 기존 verified 기록이 반환됩니다.

오류

HTTP	code	상황
422	`invalid_parameter`	에셋이 real_person이 아니거나 이미지가 아님, 또는 model이 존재하지 않음
403	`permission_denied`	계정에 해당 모델이 열려 있지 않음
404	`not_found`	에셋이나 인증 기록이 없거나 본인 것이 아님
503	`no_available_channel`	해당 모델에 지금 사용할 수 있는 실제 인물 인증 채널이 없음. 잠시 후 다시 시도

사진 속 인물은 얼굴 인증을 한 본인이어야 합니다

업스트림이 에셋과 인증한 얼굴을 비교합니다. 일치하지 않으면 에셋을 생성에 쓸 수 없고, 이를 사용한 작업은 asset_rejected로 실패합니다.

# 실제 인물 인증 시작: h5_link 반환, 30분간 유효
curl https://api.aitoken.tools/v1/assets/asset_xxx/portrait-authorizations \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-standard"}'

# h5_link를 사진 속 본인에게 보내 얼굴 인증을 받은 뒤, status가 verified / failed / expired가 될 때까지 조회
curl https://api.aitoken.tools/v1/portrait-authorizations/auth_xxx \
  -H "Authorization: Bearer $AITOKEN_API_KEY"