Face Management API

This document describes how to use the terminal-level Face Management API, which allows you to manage facial recognition data using your terminal secret.

API Description

All API endpoints are relative to the base URL:


https://api.ticos.ai/v1/api

Request Headers

Parameter	Required	Description
Authorization	Yes	Format: `Bearer <terminal_secret>`, terminal secret obtained during terminal registration
Content-Type	Varies	For POST and PUT operations with file uploads: `multipart/form-data`

API Endpoints

List All Faces


GET /faces

Retrieves all faces associated with the terminal’s group.

Response

After a successful call, the service returns JSON:


[
  {
    "face_id": "face123",
    "group_id": "user_id_identifier",
    "id": 39,
    "name": "Test Face"
  }
]

Create Face


POST /faces

Creates a new face in the terminal’s associated group.

Request Body Fields

Field	Type	Required	Description
`image`	File	Yes	Face image file
`name`	string	Yes	Face name

Response

After a successful call, the service returns JSON:


{
  "return_code": 0,
  "return_message": "Success"
}

Get Face


GET /faces/{face_id}

Retrieves a specific face from the terminal’s group.

Response

After a successful call, the service returns JSON:


{
  "face_id": "face123",
  "group_id": "user_id_identifier",
  "id": 39,
  "name": "Test Face"
}

Update Face


PUT /faces/{face_id}

Updates a specific face in the terminal’s group.

Request Body Fields

Field	Type	Required	Description
`name`	string	Yes	Face name
`image`	File	No	Face image file

Response

After a successful call, the service returns JSON:


{
  "return_code": 0,
  "return_message": "Success"
}

Delete Face


DELETE /faces/{face_id}

Deletes a specific face from the terminal’s group.

Response

204 No Content

Get Face Image


GET /faces/{face_id}/image

Retrieves the image of a specific face.

Response

Image data in the appropriate MIME type

Error Responses

All endpoints may return the following error responses:

400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication failed
404 Not Found: Resource not found
500 Internal Server Error: Server error

Example Code

cURL


# List all faces
curl -X GET "https://api.ticos.ai/v1/api/faces" \
  -H "Authorization: Bearer <terminal_secret>"
 
# Create a new face
curl -X POST "https://api.ticos.ai/v1/api/faces" \
  -H "Authorization: Bearer <terminal_secret>" \
  -H "Content-Type: multipart/form-data" \
  -F "name=Test Face" \
  -F "image=@/path/to/face.jpg"
 
# Get a specific face
curl -X GET "https://api.ticos.ai/v1/api/faces/face123" \
  -H "Authorization: Bearer <terminal_secret>"
 
# Update a face
curl -X PUT "https://api.ticos.ai/v1/api/faces/face123" \
  -H "Authorization: Bearer <terminal_secret>" \
  -H "Content-Type: multipart/form-data" \
  -F "name=Updated Face Name" \
  -F "image=@/path/to/new_face.jpg"
 
# Delete a face
curl -X DELETE "https://api.ticos.ai/v1/api/faces/face123" \
  -H "Authorization: Bearer <terminal_secret>"
 
# Get face image
curl -X GET "https://api.ticos.ai/v1/api/faces/face123/image" \
  -H "Authorization: Bearer <terminal_secret>" \
  --output face.jpg

Python


import requests
 
base_url = "https://api.ticos.ai/v1/api"
headers = {
    "Authorization": "Bearer <terminal_secret>"
}
 
# List all faces
response = requests.get(f"{base_url}/faces", headers=headers)
faces = response.json()
print(faces)
 
# Create a new face
files = {
    "image": open("/path/to/face.jpg", "rb")
}
data = {
    "name": "Test Face"
}
response = requests.post(f"{base_url}/faces", headers=headers, files=files, data=data)
print(response.json())
 
# Get a specific face
face_id = "face123"
response = requests.get(f"{base_url}/faces/{face_id}", headers=headers)
print(response.json())
 
# Update a face
files = {
    "image": open("/path/to/new_face.jpg", "rb")
}
data = {
    "name": "Updated Face Name"
}
response = requests.put(f"{base_url}/faces/{face_id}", headers=headers, files=files, data=data)
print(response.json())
 
# Delete a face
response = requests.delete(f"{base_url}/faces/{face_id}", headers=headers)
print(response.status_code)  # Should be 204
 
# Get face image
response = requests.get(f"{base_url}/faces/{face_id}/image", headers=headers)
with open("face.jpg", "wb") as f:
    f.write(response.content)

Common Issues

Issue	Solution
Returns 401 Unauthorized	Check if the terminal secret in the `Authorization` header is correct
Returns 400 Bad Request	Ensure all required fields are provided and the image format is supported
Returns 404 Not Found	Verify that the face_id exists in the terminal’s group

Implementation Details

Face ID Generation

When creating a face, the system automatically generates a unique face_id. The face_id is a 32-character hexadecimal string generated from 16 random bytes.

Best Practices

Error Handling
- Always check response status codes
- Implement proper error handling for all API calls
- Use appropriate retry mechanisms
Security
- Keep your terminal secret secure
- Use HTTPS for all API calls
Performance
- Cache responses when appropriate
- Implement request batching
- Use compression for large payloads