Unit API 시작하기

• 호출 한 번이 결과 하나입니다. 제출건(submission)을 만들지 않습니다.
• 모든 호출은 동기로 처리됩니다. 결과는 응답으로 바로 받고, 웹훅은 없습니다.
• 결과가 나온 호출만 과금합니다. 오류로 결과가 나오지 않은 호출은 과금하지 않습니다.

​

제공 API

​

이미지·텍스트 분석

​

외부 기관 조회

​

시작 순서

​

호출 주소

POST https://client-api.argosidentity.com/v1/units/{api}

• {api}는 각 API 페이지에 있는 경로입니다. 예: /v1/units/id-ocr
• 모든 리전에서 14종을 모두 쓸 수 있습니다.
• 키는 프로젝트의 리전에서만 통합니다. 다른 리전 호스트로 호출하면 401이 돌아옵니다. 프로젝트 리전은 리전 안내에서 확인하세요.

​

인증

curl -X POST "https://client-api.argosidentity.com/v1/units/txt-fz-mat" \
  -H "x-api-key: {yourUnitApiKey}" \
  -H "Content-Type: application/json" \
  -d '{"text1": "Hong Gildong", "text2": "Gildong Hong", "referenceId": "order-20261103-0001"}'

curl -X POST "https://kr.client-api.argosidentity.com/v1/units/txt-fz-mat" \
  -H "x-api-key: {yourUnitApiKey}" \
  -H "Content-Type: application/json" \
  -d '{"text1": "Hong Gildong", "text2": "Gildong Hong", "referenceId": "order-20261103-0001"}'

​

키 재발급

• 키가 노출됐거나 오남용이 의심되면 Owner·Leader가 대시보드에서 키를 재발급합니다.
• 재발급하면 이전 키는 즉시 폐기됩니다. 이전 키로 들어온 호출은 401 INVALID_API_KEY로 거절되고 과금되지 않습니다.
• 재발급한 사람과 시각은 키 발급 이력과 이벤트 로그에 남습니다.

​

요청 규칙

• 본문은 JSON으로 보내고 Content-Type: application/json을 붙입니다. 다른 타입은 415 UNSUPPORTED_MEDIA_TYPE으로 거절됩니다.
• 계약에 없는 필드를 보내면 400 UNKNOWN_PARAMETER로 거절됩니다. 오타가 조용히 무시되어 엉뚱한 결과로 과금되는 일을 막기 위해서입니다.
• 빈 문자열("")과 null은 값을 보내지 않은 것으로 보지 않고 400 INVALID_PARAMETER_FORMAT으로 거절합니다. 선택 필드는 값이 없으면 키째 빼고 보내세요.
• 날짜는 YYYY-MM-DD 형식입니다. 예: 2019-03-14

​

이미지

• Base64 문자열로 보냅니다. data:image/jpeg;base64, 같은 접두어는 붙여도 되고 빼도 됩니다.
• JPEG와 PNG만 받습니다. iPhone HEIC, GIF, BMP 등은 JPEG로 변환해서 보내세요.
• 한 장당 원본 약 3 MB(접두어를 뺀 Base64 4,000,064자)까지 받습니다. 넘으면 400 PARAMETER_OUT_OF_RANGE입니다. 휴대폰으로 찍은 신분증 사진은 대부분 그대로 보낼 수 있습니다.

​

referenceId

​

공통 응답

{
  "txId": "01a17c3a-646f-762e-bb38-fe0cae059282",
  "txCode": "FACE_LIVE_PSV",
  "createdAt": "2026-11-03T07:19:24.015Z",
  "latencyMs": 812,
  "billing": {
    "unit": "response",
    "count": 1,
    "unitPrice": 0.08,
    "credit": 0.08,
    "pricingVersion": "v4.0_KOR"
  },
  "referenceId": "order-20261103-0001",
  "data": {
    "livenessScore": 93
  }
}

​

판정 읽기

• MATCH: 기관 기록과 일치합니다.
• MISMATCH: 기관이 불일치로 답했습니다. 조회는 이루어졌으므로 과금됩니다.
• REJECTED: 진본이지만 지금은 효력이 없습니다(효력을 잃은 여권, 휴업·폐업 사업자).

​

과금 기준

• 결과가 나오면 차감됩니다. 얼굴 유사도가 낮게 나오거나 기관이 불일치(MISMATCH)로 답해도 결과가 나온 것이므로 차감됩니다.
• 오류로 결과가 나오지 않으면 차감되지 않습니다. HTTP 상태가 200이 아닌 모든 응답입니다.
• 대시보드 API 테스트로 실행한 호출도 같은 기준으로 차감됩니다.
• 체험(Trial) 프로젝트는 차감되지 않습니다. 대신 월 호출 수가 제한됩니다. 프로젝트 상태별 이용 범위
• 같은 요청을 두 번 보내면 두 건으로 처리하고 두 번 차감합니다.

​

API별 단가

​

프로젝트 상태별 이용 범위

• 체험 한도는 오류를 포함한 호출 수로 셉니다. 차감되지 않은 오류 호출과 한도 초과로 거절된 호출도 포함됩니다.
• 한도는 매월 1일 00:00 UTC(한국시간 오전 9시)에 초기화됩니다.
• 한도를 넘기면 429 TRIAL_LIMIT_EXCEEDED가 돌아오고, Retry-After 헤더에 초기화까지 남은 초가 들어 있습니다.

​

데이터 보관과 개인정보

• 요청·응답 본문은 저장되지 않습니다. 응답을 받는 즉시 결과를 txId와 함께 시스템에 저장해 두세요. ARGOS에서 결과를 다시 조회할 수 없습니다.
• 호출 기록은 3년간 보관됩니다. 호출 시각, API, 결과, 오류 코드, 처리 시간, Count, 크레딧, 소스(라이브·API 테스트), 실행자, referenceId가 남습니다.
• 테스트라도 실제 개인정보를 넣으려면 정보주체의 동의 등 처리 근거가 있어야 합니다.

​

다음 단계