openapi: 3.1.0
info:
  title: CodeProject.AI Server Articles Vision-Face API
  description: CodeProject.AI Server is a self-contained, self-hosted, free and open-source AI service that exposes computer-vision, audio, NLP, and model-training capabilities through a local HTTP REST API. It runs on Windows, macOS, Linux, Raspberry Pi, NVIDIA Jetson, OrangePi, and as a Docker container, and is most often integrated with home-automation and surveillance platforms (Blue Iris, Home Assistant, Agent DVR) for object detection, face recognition, ALPR (license-plate), and scene classification. All endpoints are POST and accept multipart/form-data uploads.
  version: '2.9'
  contact:
    name: CodeProject.AI Server
    url: https://www.codeproject.com/AI/
  license:
    name: GPL-3.0
    url: https://github.com/codeproject/CodeProject.AI-Server/blob/main/LICENSE
servers:
- url: http://localhost:32168
  description: Default local CodeProject.AI Server endpoint
tags:
- name: Vision-Face
  description: Face detection, comparison, registration, and recognition.
paths:
  /v1/vision/face:
    post:
      operationId: detectFaces
      summary: Detect faces in an image
      tags:
      - Vision-Face
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - image
              properties:
                image:
                  type: string
                  format: binary
                min_confidence:
                  type: number
                  format: float
      responses:
        '200':
          description: Face detection result
  /v1/vision/face/match:
    post:
      operationId: matchFaces
      summary: Compare two face images for similarity
      tags:
      - Vision-Face
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - image1
              - image2
              properties:
                image1:
                  type: string
                  format: binary
                image2:
                  type: string
                  format: binary
      responses:
        '200':
          description: Match result
  /v1/vision/face/list:
    post:
      operationId: listRegisteredFaces
      summary: List registered users for face recognition
      tags:
      - Vision-Face
      responses:
        '200':
          description: Registered users
  /v1/vision/face/register:
    post:
      operationId: registerFace
      summary: Register face images for a user
      tags:
      - Vision-Face
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - userid
              - image
              properties:
                userid:
                  type: string
                image:
                  type: string
                  format: binary
      responses:
        '200':
          description: Registration result
  /v1/vision/face/delete:
    post:
      operationId: deleteFace
      summary: Remove a registered user
      tags:
      - Vision-Face
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - userid
              properties:
                userid:
                  type: string
      responses:
        '200':
          description: Deletion result
  /v1/vision/face/recognize:
    post:
      operationId: recognizeFaces
      summary: Identify faces in an image against the registered set
      tags:
      - Vision-Face
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - image
              properties:
                image:
                  type: string
                  format: binary
                min_confidence:
                  type: number
                  format: float
      responses:
        '200':
          description: Recognition result
components:
  securitySchemes:
    none:
      type: apiKey
      in: header
      name: X-Disabled
      description: CodeProject.AI Server runs locally and does not require authentication by default. Operators are expected to keep the service on a private network or behind their own reverse proxy.
externalDocs:
  description: CodeProject.AI Server documentation
  url: https://codeproject.github.io/codeproject.ai/