생체 정보 업로드

개요

반려동물의 생체 정보(지문/코 이미지, 외관 이미지)를 업로드하는 API입니다. 업로드 전에 반드시 캡처 세션을 생성해야 합니다.

캡처 세션 생성

생체 정보 업로드 전에 캡처 세션을 먼저 생성합니다.

엔드포인트: POST /v2/capture-sessions

요청

curl -X POST "https://api.petify.petnow.io/v2/capture-sessions" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "species": "DOG",
    "purpose": "PET_PROFILE_REGISTRATION",
    "petId": "pet-uuid-1234"
  }'

import requests

url = "https://api.petify.petnow.io/v2/capture-sessions"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "species": "DOG",
    "purpose": "PET_PROFILE_REGISTRATION",
    "petId": "pet-uuid-1234"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
session_id = result["data"]["id"]
print(f"Session ID: {session_id}")

const response = await fetch("https://api.petify.petnow.io/v2/capture-sessions", {
  method: "POST",
  headers: {
    "x-petnow-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    species: "DOG",
    purpose: "PET_PROFILE_REGISTRATION",
    petId: "pet-uuid-1234"
  })
});

const result = await response.json();
const sessionId = result.data.id;
console.log(`Session ID: ${sessionId}`);

요청 파라미터

필드	타입	필수	설명
`species`	string	✅	종류: `DOG` 또는 `CAT`
`purpose`	string	✅	목적 (아래 표 참조)
`petId`	string	조건부	등록/검증 시 필수

Purpose 값

Purpose	설명	Pet ID
`PET_PROFILE_REGISTRATION`	새 반려동물 등록	필수
`PET_VERIFICATION`	특정 반려동물 검증 (1:1)	필수
`PET_IDENTIFICATION`	반려동물 식별 (1:N)	불필요

응답

{
  "data": {
    "id": "session-uuid-abcd"
  }
}

지문(코) 이미지 업로드

반려동물의 코(지문) 이미지를 업로드합니다.

엔드포인트: POST /v2/fingerprints:upload?sessionId={sessionId}

필수: sessionId 쿼리 파라미터가 항상 필요합니다. 업로드된 파일은 자동으로 해당 세션에 연결됩니다.

요청

curl -X POST "https://api.petify.petnow.io/v2/fingerprints:upload?sessionId=session-uuid-abcd" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/nose_image.jpg"

import requests

session_id = "session-uuid-abcd"
url = f"https://api.petify.petnow.io/v2/fingerprints:upload?sessionId={session_id}"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY"
}

with open("/path/to/nose_image.jpg", "rb") as f:
    files = {"file": ("nose_image.jpg", f, "image/jpeg")}
    response = requests.post(url, headers=headers, files=files)

result = response.json()
fingerprint_id = result["data"]["id"]
print(f"Fingerprint ID: {fingerprint_id}")

const sessionId = "session-uuid-abcd";
const formData = new FormData();
formData.append("file", fileBlob, "nose_image.jpg");

const response = await fetch(
  `https://api.petify.petnow.io/v2/fingerprints:upload?sessionId=${sessionId}`,
  {
    method: "POST",
    headers: {
      "x-petnow-api-key": "YOUR_API_KEY"
    },
    body: formData
  }
);

const result = await response.json();
const fingerprintId = result.data.id;
console.log(`Fingerprint ID: ${fingerprintId}`);

요청 파라미터

필드	타입	필수	설명
`sessionId`	string (query)	✅	캡처 세션 ID
`file`	file	✅	지문(코) 이미지 파일 (JPEG)

응답

{
  "data": {
    "id": "fingerprint-uuid-1234"
  }
}

업로드 개수: 등록 시 최소 5장, 검증/식별 시 최소 3장의 지문 이미지가 필요합니다. 더 많은 이미지를 업로드할수록 인식 정확도가 향상됩니다. 외관 이미지도 모든 용도에서 필수입니다 — UI 모듈이 제공하는 외관 이미지를 업로드하세요. 개수는 직접 관리할 필요가 없습니다.

외관 이미지 업로드

반려동물의 외관 이미지를 업로드합니다. 외관 이미지는 모든 캡처 세션(등록/지문 추가, 검증, 식별)에서 필수입니다. UI 모듈이 제공하는 외관 이미지를 업로드하세요. 외관 이미지를 생략하면 작업이 CaptureSessionIsNotFinishedException (PETNOWB2B20012) 오류로 실패합니다.

엔드포인트: POST /v2/appearances:upload?sessionId={sessionId}

요청

curl -X POST "https://api.petify.petnow.io/v2/appearances:upload?sessionId=session-uuid-abcd" \
  -H "x-petnow-api-key: YOUR_API_KEY" \
  -F "file=@/path/to/pet_photo.jpg"

import requests

session_id = "session-uuid-abcd"
url = f"https://api.petify.petnow.io/v2/appearances:upload?sessionId={session_id}"
headers = {
    "x-petnow-api-key": "YOUR_API_KEY"
}

with open("/path/to/pet_photo.jpg", "rb") as f:
    files = {"file": ("pet_photo.jpg", f, "image/jpeg")}
    response = requests.post(url, headers=headers, files=files)

result = response.json()
appearance_id = result["data"]["id"]
print(f"Appearance ID: {appearance_id}")

const sessionId = "session-uuid-abcd";
const formData = new FormData();
formData.append("file", fileBlob, "pet_photo.jpg");

const response = await fetch(
  `https://api.petify.petnow.io/v2/appearances:upload?sessionId=${sessionId}`,
  {
    method: "POST",
    headers: {
      "x-petnow-api-key": "YOUR_API_KEY"
    },
    body: formData
  }
);

const result = await response.json();
const appearanceId = result.data.id;
console.log(`Appearance ID: ${appearanceId}`);

요청 파라미터

필드	타입	필수	설명
`sessionId`	string (query)	✅	캡처 세션 ID
`file`	file	✅	외관 이미지 파일 (JPEG)

응답

{
  "data": {
    "id": "appearance-uuid-5678"
  }
}

전체 업로드 플로우 예시

세션 자동 연결: 업로드 시 sessionId 쿼리 파라미터를 사용하면 파일이 자동으로 해당 세션에 연결됩니다. 별도의 세션 종료 API 호출은 필요하지 않습니다.

import requests
from pathlib import Path

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.petify.petnow.io"
HEADERS = {"x-petnow-api-key": API_KEY}

def upload_biometrics(pet_id: str, fingerprint_files: list, appearance_files: list):
    # 1. 캡처 세션 생성
    session_response = requests.post(
        f"{BASE_URL}/v2/capture-sessions",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={
            "species": "DOG",
            "purpose": "PET_PROFILE_REGISTRATION",
            "petId": pet_id
        }
    )
    session_id = session_response.json()["data"]["id"]
    print(f"Created session: {session_id}")

    # 2. 지문 업로드 (sessionId 쿼리 파라미터로 자동 연결)
    fingerprint_ids = []
    for file_path in fingerprint_files:
        with open(file_path, "rb") as f:
            response = requests.post(
                f"{BASE_URL}/v2/fingerprints:upload?sessionId={session_id}",
                headers=HEADERS,
                files={"file": (Path(file_path).name, f, "image/jpeg")}
            )
            fp_id = response.json()["data"]["id"]
            fingerprint_ids.append(fp_id)
            print(f"Uploaded fingerprint: {fp_id}")

    # 3. 외관 업로드 (sessionId 쿼리 파라미터로 자동 연결)
    appearance_ids = []
    for file_path in appearance_files:
        with open(file_path, "rb") as f:
            response = requests.post(
                f"{BASE_URL}/v2/appearances:upload?sessionId={session_id}",
                headers=HEADERS,
                files={"file": (Path(file_path).name, f, "image/jpeg")}
            )
            ap_id = response.json()["data"]["id"]
            appearance_ids.append(ap_id)
            print(f"Uploaded appearance: {ap_id}")

    return session_id, fingerprint_ids, appearance_ids

# 사용 예시
session_id, fp_ids, ap_ids = upload_biometrics(
    pet_id="pet-uuid-1234",
    fingerprint_files=["nose1.jpg", "nose2.jpg", "nose3.jpg", "nose4.jpg", "nose5.jpg"],
    appearance_files=["full_body.jpg"]
)

const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.petify.petnow.io";

async function uploadBiometrics(petId, fingerprintFiles, appearanceFiles) {
  const headers = { "x-petnow-api-key": API_KEY };

  // 1. 캡처 세션 생성
  const sessionResponse = await fetch(`${BASE_URL}/v2/capture-sessions`, {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({
      species: "DOG",
      purpose: "PET_PROFILE_REGISTRATION",
      petId: petId
    })
  });
  const sessionId = (await sessionResponse.json()).data.id;
  console.log(`Created session: ${sessionId}`);

  // 2. 지문 업로드 (sessionId 쿼리 파라미터로 자동 연결)
  const fingerprintIds = [];
  for (const file of fingerprintFiles) {
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch(
      `${BASE_URL}/v2/fingerprints:upload?sessionId=${sessionId}`,
      {
        method: "POST",
        headers: headers,
        body: formData
      }
    );
    const fpId = (await response.json()).data.id;
    fingerprintIds.push(fpId);
    console.log(`Uploaded fingerprint: ${fpId}`);
  }

  // 3. 외관 업로드 (sessionId 쿼리 파라미터로 자동 연결)
  const appearanceIds = [];
  for (const file of appearanceFiles) {
    const formData = new FormData();
    formData.append("file", file);

    const response = await fetch(
      `${BASE_URL}/v2/appearances:upload?sessionId=${sessionId}`,
      {
        method: "POST",
        headers: headers,
        body: formData
      }
    );
    const apId = (await response.json()).data.id;
    appearanceIds.push(apId);
    console.log(`Uploaded appearance: ${apId}`);
  }

  return { sessionId, fingerprintIds, appearanceIds };
}

생체 정보 업로드

개요

캡처 세션 생성

요청

요청 파라미터

Purpose 값

응답

지문(코) 이미지 업로드

요청

요청 파라미터

응답

외관 이미지 업로드

요청

요청 파라미터

응답

전체 업로드 플로우 예시

다음 단계

On this page