# eKYC 본인확인



사진이 있는 신분증(주민등록증·운전면허증·여권·외국인등록증) 사진과, 고개를 좌우로 돌린 짧은 촬영 영상(또는 얼굴 사진)을 함께 받아 ① 신분증 사진이 실물 카메라 촬영본인지(화면 캡처·편집 여부) ② 지금 실제 사람이 움직였는지(라이브니스) ③ 신분증 얼굴과 촬영한 얼굴이 같은 사람인지 한 번에 판정합니다. 등본·주민등록등초본처럼 사진이 없는 서류는 대상이 아닙니다.



인증: Authorization: Bearer $APICK_API_KEY

본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다.

인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다.



## POST /rest/kyc_session 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.verified` (boolean): 'verified' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.result` (integer): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.

- `data.reason` (string): 'reason' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.message` (string): 안내 문구입니다. 오류 원인과 다음 행동을 설명합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.session_id` (string): 'session_id' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.document` (object): 'document' 관련 값을 묶은 객체입니다. 하위 필드에 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.document.verdict` (string): 'verdict' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.document.reason` (string): 'reason' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.document.camera_capture` (boolean): 'camera_capture' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.document.edited` (boolean): 'edited' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.document.screen_capture` (boolean): 'screen_capture' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.document.capture_age_days` (number): 'capture_age_days' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness` (object): 'liveness' 관련 값을 묶은 객체입니다. 하위 필드에 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.liveness.verdict` (string): 'verdict' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.liveness.duration_seconds` (number): 'duration_seconds' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness.motion` (number): 'motion' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness.pan_shift` (number): 'pan_shift' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness.failed` (array): 'failed' 목록입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다.

- `data.liveness.manual` (array): 'manual' 목록입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다.

- `data.face` (object): 'face' 관련 값을 묶은 객체입니다. 하위 필드에 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.face.verdict` (string): 'verdict' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.face.similarity` (number): 'similarity' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.similarity_avg` (number): 'similarity_avg' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.matched_frames` (integer): 'matched_frames' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.frames` (integer): 'frames' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.threshold` (number): 'threshold' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.elapsed_ms` (integer): 'elapsed_ms' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.similarity` (number): 'similarity' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/kyc_session



### 입력

- `challenge` (string, 선택): 좌우 방향을 직접 지정합니다. turn_left_right·turn_right_left. 생략하면 서버가 무작위로 정합니다.

- `data[result][session_id]` (string, 선택): 1회용 세션 식별자(32자)입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `data[result][challenge]` (string, 선택): 좌우 지시 방향입니다. SDK 가 이 방향으로 고개를 돌리게 안내합니다.

- `data[result][nonce]` (string, 선택): 서명에 묶이는 1회용 값입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `data[result][expires_at]` (integer, 선택): 세션 만료 시각(밀리초)입니다. 기본 15분입니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

- `session_id` (string, 필수): kyc_session 이 준 세션 식별자입니다. 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.

- `nonce` (string, 필수): kyc_session 이 준 nonce 값입니다. 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.

- `frames[0]` (string, 필수): 촬영 중 확인한 프레임 지문입니다. 6~128자 hex, 1~60개입니다.

- `session` (string, 필수): 촬영 세션 서명(/rest/kyc_session 발급 → /rest/kyc_seal 서명)

- `document_image` (file, 필수): 사진이 있는 신분증 사진(PNG·JPEG, 최대 20MB)입니다. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다.

- `face_video` (file, 선택): 고개를 좌우로 돌린 촬영 영상(MP4·MOV·WebM·3GP, 1~60초, 최대 30MB)입니다. face_image 와 둘 중 하나는 필수입니다.

- `face_image` (file, 선택): 촬영 영상 대신 보내는 정지 얼굴 사진(JPEG·PNG, 최대 10MB)입니다. 라이브니스는 담당자 확인으로 내려갑니다.

- `threshold` (number, 선택): 얼굴 일치 기준 점수 (범위: 0.2 ~ 0.8, 기본값 0.4) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

- `data[result]` (integer, 선택): 1 통과, 0 실패, 2 담당자 확인입니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

- `data[verified]` (boolean, 선택): result == 1 과 같습니다. true/false로 보내며, 생략하면 서버 기본값이 적용됩니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data[reason]` (string, 선택): 사유 코드입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `data[message]` (string, 선택): 사용자에게 보여 줄 문구입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

- `data[document]` (object, 선택): 신분증 실물성 — verdict·reason·camera_capture·edited·screen_capture·capture_age_days.

- `data[liveness]` (object, 선택): 라이브니스 — verdict·duration_seconds·motion(움직이는 프레임 비율)·pan_shift(좌우 이동)·failed·manual.

- `data[face]` (object, 선택): 얼굴 대조 — verdict·similarity(가장 높은 점수)·similarity_avg·matched_frames·frames·threshold.

- `data[similarity]` (number, 선택): 가장 높은 얼굴 유사도(MCP 연동 편의 필드)입니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "verified": {
          "type": "boolean"
        },
        "result": {
          "type": "integer"
        },
        "reason": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "session_id": {
          "type": "string"
        },
        "document": {
          "type": "object",
          "properties": {
            "verdict": {
              "type": "string"
            },
            "reason": {
              "type": "string"
            },
            "camera_capture": {
              "type": "boolean"
            },
            "edited": {
              "type": "boolean"
            },
            "screen_capture": {
              "type": "boolean"
            },
            "capture_age_days": {
              "type": "number"
            }
          }
        },
        "liveness": {
          "type": "object",
          "properties": {
            "verdict": {
              "type": "string"
            },
            "duration_seconds": {
              "type": "number"
            },
            "motion": {
              "type": "number"
            },
            "pan_shift": {
              "type": "number"
            },
            "failed": {
              "type": "array",
              "items": {}
            },
            "manual": {
              "type": "array",
              "items": {}
            }
          }
        },
        "face": {
          "type": "object",
          "properties": {
            "verdict": {
              "type": "string"
            },
            "similarity": {
              "type": "number"
            },
            "similarity_avg": {
              "type": "number"
            },
            "matched_frames": {
              "type": "integer"
            },
            "frames": {
              "type": "integer"
            },
            "threshold": {
              "type": "number"
            }
          }
        },
        "elapsed_ms": {
          "type": "integer"
        },
        "similarity": {
          "type": "number"
        },
        "success": {
          "type": "integer"
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer"
        },
        "ms": {
          "type": "integer"
        },
        "pl_id": {
          "type": "integer"
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "verified": true,
    "result": 1,
    "reason": "MATCH",
    "message": "본인 확인에 성공했습니다.",
    "session_id": "9f2c1b7e0a5d4c3b8e1f6a2d7c0b4e5a",
    "document": {
      "verdict": "pass",
      "reason": "CAMERA_CAPTURE",
      "camera_capture": true,
      "edited": false,
      "screen_capture": false,
      "capture_age_days": 0.1
    },
    "liveness": {
      "verdict": "pass",
      "duration_seconds": 4.2,
      "motion": 0.82,
      "pan_shift": 1.9,
      "failed": [],
      "manual": []
    },
    "face": {
      "verdict": "pass",
      "similarity": 0.612,
      "similarity_avg": 0.55,
      "matched_frames": 4,
      "frames": 5,
      "threshold": 0.4
    },
    "elapsed_ms": 6210,
    "similarity": 0.612,
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 200,
    "ms": 6240,
    "pl_id": 108712
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/kyc_session' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "session_id=${APICK_SESSION_ID}" \
  --form-string "nonce=${APICK_NONCE}" \
  --form-string "frames[0]=${APICK_FRAMES_0_}" \
  --form-string "session=${APICK_SESSION}" \
  --form 'document_image=@/path/to/input.file'

```

### Node.js (서버 ESM)

```javascript

import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("session_id", process.env.APICK_SESSION_ID);
form.append("nonce", process.env.APICK_NONCE);
form.append("frames[0]", process.env.APICK_FRAMES_0_);
form.append("session", process.env.APICK_SESSION);
form.append("document_image", new Blob([await readFile("/path/to/input.file")]), "input.file");
const response = await fetch("https://apick.app/rest/kyc_session", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("session_id", (None, os.environ["APICK_SESSION_ID"])),
    ("nonce", (None, os.environ["APICK_NONCE"])),
    ("frames[0]", (None, os.environ["APICK_FRAMES_0_"])),
    ("session", (None, os.environ["APICK_SESSION"])),
    ("document_image", ("input.file", open("/path/to/input.file", "rb"))),
]
response = requests.request("POST", "https://apick.app/rest/kyc_session",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'session_id' => getenv('APICK_SESSION_ID'),
    'nonce' => getenv('APICK_NONCE'),
    'frames[0]' => getenv('APICK_FRAMES_0_'),
    'session' => getenv('APICK_SESSION'),
    'document_image' => new CURLFile('/path/to/input.file'),
];
$curl = curl_init('https://apick.app/rest/kyc_session');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## POST /rest/kyc_verify 응답 필드

- `data` (object): 요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

- `data.verified` (boolean): 'verified' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.result` (integer): 조회 결과 본문입니다. 서비스가 찾은 실제 데이터가 들어 있으며, 자료가 없거나 조회에 실패하면 null이거나 필드가 생략됩니다.

- `data.reason` (string): 'reason' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.message` (string): 안내 문구입니다. 오류 원인과 다음 행동을 설명합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.

- `data.session_id` (string): 'session_id' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.document` (object): 'document' 관련 값을 묶은 객체입니다. 하위 필드에 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.document.verdict` (string): 'verdict' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.document.reason` (string): 'reason' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.document.camera_capture` (boolean): 'camera_capture' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.document.edited` (boolean): 'edited' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.document.screen_capture` (boolean): 'screen_capture' 여부를 true/false로 나타냅니다. 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

- `data.document.capture_age_days` (number): 'capture_age_days' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness` (object): 'liveness' 관련 값을 묶은 객체입니다. 하위 필드에 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.liveness.verdict` (string): 'verdict' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.liveness.duration_seconds` (number): 'duration_seconds' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness.motion` (number): 'motion' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness.pan_shift` (number): 'pan_shift' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.liveness.failed` (array): 'failed' 목록입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다.

- `data.liveness.manual` (array): 'manual' 목록입니다. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다.

- `data.face` (object): 'face' 관련 값을 묶은 객체입니다. 하위 필드에 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

- `data.face.verdict` (string): 'verdict' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.

- `data.face.similarity` (number): 'similarity' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.similarity_avg` (number): 'similarity_avg' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.matched_frames` (integer): 'matched_frames' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.frames` (integer): 'frames' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.face.threshold` (number): 'threshold' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.elapsed_ms` (integer): 'elapsed_ms' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.similarity` (number): 'similarity' 수치 값입니다. 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

- `data.success` (integer): 업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.

- `api` (object): API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

- `api.success` (boolean): API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

- `api.cost` (integer): 이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

- `api.ms` (integer): 서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.

- `api.pl_id` (integer): 포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

## API 요청: POST /rest/kyc_verify



### 입력

- `session` (string, 필수): 촬영 세션 서명(/rest/kyc_session 발급 → /rest/kyc_seal 서명)

- `document_image` (file, 필수): 사진이 있는 신분증 사진(PNG·JPEG, 최대 20MB)입니다. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다.

- `face_video` (file, 선택): 고개를 좌우로 돌린 촬영 영상(MP4·MOV·WebM·3GP, 1~60초, 최대 30MB)입니다. face_image 와 둘 중 하나는 필수입니다.

- `face_image` (file, 선택): 촬영 영상 대신 보내는 정지 얼굴 사진(JPEG·PNG, 최대 10MB)입니다. 라이브니스는 담당자 확인으로 내려갑니다.

- `threshold` (number, 선택): 얼굴 일치 기준 점수 (범위: 0.2 ~ 0.8, 기본값 0.4) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.



### 응답 명세

```json

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "verified": {
          "type": "boolean"
        },
        "result": {
          "type": "integer"
        },
        "reason": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "session_id": {
          "type": "string"
        },
        "document": {
          "type": "object",
          "properties": {
            "verdict": {
              "type": "string"
            },
            "reason": {
              "type": "string"
            },
            "camera_capture": {
              "type": "boolean"
            },
            "edited": {
              "type": "boolean"
            },
            "screen_capture": {
              "type": "boolean"
            },
            "capture_age_days": {
              "type": "number"
            }
          }
        },
        "liveness": {
          "type": "object",
          "properties": {
            "verdict": {
              "type": "string"
            },
            "duration_seconds": {
              "type": "number"
            },
            "motion": {
              "type": "number"
            },
            "pan_shift": {
              "type": "number"
            },
            "failed": {
              "type": "array",
              "items": {}
            },
            "manual": {
              "type": "array",
              "items": {}
            }
          }
        },
        "face": {
          "type": "object",
          "properties": {
            "verdict": {
              "type": "string"
            },
            "similarity": {
              "type": "number"
            },
            "similarity_avg": {
              "type": "number"
            },
            "matched_frames": {
              "type": "integer"
            },
            "frames": {
              "type": "integer"
            },
            "threshold": {
              "type": "number"
            }
          }
        },
        "elapsed_ms": {
          "type": "integer"
        },
        "similarity": {
          "type": "number"
        },
        "success": {
          "type": "integer"
        }
      }
    },
    "api": {
      "type": "object",
      "properties": {
        "success": {
          "type": "boolean"
        },
        "cost": {
          "type": "integer"
        },
        "ms": {
          "type": "integer"
        },
        "pl_id": {
          "type": "integer"
        }
      }
    }
  }
}

```

### 정적 응답 예시

```json

{
  "data": {
    "verified": true,
    "result": 1,
    "reason": "MATCH",
    "message": "본인 확인에 성공했습니다.",
    "session_id": "9f2c1b7e0a5d4c3b8e1f6a2d7c0b4e5a",
    "document": {
      "verdict": "pass",
      "reason": "CAMERA_CAPTURE",
      "camera_capture": true,
      "edited": false,
      "screen_capture": false,
      "capture_age_days": 0.1
    },
    "liveness": {
      "verdict": "pass",
      "duration_seconds": 4.2,
      "motion": 0.82,
      "pan_shift": 1.9,
      "failed": [],
      "manual": []
    },
    "face": {
      "verdict": "pass",
      "similarity": 0.612,
      "similarity_avg": 0.55,
      "matched_frames": 4,
      "frames": 5,
      "threshold": 0.4
    },
    "elapsed_ms": 6210,
    "similarity": 0.612,
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 200,
    "ms": 6240,
    "pl_id": 108712
  }
}

```

### curl

```curl

curl --fail-with-body --request POST 'https://apick.app/rest/kyc_verify' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "session=${APICK_SESSION}" \
  --form 'document_image=@/path/to/input.file'

```

### Node.js (서버 ESM)

```javascript

import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("session", process.env.APICK_SESSION);
form.append("document_image", new Blob([await readFile("/path/to/input.file")]), "input.file");
const response = await fetch("https://apick.app/rest/kyc_verify", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

```

### python

```python

import os
import requests
parts = [
    ("session", (None, os.environ["APICK_SESSION"])),
    ("document_image", ("input.file", open("/path/to/input.file", "rb"))),
]
response = requests.request("POST", "https://apick.app/rest/kyc_verify",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

```

### php

```php

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'session' => getenv('APICK_SESSION'),
    'document_image' => new CURLFile('/path/to/input.file'),
];
$curl = curl_init('https://apick.app/rest/kyc_verify');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

```

## 코드·오류

### 업무 실패 응답

입력 오류·대상 없음·일시 실패는 data.error(사유)와 data.success=0으로 오며 api.cost는 0(과금 없음)입니다. HTTP 상태는 400·404·408·424 중 하나입니다. 입력 오류는 값을 고쳐 다시 요청하고, 408·424는 잠시 후 한 번 다시 시도하세요.

```json

{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}

```

## 상세 기능·요금

업로드 용량 제한: 60MB 한 요청에서 신분증 사진은 최대 20MB(PNG·JPEG), 얼굴 영상은 최대 30MB(MP4·MOV·WebM·3GP, 1~60초), 얼굴 사진은 최대 10MB입니다. 촬영 세션 서명이 함께 와야 하며 파일은 판정 직후 삭제됩니다. 제한을 초과하면 HTTP 413과 REQUEST_TOO_LARGE 오류가 반환되며 과금되지 않습니다. 한눈에 보는 흐름 촬영 시작 전 POST /rest/kyc_session 으로 1회용 촬영 세션을 받습니다. 서버가 좌우 방향(왼쪽→오른쪽 또는 오른쪽→왼쪽)을 정해 줍니다. 촬영이 끝나면 화면에서 확인한 프레임 지문을 POST /rest/kyc_seal 로 보내 서버 서명(kyc1.…)을 받습니다. 신분증 사진과 촬영 결과를 POST /rest/kyc_verify 로 보냅니다. 서명이 유효하고 세션이 처음 쓰일 때만 판정합니다. 응답의 data.result가 1(통과)·0(실패)·2(담당자 확인)입니다. 항목별 근거 수치는 data.document·data.liveness·data.face에 담깁니다. 웹 촬영 화면은 이 사이트의 /js/apick-kyc-sdk.js 를 쓰면 됩니다. 아래 웹 SDK 절을 보세요. 이용 전 확인 신분증은 PNG·JPEG 사진(최대 20MB) 만 받습니다. 사진이 있는 신분증(주민등록증·운전면허증·여권·외국인등록증)을 카메라로 찍은 사진을 보내세요. 얼굴은 ASMR 영상(MP4·MOV·WebM·3GP, 1~60초, 최대 30MB) 또는 얼굴 사진(JPEG·PNG, 최대 10MB) 을 받습니다. 영상이 있으면 움직임을 실제로 분석하고, 사진만 있으면 얼굴 대조만 합니다(liveness 판정이 담당자 확인으로 내려갑니다). 촬영 세션이 없거나, 서명이 맞지 않거나, 이미 쓴 세션이면 차감 없이 거절합니다. 시간 초과·처리 실패도 과금하지 않습니다. 판정까지 진행된 요청은 결과(통과·불통과·담당자 확인)와 관계없이 건당 과금됩니다. 정지 사진처럼 확정 판정이 어려운 경우도 위조·대조 분석을 끝냈으므로 정상 응답으로 보고 요금을 받습니다. 보낸 사진·영상은 판정이 끝나면 바로 삭제하며 저장하지 않습니다. 응답에도 이미지·얼굴 특징값을 담지 않고 판정 수치만 줍니다. 건당 200P 입니다. 꼼수·미리 찍은 사진을 막는 장치 우회 시도막는 방법 미리 찍어 둔 영상·사진을 그대로 보냄1회용 촬영 세션 + 서버 서명(kyc_seal)이 없으면 거절합니다. 세션은 처음 쓴 순간 소비되어 다시 쓸 수 없습니다. 정지 사진을 카메라 앞에 대고 촬영영상 프레임의 연속 움직임·장면 전환과 좌우 무게중심 이동을 함께 봅니다. 움직임이 없으면 실패합니다. 녹화 영상을 재생해 카메라 앞에 비춤SDK 는 좌우 챌린지 방향을 화면에 지시하고, 촬영 중 화면 전환·탭 이탈을 감지하면 촬영을 무효화합니다. 화면 공유(getDisplayMedia)로는 카메라를 열 수 없게 막습니다. 화면 캡처로 만든 신분증 사진촬영 메타데이터(카메라 기기·촬영 시각)와 화면 캡처 표시·편집 프로그램 표시를 확인합니다. 화면 캡처로 판단되면 실패합니다. 다른 계정·다른 사람이 촬영분을 옮겨 씀세션 서명은 계정 단위로 묶여 있어 다른 계정에서는 서명 검증이 실패합니다. 서버 판정이 최종입니다. SDK 의 사전 이동 확인은 통과 확률을 높이는 보조 장치일 뿐, 서버가 다시 움직임·얼굴 일치를 확인합니다. 판정 읽는 법 data.result뜻권장 처리 1세 항목(신분증 실물성·라이브니스·얼굴 대조)이 모두 기준을 넘었습니다.자동 통과 2자동으로 확정하기 어려운 항목이 있습니다(신분증 메타데이터 없음, 점수 경계, 영상 움직임 자료 없음 등).담당자 확인 또는 재촬영 요청 0위조·화면 캡처·움직임 없음·얼굴 불일치 중 하나 이상이 확인됐습니다.거절 data.reason은 실패·확인 사유 코드(SCREEN_CAPTURE, LIVENESS_MOTION, LIVENESS_PAN, LOW_SIMILARITY 등)이고, data.message는 사용자에게 보여 줄 문구입니다. 웹 SDK 브라우저에서 신분증 촬영 + 얼굴 촬영 + 서명 + 판정을 한 화면에서 진행합니다. 스크립트는 /js/apick-kyc-sdk.js 입니다. 모드document설명 모드 A"camera"신분증 사진도 카메라로 촬영하고, 이어서 얼굴 촬영을 진행합니다. 모드 B"upload"신분증은 파일로 올리고 얼굴만 촬영합니다. 사용 예시 <script src="https://apick.app/js/apick-kyc-sdk.js"></script> <div id="kyc"></div> <script> const kyc = new ApickKyc({ apiKey: "내 API 인증키" }); kyc.start(document.getElementById("kyc"), { document: "camera" }, (event) => { if (event.type === "done") { // event.detail.result.result === 1 이면 통과 console.log(event.detail.result); } if (event.type === "error") console.log("실패:", event.detail.message); }).catch(() => {}); </script> 보안 장치(1회용 세션·좌우 챌린지·탭 이탈 감지·화면 공유 차단·좌우 이동 확인)는 SDK 가 자동으로 켭니다. 꺼 두면 서버 판정에서 라이브니스가 실패할 수 있습니다. 카메라는 https 에서만 열립니다.

## 상세 요청

요청 — 촬영 세션 항목설정 메서드·주소POST https://apick.app/rest/kyc_session 인증 헤더Authorization: Bearer 내 계정의 API 인증키 본문 형식multipart/form-data 또는 빈 본문 응답 요청 예시 form-data 전체 예제 보기 요청 — 촬영 결과 서명 SDK 가 화면에서 확인한 프레임 지문(프레임마다 40자 SHA-256 지문, 최대 60개)을 보냅니다. 서버가 세션과 묶어 서명합니다. 응답의 data.result.session(kyc1.…)을 판정 요청의 session 에 그대로 넣습니다. 요청 — 본인 확인 판정 항목설정 메서드·주소POST https://apick.app/rest/kyc_verify 인증 헤더Authorization: Bearer 내 계정의 API 인증키 본문 형식multipart/form-data. 서버간 연동은 같은 이름의 data: URI 문자열을 JSON 으로 보내도 됩니다. 응답 응답 예시 { "data": { "verified": true, "result": 1, "reason": "MATCH", "message": "본인 확인에 성공했습니다.", "session_id": "9f2c1b7e0a5d4c3b8e1f6a2d7c0b4e5a", "document": { "verdict": "pass", "reason": "CAMERA_CAPTURE", "camera_capture": true, "edited": false, "screen_capture": false, "capture_age_days": 0.1 }, "liveness": { "verdict": "pass", "duration_seconds": 4.2, "motion": 0.82, "pan_shift": 1.9, "failed": [], "manual": [] }, "face": { "verdict": "pass", "similarity": 0.612, "similarity_avg": 0.55, "matched_frames": 4, "frames": 5, "threshold": 0.4 }, "elapsed_ms": 6210, "similarity": 0.612, "success": 1 }, "api": { "success": true, "cost": 200, "ms": 6240, "pl_id": 108712 } }

## 상세 코드·정책

오류와 대처 실패하면 data.error에 문구가 담기고 api.cost는 0입니다. HTTPdata.error대처 400촬영 세션(session)이 없습니다. …먼저 kyc_session 과 kyc_seal 을 호출하세요. 400신분증 사진(document_image)이 없습니다.document_image 를 보내세요. 400얼굴 사진 또는 촬영 영상(face_image, face_video)이 없습니다.face_video 또는 face_image 중 하나를 보내세요. 413얼굴 영상은 30MB, 얼굴 사진은 10MB 이하여야 합니다.촬영 길이·해상도를 줄이세요(SDK 기본값으로 촬영하면 넘지 않습니다). 422촬영 영상에서 실제 사람의 움직임을 확인하지 못했습니다. …안내에 따라 고개를 좌우로 크게 돌려 다시 촬영하세요. 422화면 캡처로 만든 신분증 사진은 사용할 수 없습니다. …실물 신분증을 카메라로 촬영하세요. 422이미 사용했거나 만료된 촬영 세션입니다. …촬영 세션은 1회만 쓸 수 있습니다. 새 세션을 받으세요. 422신분증 사진과 촬영한 얼굴이 일치하지 않습니다.다른 사람의 신분증인지 확인하고 다시 촬영하세요. 424본인 확인 서비스를 사용할 수 없습니다. … / 영상 처리 시간이 길어 …잠시 뒤 한 번 더 요청하세요(과금 없음).

## 상세 예제

호출 예시 키는 환경변수 APICK_API_KEY 에서 읽습니다. JavaScript (Node.js 18 이상) form-data 전체 예제 보기 Python (requests) form-data 전체 예제 보기
