Microsoft Azure Detect API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Detect API
schemes:
- https
tags:
- name: Detect
paths:
  /detect:
    post:
      description: 'Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br>* No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify), [Face - Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface), and [Face - Find Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar). The stored face feature(s) will expire and be deleted at the time specified by faceIdTimeToLive after the original detection call.<br>* Optional parameters include faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure, noise, mask, and qualityForRecognition. Some of the results returned for specific attributes may not be highly accurate.<br>* JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB.<br>* Up to 100 faces can be returned for an image. Faces are ranked by face rectangle size from large to small.<br>* For optimal results when querying [Face - Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify), [Face - Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface), and [Face - Find Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar) (''returnFaceId'' is true), please use faces that are: frontal, clear, and with a minimum size of 200x200 pixels (100 pixels between eyes).<br>* The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size.<br>* Different ''detectionModel'' values can be provided. To use and compare different detection models, please refer to [How to specify a detection model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model).<br><br>* Different ''recognitionModel'' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with ''recognitionModel'' parameter. The default value for ''recognitionModel'' is ''recognition_01'', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [Specify a recognition model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).'
      operationId: microsoftAzureFaceDetectwithurl
      parameters:
      - $ref: '#/parameters/returnFaceId'
      - $ref: '#/parameters/returnFaceLandmarks'
      - $ref: '#/parameters/returnFaceAttributes'
      - $ref: ../../../Common/Parameters.json#/parameters/ImageUrl
      - $ref: '#/parameters/recognitionModel'
      - $ref: '#/parameters/returnRecognitionModel'
      - $ref: '#/parameters/detectionModel'
      - $ref: '#/parameters/faceIdTimeToLive'
      consumes:
      - application/json
      produces:
      - application/json
      responses:
        '200':
          description: A successful call returns an array of face entries ranked by face rectangle size in descending order. An empty response indicates no faces detected.
          schema:
            $ref: '#/definitions/DetectedFaces'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/APIError'
      x-ms-examples:
        Detect with url example:
          $ref: ./examples/DetectWithUrl.json
      summary: Microsoft Azure Post Detect
      tags:
      - Detect
  /Detect:
    post:
      description: Identifies the language of a string of text.<br>
      tags:
      - Detect
      operationId: microsoftAzureTranslatorDetect
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - $ref: '#/parameters/ApiVersion'
      - name: X-ClientTraceId
        description: A client-generated GUID to uniquely identify the request. Note that you can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.
        in: header
        required: false
        type: string
      - name: text
        description: '# Request Body

          The body of the request is a JSON array. Each array element is a JSON object with a string property named Text. Language detection is applied to the value of the Text property.

          The following limitations apply:

          * The array can have at most 100 elements.

          * The text value of an array element cannot exceed 10,000 characters including spaces.

          * The entire text included in the request cannot exceed 50,000 characters including spaces.


          # Response Body

          A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:

          * language- Code of the detected language.

          * score- A float value indicating the confidence in the result. The score is between zero and one and a low score indicates a low confidence.

          * isTranslationSupported- A boolean value which is true if the detected language is one of the languages supported for text translation. Not all detected languages can be translated by the API.

          * isTransliterationSupported- A boolean value which is true if the detected language is one of the languages supported for transliteration.

          * alternatives- An array of other possible languages. Each element of the array is another object with the same properties listed above- language, score, isTranslationSupported and isTransliterationSupported.

          # Response Header

          X-RequestId - Value generated by the service to identify the request. It is used for troubleshooting purposes.

          '
        in: body
        required: true
        schema:
          type: array
          items:
            $ref: '#/definitions/DetectTextInput'
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/DetectResult'
        default:
          description: Error response.
          schema:
            $ref: '#/definitions/ErrorMessage'
      x-ms-examples:
        Detect success example:
          $ref: ./examples/detectSuccess.json
      deprecated: false
      summary: Microsoft Azure Post Detect
definitions:
  HairColor:
    type: object
    description: Hair color and associated confidence
    properties:
      color:
        type: string
        description: Name of the hair color.
        x-nullable: false
        x-ms-enum:
          name: HairColorType
          modelAsString: false
        enum:
        - unknown
        - white
        - gray
        - blond
        - brown
        - red
        - black
        - other
      confidence:
        x-nullable: false
        description: Confidence level of the color
        $ref: '#/definitions/Confidence'
  Accessory:
    type: object
    description: Accessory item and corresponding confidence level.
    properties:
      type:
        type: string
        description: Type of an accessory
        x-nullable: false
        x-ms-enum:
          name: AccessoryType
          modelAsString: false
        enum:
        - headWear
        - glasses
        - mask
      confidence:
        x-nullable: false
        description: Confidence level of an accessory
        $ref: '#/definitions/Confidence'
  ErrorMessage:
    type: object
    properties:
      error:
        type: object
        properties:
          code:
            type: string
          message:
            type: string
  APIError:
    type: object
    description: Error information returned by the API
    properties:
      error:
        $ref: '#/definitions/Error'
  Exposure:
    type: object
    description: Properties describing exposure level of the image.
    properties:
      exposureLevel:
        type: string
        description: An enum value indicating level of exposure.
        x-nullable: false
        x-ms-enum:
          name: ExposureLevel
          modelAsString: false
        enum:
        - UnderExposure
        - GoodExposure
        - OverExposure
      value:
        description: A number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure.
        x-nullable: false
        $ref: '#/definitions/Level'
  Blur:
    type: object
    description: Properties describing any presence of blur within the image.
    properties:
      blurLevel:
        type: string
        description: An enum value indicating level of blurriness.
        x-nullable: false
        x-ms-enum:
          name: BlurLevel
          modelAsString: false
        enum:
        - Low
        - Medium
        - High
      value:
        description: A number indicating level of blurriness ranging from 0 to 1.
        x-nullable: false
        $ref: '#/definitions/Level'
  HeadPose:
    type: object
    description: Properties indicating head pose of the face.
    properties:
      roll:
        type: number
        x-nullable: false
      yaw:
        type: number
        x-nullable: false
      pitch:
        type: number
        x-nullable: false
  FaceLandmarks:
    type: object
    description: A collection of 27-point face landmarks pointing to the important positions of face components.
    properties:
      pupilLeft:
        $ref: '#/definitions/Coordinate'
      pupilRight:
        $ref: '#/definitions/Coordinate'
      noseTip:
        $ref: '#/definitions/Coordinate'
      mouthLeft:
        $ref: '#/definitions/Coordinate'
      mouthRight:
        $ref: '#/definitions/Coordinate'
      eyebrowLeftOuter:
        $ref: '#/definitions/Coordinate'
      eyebrowLeftInner:
        $ref: '#/definitions/Coordinate'
      eyeLeftOuter:
        $ref: '#/definitions/Coordinate'
      eyeLeftTop:
        $ref: '#/definitions/Coordinate'
      eyeLeftBottom:
        $ref: '#/definitions/Coordinate'
      eyeLeftInner:
        $ref: '#/definitions/Coordinate'
      eyebrowRightInner:
        $ref: '#/definitions/Coordinate'
      eyebrowRightOuter:
        $ref: '#/definitions/Coordinate'
      eyeRightInner:
        $ref: '#/definitions/Coordinate'
      eyeRightTop:
        $ref: '#/definitions/Coordinate'
      eyeRightBottom:
        $ref: '#/definitions/Coordinate'
      eyeRightOuter:
        $ref: '#/definitions/Coordinate'
      noseRootLeft:
        $ref: '#/definitions/Coordinate'
      noseRootRight:
        $ref: '#/definitions/Coordinate'
      noseLeftAlarTop:
        $ref: '#/definitions/Coordinate'
      noseRightAlarTop:
        $ref: '#/definitions/Coordinate'
      noseLeftAlarOutTip:
        $ref: '#/definitions/Coordinate'
      noseRightAlarOutTip:
        $ref: '#/definitions/Coordinate'
      upperLipTop:
        $ref: '#/definitions/Coordinate'
      upperLipBottom:
        $ref: '#/definitions/Coordinate'
      underLipTop:
        $ref: '#/definitions/Coordinate'
      underLipBottom:
        $ref: '#/definitions/Coordinate'
  FaceRectangle:
    type: object
    required:
    - width
    - height
    - left
    - top
    description: A rectangle within which a face can be found
    properties:
      width:
        type: integer
        format: int32
        description: The width of the rectangle, in pixels.
      height:
        type: integer
        format: int32
        description: The height of the rectangle, in pixels.
      left:
        type: integer
        format: int32
        description: The distance from the left edge if the image to the left edge of the rectangle, in pixels.
      top:
        type: integer
        format: int32
        description: The distance from the top edge if the image to the top edge of the rectangle, in pixels.
  DetectTextInput:
    type: object
    description: 'Text needed for detect request '
    properties:
      text:
        type: string
        maximum: 10000
    example:
      text: What language is this? I am not sure, nein
  Occlusion:
    type: object
    description: Properties describing occlusions on a given face.
    properties:
      foreheadOccluded:
        type: boolean
        description: A boolean value indicating whether forehead is occluded.
        x-nullable: false
      eyeOccluded:
        type: boolean
        description: A boolean value indicating whether eyes are occluded.
        x-nullable: false
      mouthOccluded:
        type: boolean
        description: A boolean value indicating whether the mouth is occluded.
        x-nullable: false
  DetectedFaces:
    type: array
    items:
      $ref: '#/definitions/DetectedFace'
  FaceAttributes:
    type: object
    description: Face Attributes
    properties:
      age:
        type: number
        description: Age in years
      gender:
        type: string
        description: Possible gender of the face.
        x-ms-enum:
          name: Gender
          modelAsString: false
        enum:
        - male
        - female
      smile:
        description: 'Smile intensity, a number between [0,1] '
        $ref: '#/definitions/Level'
      facialHair:
        description: Properties describing facial hair attributes.
        $ref: '#/definitions/FacialHair'
      glasses:
        type: string
        description: Glasses type if any of the face.
        x-ms-enum:
          name: GlassesType
          modelAsString: false
        enum:
        - noGlasses
        - readingGlasses
        - sunglasses
        - swimmingGoggles
      headPose:
        description: Properties indicating head pose of the face.
        $ref: '#/definitions/HeadPose'
      emotion:
        description: Properties describing facial emotion in form of confidence ranging from 0 to 1.
        $ref: '#/definitions/Emotion'
      hair:
        description: Properties describing hair attributes.
        $ref: '#/definitions/Hair'
      makeup:
        description: Properties describing the presence of makeup on a given face.
        $ref: '#/definitions/Makeup'
      occlusion:
        description: Properties describing occlusions on a given face.
        $ref: '#/definitions/Occlusion'
      accessories:
        description: Properties describing any accessories on a given face.
        $ref: '#/definitions/Accessories'
      blur:
        description: Properties describing any presence of blur within the image.
        $ref: '#/definitions/Blur'
      exposure:
        description: Properties describing exposure level of the image.
        $ref: '#/definitions/Exposure'
      noise:
        description: Properties describing noise level of the image.
        $ref: '#/definitions/Noise'
      mask:
        description: Properties describing the presence of a mask on a given face.
        $ref: '#/definitions/Mask'
      qualityForRecognition:
        type: string
        description: Properties describing the overall image quality regarding whether the image being used in the detection is of sufficient quality to attempt face recognition on.
        x-ms-enum:
          name: QualityForRecognition
          modelAsString: false
        enum:
        - Low
        - Medium
        - High
  Emotion:
    type: object
    description: Properties describing facial emotion in form of confidence ranging from 0 to 1.
    properties:
      anger:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      contempt:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      disgust:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      fear:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      happiness:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      neutral:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      sadness:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      surprise:
        x-nullable: false
        $ref: '#/definitions/Confidence'
  HairColors:
    type: array
    items:
      $ref: '#/definitions/HairColor'
  Makeup:
    type: object
    description: Properties describing the presence of makeup on a given face.
    properties:
      eyeMakeup:
        type: boolean
        description: A boolean value describing whether eye makeup is present on a face.
        x-nullable: false
      lipMakeup:
        type: boolean
        description: A boolean value describing whether lip makeup is present on a face.
        x-nullable: false
  DetectedFace:
    type: object
    required:
    - faceRectangle
    description: Detected Face object.
    properties:
      faceId:
        type: string
        format: uuid
      recognitionModel:
        $ref: '#/definitions/RecognitionModel'
      faceRectangle:
        $ref: '#/definitions/FaceRectangle'
      faceLandmarks:
        $ref: '#/definitions/FaceLandmarks'
      faceAttributes:
        $ref: '#/definitions/FaceAttributes'
  FacialHair:
    type: object
    description: Properties describing facial hair attributes.
    properties:
      moustache:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      beard:
        x-nullable: false
        $ref: '#/definitions/Confidence'
      sideburns:
        x-nullable: false
        $ref: '#/definitions/Confidence'
  Mask:
    type: object
    description: Properties describing the presence of a mask on a given face.
    properties:
      type:
        type: string
        description: Mask type if any of the face
        x-nullable: false
        x-ms-enum:
          name: MaskType
          modelAsString: false
        enum:
        - noMask
        - faceMask
        - otherMaskOrOcclusion
        - uncertain
      noseAndMouthCovered:
        type: boolean
        description: A boolean value indicating whether nose and mouth are covered.
        x-nullable: false
  DetectResult:
    type: array
    description: Example of a successful detect request
    items:
      type: object
      properties:
        text:
          type: string
  Coordinate:
    type: object
    required:
    - x
    - y
    description: Coordinates within an image
    properties:
      x:
        type: number
        description: The horizontal component, in pixels.
      y:
        type: number
        description: The vertical component, in pixels.
  Noise:
    type: object
    description: Properties describing noise level of the image.
    properties:
      noiseLevel:
        type: string
        description: An enum value indicating level of noise.
        x-nullable: false
        x-ms-enum:
          name: NoiseLevel
          modelAsString: false
        enum:
        - Low
        - Medium
        - High
      value:
        description: A number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level.
        x-nullable: false
        $ref: '#/definitions/Level'
  Accessories:
    type: array
    description: Properties describing any accessories on a given face.
    items:
      $ref: '#/definitions/Accessory'
  Error:
    type: object
    description: Error body.
    properties:
      code:
        type: string
      message:
        type: string
  Level:
    description: A number ranging from 0 to 1 indicating the intensity level associated with a property.
    type: number
    minimum: 0
    maximum: 1
  RecognitionModel:
    type: string
    description: Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.
    default: recognition_01
    x-nullable: false
    x-ms-enum:
      name: RecognitionModel
      modelAsString: true
    enum:
    - recognition_01
    - recognition_02
    - recognition_03
    - recognition_04
  Hair:
    type: object
    description: Properties describing hair attributes.
    properties:
      bald:
        description: A number describing confidence level of whether the person is bald.
        x-nullable: false
        $ref: '#/definitions/Confidence'
      invisible:
        type: boolean
        description: A boolean value describing whether the hair is visible in the image.
        x-nullable: false
      hairColor:
        description: An array of candidate colors and confidence level in the presence of each.
        $ref: '#/definitions/HairColors'
  Confidence:
    description: A number ranging from 0 to 1 indicating a level of confidence associated with a property.
    type: number
    minimum: 0
    maximum: 1
parameters:
  detectionModel:
    name: detectionModel
    description: Name of detection model. Detection model is used to detect faces in the submitted image. A detection model name can be provided when performing Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add Face. The default value is 'detection_01', if another model is needed, please explicitly specify it.
    default: detection_01
    required: false
    type: string
    in: query
    x-ms-parameter-location: method
    x-nullable: false
    x-ms-enum:
      name: DetectionModel
      modelAsString: true
    enum:
    - detection_01
    - detection_02
    - detection_03
  recognitionModel:
    name: recognitionModel
    description: Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need.
    default: recognition_01
    required: false
    type: string
    in: query
    x-ms-parameter-location: method
    x-nullable: false
    x-ms-enum:
      name: RecognitionModel
      modelAsString: true
    enum:
    - recognition_01
    - recognition_02
    - recognition_03
    - recognition_04
  returnFaceAttributes:
    name: returnFaceAttributes
    in: query
    description: Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". The available attributes depends on the 'detectionModel' specified. 'detection_01' supports age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure, noise, and qualityForRecognition. While 'detection_02' does not support any attributes and 'detection_03' only supports mask and qualityForRecognition. Additionally, qualityForRecognition is only supported when the 'recognitionModel' is specified as 'recognition_03' or 'recognition_04'. Note that each face attribute analysis has additional computational and time cost.
    type: array
    x-ms-parameter-location: method
    required: false
    collectionFormat: csv
    items:
      type: string
      x-nullable: false
      x-ms-enum:
        name: FaceAttributeType
        modelAsString: false
      enum:
      - age
      - gender
      - headPose
      - smile
      - facialHair
      - glasses
      - emotion
      - hair
      - makeup
      - occlusion
      - accessories
      - blur
      - exposure
      - noise
      - mask
      - qualityForRecognition
  returnFaceId:
    name: returnFaceId
    in: query
    x-ms-parameter-location: method
    description: A value indicating whether the operation should return faceIds of detected faces. Detecting with this value set to true requires additional access approvals at https://aka.ms/facerecognition.
    type: boolean
  returnFaceLandmarks:
    name: returnFaceLandmarks
    in: query
    x-ms-parameter-location: method
    description: A value indicating whether the operation should return landmarks of the detected faces.
    type: boolean
    default: false
  faceIdTimeToLive:
    name: faceIdTimeToLive
    in: query
    x-ms-parameter-location: method
    description: The number of seconds for the faceId being cached. Supported range from 60 seconds up to 86400 seconds. The default value is 86400 (24 hours).
    type: integer
    default: 86400
    minimum: 60
    maximum: 86400
  ApiVersion:
    name: api-version
    description: Version of the API requested by the client. Value must be **3.0**.
    in: query
    required: true
    type: string
    default: '3.0'
  returnRecognitionModel:
    name: returnRecognitionModel
    description: A value indicating whether the operation should return 'recognitionModel' in response.
    default: false
    required: false
    type: boolean
    in: query
    x-ms-parameter-location: method
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'