Register API

Register new persons in the Visage memory bank.

Endpoint

POST /api/v1/register

Request

Headers

Content-Type: multipart/form-data

Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Person's name
relationship	string	No	Relationship to user
image	file	Yes	Face image (JPEG/PNG)
metadata	JSON	No	Additional metadata

Example Request

curl -X POST http://localhost:8000/api/v1/register \
  -F "name=John Doe" \
  -F "relationship=Friend" \
  -F "image=@photo.jpg"

Response

Success Response (200)

{
  "success": true,
  "data": {
    "person_id": "uuid-here",
    "name": "John Doe",
    "relationship": "Friend",
    "embedding_count": 1,
    "created_at": "2025-12-04T10:30:00Z"
  },
  "error": null
}

Error Responses

No Face Detected (400)

{
  "success": false,
  "data": null,
  "error": {
    "code": "NO_FACE_DETECTED",
    "message": "No face detected in the provided image"
  }
}

Invalid Image (400)

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_IMAGE",
    "message": "Invalid image format. Supported: JPEG, PNG"
  }
}

Code Examples

Python

import requests

url = "http://localhost:8000/api/v1/register"
files = {"image": open("photo.jpg", "rb")}
data = {"name": "John Doe", "relationship": "Friend"}

response = requests.post(url, files=files, data=data)
result = response.json()

print(f"Person ID: {result['data']['person_id']}")

JavaScript

const formData = new FormData();
formData.append('name', 'John Doe');
formData.append('relationship', 'Friend');
formData.append('image', fileInput.files[0]);

const response = await fetch('http://localhost:8000/api/v1/register', {
  method: 'POST',
  body: formData
});

const result = await response.json();
console.log('Person ID:', result.data.person_id);

Best Practices

1. Image Quality: Use clear, well-lit photos
2. Face Position: Ensure face is centered and frontal
3. Multiple Samples: Register 3-5 photos per person for better accuracy
4. Validation: Check for successful face detection before registering

Next Steps

• WebSocket API - Real-time identification
• API Overview - Back to API overview