API 문서

모리아AI 파트너 API는 증명사진 생성과 자동 양식 인식을 외부 서비스·기관 시스템에서 직접 부를 수 있게 연 통로입니다. 현장 키오스크가 쓰는 것과 같은 코드를 쓰므로 결과물이 갈라지지 않습니다.

화면을 새로 만들지 않아도 됩니다. 이미 쓰고 계신 시스템에서 사진이나 서류를 보내면, 결과를 받아 그대로 띄우거나 저장하시면 됩니다.

답에 따라 준비할 것이 완전히 달라집니다. 해당하는 쪽만 읽으시면 됩니다.

어느 쪽을 고르시든 순서는 같습니다. 다른 것은 3단계를 누가 하느냐입니다.

1. 1
   문의

   쓰실 기능과 예상 사용량을 알려주세요.
2. 2
   키 발급

   기능 권한·허용 도메인·횟수를 정해 열어 드립니다.
3. 3
   연결

   연결 점검으로 통신을 확인하고 실제 화면에 붙입니다.
4. 4
   운영

   남은 횟수와 오류를 보며 필요할 때 충전합니다.

API 를 직접 부르지 않고도 같은 기능을 쓰실 수 있습니다. 세 가지 중 지금 환경에 맞는 쪽을 상담에서 함께 고릅니다.

발급받은 키를 헤더에 넣습니다. 두 가지 형태 중 편한 쪽을 쓰시면 되고, 둘 다 같게 동작합니다.

x-api-key: mrai_xxxxxxxxxxxx_xxxxxxxx...

# 또는
Authorization: Bearer mrai_xxxxxxxxxxxx_xxxxxxxx...

키마다 쓸 수 있는 기능이 정해져 있습니다. 열어 주지 않은 기능을 부르면 403 SCOPE_NOT_GRANTED 로 막힙니다.

기능을 붙이기 전에 이 호출로 키와 통신을 확인하세요. 아무것도 실행하지 않아 사용 횟수가 줄지 않습니다. 남은 횟수도 여기서 볼 수 있습니다.

curl -H "x-api-key: $MORIAH_API_KEY" \
  https://moriahai.com/api/public/v1/health

{
  "ok": true,
  "partner": { "id": "acme", "name": "에이스" },
  "scopes": ["id-photo", "smart-form"],
  "quota": { "unlimited": false, "limit": 5000,
             "used": 873, "remaining": 4127 }
}

파일을 그대로 올리거나(multipart) base64 로 넣어(JSON) 보냅니다. 사진은 10MB 이하, jpeg·png·webp·heic 를 받습니다.

curl -X POST https://moriahai.com/api/public/v1/id-photo \
  -H "x-api-key: $MORIAH_API_KEY" \
  -F "image=@photo.jpg" \
  -F "background=white" \
  -F "gender=auto" \
  -F "retouch=light"

{
  "ok": true,
  "requestId": "3f2b1c...",
  "image": { "base64": "...", "mimeType": "image/jpeg",
             "width": 600, "height": 800, "byteLength": 148213 },
  "meta": { "gender": "auto", "retouch": "light",
            "cropped": true, "latencyMs": 21458 }
}

주요 항목

서류 사진에서 제목·기본 정보·표를 구조 그대로 뽑아냅니다. 이력서·신청서처럼 칸이 정해진 문서에 맞습니다.

curl -X POST https://moriahai.com/api/public/v1/smart-form \
  -H "x-api-key: $MORIAH_API_KEY" \
  -F "image=@document.jpg"

{
  "ok": true,
  "document": {
    "title": "이력서",
    "basicInfo": { "name": "홍길동", "birthDate": "1990-01-01",
                   "phone": "010-0000-0000", "email": "...",
                   "address": "...", "gender": "..." },
    "blocks": [
      { "type": "fields", ... },
      { "type": "table",  ... },
      { "type": "paragraph", ... }
    ],
    "warnings": []
  },
  "meta": { "blockCount": 6, "latencyMs": 8342 }
}

blocks 는 문서에 나온 순서 그대로입니다. 화면에 그대로 그리거나 필요한 값만 골라 쓰시면 됩니다.

오류는 모두 같은 모양입니다. HTTP 상태가 아니라 code 로 갈라 처리하세요.

{ "ok": false, "requestId": "3f2b1c...",
  "code": "IMAGE_TOO_LARGE", "message": "..." }

재시도 기준

• 4xx — 요청을 고쳐야 합니다. 다시 보내도 결과가 같습니다.
• 429 — RATE_LIMITED 는 Retry-After 초 뒤 재시도. QUOTA_EXCEEDED 는 기다려도 풀리지 않고 충전해야 합니다.
• 502 — 한 번쯤 재시도할 만합니다. 같은 사진에서 계속 실패하면 사진 문제입니다.
• 503 — 처리량이 몰렸습니다. 잠시 후 재시도하세요.

API_KEY_INVALID 는 「그런 키가 없다」와 「키는 있는데 값이 틀렸다」를 구분하지 않습니다. 구분해 주면 키를 추측하는 쪽에 힌트가 되기 때문입니다.

계약으로 정한 총 사용 횟수가 있습니다. 성공한 호출만 차감하며, 모델이 실패한 건은 횟수를 쓰지 않습니다.

X-Quota-Limit: 5000
X-Quota-Remaining: 4127
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

• 다 쓰면 429 QUOTA_EXCEEDED 로 기능 호출이 막힙니다.
• 막힌 뒤에도 연결 점검은 열려 있습니다. 남은 횟수를 확인하는 길까지 막지 않습니다.
• 충전 방식은 매달 다시 채워지는 월 자동 갱신과 담당자가 채우는 수동 충전 두 가지입니다.
• 한도가 없는 회선에는 위 X-Quota-* 헤더가 붙지 않습니다.

결과가 나올 때까지 기다리는 방식이라 타임아웃을 넉넉히 잡아야 합니다. 증명사진은 200초를 권합니다.

const form = new FormData();
form.append("image", new Blob([buffer], { type: "image/jpeg" }), "photo.jpg");
form.append("background", "white");

const response = await fetch("https://moriahai.com/api/public/v1/id-photo", {
  method: "POST",
  headers: { "x-api-key": process.env.MORIAH_API_KEY },
  body: form,
  signal: AbortSignal.timeout(200_000),
});

const result = await response.json();
if (!result.ok) throw new Error(`${result.code}: ${result.message}`);

const image = Buffer.from(result.image.base64, "base64");

• 키는 환경변수나 비밀 저장소에 두고, 저장소(Git)에 커밋하지 마세요.
• 유출이 의심되면 알려 주세요. 즉시 폐기하고 새 키를 발급합니다.
• 일시 중지는 되돌릴 수 있지만 폐기는 되돌릴 수 없습니다.

입력 사진과 결과물을 저장하지 않습니다. 요청을 처리하는 동안만 메모리에 두고, 응답을 보낸 뒤 버립니다. 결과가 필요하시면 받는 쪽에서 보관하셔야 합니다.

남기는 것은 정산과 장애 확인에 필요한 호출 기록(시각·기능·성공 여부·처리 시간)뿐이며, 사진이나 인식된 개인정보는 포함하지 않습니다.

기관·기업 도입 시 개인정보 처리위탁 계약이 필요하면 상담에서 함께 준비합니다.

파트너가 체감하는 변화만 적습니다. 현재 버전은 v1 이며, 지금까지 기존 연동을 깨는 변경은 없었습니다.