{
  "openapi": "3.0.4",
  "info": {
    "title": "Face Verification API",
    "description": "Face Verification API",
    "version": "v1"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/v1/face-verification/detect-faces": {
      "post": {
        "tags": [
          "FaceVerification"
        ],
        "summary": "Returns a list of detected faces on the provided image with their respective bounding boxes.",
        "requestBody": {
          "description": "Detect faces request model",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DetectFacesRequestModel"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/DetectFacesRequestModel"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/DetectFacesRequestModel"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the detected faces results",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/DetectFacesResultModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectFacesResultModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/DetectFacesResultModel"
                }
              }
            }
          },
          "400": {
            "description": "Returned when maxFaceCount is outside the allowed range (1-10)",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/face-verification/get-face-embeddings": {
      "post": {
        "tags": [
          "FaceVerification"
        ],
        "summary": "Returns a list of face embeddings for all the detected faces in the provided image.",
        "requestBody": {
          "description": "Face embeddings request model",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetFaceEmbeddingsRequestModel"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/GetFaceEmbeddingsRequestModel"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/GetFaceEmbeddingsRequestModel"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the face embeddings results",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/GetFaceEmbeddingsResultModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetFaceEmbeddingsResultModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetFaceEmbeddingsResultModel"
                }
              }
            }
          },
          "400": {
            "description": "Returned when maxFaceCount is outside the allowed range (1-10)",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          }
        }
      }
    },
    "/v1/face-verification/compare-face-embeddings": {
      "post": {
        "tags": [
          "FaceVerification"
        ],
        "summary": "Returns the similarity between two face embeddings as an integer between 0 and 100.",
        "requestBody": {
          "description": "Compare face embeddings request",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompareFaceEmbeddingsRequestModel"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/CompareFaceEmbeddingsRequestModel"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/CompareFaceEmbeddingsRequestModel"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns the similarity result",
            "content": {
              "text/plain": {
                "schema": {
                  "$ref": "#/components/schemas/CompareFaceEmbeddingsResultModel"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompareFaceEmbeddingsResultModel"
                }
              },
              "text/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompareFaceEmbeddingsResultModel"
                }
              }
            }
          }
        }
      }
    },
    "/v1/healthz": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "Simple health check endpoint that returns the current UTC time.",
        "responses": {
          "200": {
            "description": "Returns the server UTC time.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "type": "string"
                }
              },
              "text/json": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BoundingBoxModel": {
        "type": "object",
        "properties": {
          "x": {
            "type": "integer",
            "description": "Horizontal position of the detected face bounding box",
            "format": "int32"
          },
          "y": {
            "type": "integer",
            "description": "Vertical position of the detected face bounding box",
            "format": "int32"
          },
          "width": {
            "type": "integer",
            "description": "Width of the detected face bounding box",
            "format": "int32"
          },
          "height": {
            "type": "integer",
            "description": "Height of the detected face bounding box",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Model for the bounding box of a detected face"
      },
      "CompareFaceEmbeddingsRequestModel": {
        "type": "object",
        "properties": {
          "embedding1": {
            "type": "array",
            "items": {
              "type": "number",
              "format": "float"
            },
            "description": "Embedding to compare",
            "nullable": true
          },
          "embedding2": {
            "type": "array",
            "items": {
              "type": "number",
              "format": "float"
            },
            "description": "Embedding to compare with",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Represents a request to compare two face embeddings."
      },
      "CompareFaceEmbeddingsResultModel": {
        "type": "object",
        "properties": {
          "similarity": {
            "type": "integer",
            "description": "Similarity between the two embeddings with value range [-1, 100] (higher is better)\nReject any matches where similarity is less than 70.\n95 corresponds to FPR 1e-06 (or better) / 95 corresponds to FPR 1e-05 / 80 corresponds to FPR 1e-4 / 70 corresponds to FPR 1e-3\nAll thresholds were computed using our extensive in-the-wild datasets",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Represents the result of comparing two face verification embeddings, including their similarity score."
      },
      "DetectFacesRequestModel": {
        "type": "object",
        "properties": {
          "image": {
            "$ref": "#/components/schemas/ImageModel"
          },
          "maxFaceCount": {
            "type": "integer",
            "description": "Maximum number of faces to detect in the image. Must be between 1 and 10. Default: 1.",
            "format": "int32",
            "default": 1
          }
        },
        "additionalProperties": false,
        "description": "Represents a request to detect faces in an image."
      },
      "DetectFacesResultModel": {
        "type": "object",
        "properties": {
          "faces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FaceDetectionModel"
            },
            "description": "Faces found on the image",
            "nullable": true
          },
          "unprocessedFaceCount": {
            "type": "integer",
            "description": "Number of faces found on the image but were not returned (because the max_faces request parameter filtered them out)",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Model for the result of face detection"
      },
      "FaceDetectionModel": {
        "type": "object",
        "properties": {
          "confidence": {
            "type": "number",
            "description": "Face detection score with value range [0.0, 1.0] (higher is better)",
            "format": "float"
          },
          "boundingBox": {
            "$ref": "#/components/schemas/BoundingBoxModel"
          }
        },
        "additionalProperties": false,
        "description": "Model for face detection"
      },
      "FaceEmbeddingModel": {
        "type": "object",
        "properties": {
          "face": {
            "$ref": "#/components/schemas/FaceDetectionModel"
          },
          "embedding": {
            "type": "array",
            "items": {
              "type": "number",
              "format": "float"
            },
            "description": "Face verification embedding of the face",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Model representing a face embedding with associated face detection data"
      },
      "GetFaceEmbeddingsRequestModel": {
        "type": "object",
        "properties": {
          "image": {
            "$ref": "#/components/schemas/ImageModel"
          },
          "maxFaceCount": {
            "type": "integer",
            "description": "Maximum number of faces to get the embedding on. Must be between 1 and 10. Default: 1.",
            "format": "int32",
            "default": 1
          }
        },
        "additionalProperties": false,
        "description": "Represents a request to generate face embeddings from an input image for face verification purposes."
      },
      "GetFaceEmbeddingsResultModel": {
        "type": "object",
        "properties": {
          "faces": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FaceEmbeddingModel"
            },
            "description": "Faces found on the image",
            "nullable": true
          },
          "unprocessedFaceCount": {
            "type": "integer",
            "description": "Number of faces found on the image but were not calculated the embedding on (because the max_faces request parameter filtered them out)",
            "format": "int32"
          }
        },
        "additionalProperties": false,
        "description": "Model for the result of face verification embedding extraction"
      },
      "ImageModel": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "URL of a jpeg or png image",
            "nullable": true
          },
          "bytes": {
            "type": "string",
            "description": "Base 64 string encoded binary jpeg or png image",
            "nullable": true
          }
        },
        "additionalProperties": false,
        "description": "Represents an image using either a URL or a Base64 encoded string."
      },
      "ProblemDetails": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "nullable": true
          },
          "title": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "detail": {
            "type": "string",
            "nullable": true
          },
          "instance": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": { }
      }
    },
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "description": "JWT Authorization header using the Bearer scheme. \r\n\r\n Enter your token in the text input below.\r\n\r\nExample: \"1safsfsdfd...\"",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "ApiKey": {
        "type": "apiKey",
        "description": "API key Authorization header using the ApiKey scheme. \r\n\r\n Enter 'ApiKey' [space] and then your APIKey in the text input below.\r\n\r\nExample: \"ApiKey 5j3245lj...\"",
        "name": "Authorization",
        "in": "header"
      }
    }
  },
  "security": [
    {
      "Bearer": [ ],
      "ApiKey": [ ]
    }
  ],
  "tags": [
    {
      "name": "FaceVerification"
    },
    {
      "name": "Health"
    }
  ]
}