FaceSDK-web-openapi/match_and_search.yml at develop · regulaforensics/FaceSDK-web-openapi · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
openapi: 3.0.4

paths:
  /match_and_search:
    parameters:
      - $ref: "./common.yml#/components/parameters/x-request"
    post:
      tags:
        - match
      summary: "match and search (1:1 + 1:N)"
      description: "To compare several images from a document and look up a person in the database in one request, use POST `/api/match_and_search`. In this case, the calculation of the descriptor will be performed only once, as opposed to using two requests for the same operation. At least two photos are required. If, after processing two or more photos, only one face is detected across them, the match step is skipped, and only the search is carried out."
      operationId: match_and_search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MatchAndSearchRequest"
      responses:
        200:
          description: "Successful operation; the compare results are returned."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MatchAndSearchResponse"
        403:
          $ref: "./common.yml#/components/responses/BadLicense"

components:
  schemas:
    MatchAndSearchRequest:
      title: "MatchAndSearchRequest"
      type: object
      properties:
        tag:
          type: string
          description: "Session identificator, should be unique for each session."
        images:
          type: array
          description: "An array of images to be processed. At least two images must be provided."
          items:
            $ref: "#/components/schemas/MatchAndSearchRequestImagesItem"
        groupIds:
          type: array
          description: "IDs of the groups in which the search is performed."
          items:
            type: string
            format: uuid
        threshold:
          description: "The similarity threshold."
          type: number
        limit:
          description: "The maximum number of results to be returned."
          type: integer
        tenant:
          type: string
          description: "A label used to group transactions by customers, applications, or other criteria."
        env:
          type: string
          description: "A label used to differentiate transactions by development stages."

    MatchAndSearchRequestImagesItem:
      title: "MatchAndSearchRequestImagesItem"
      type: object
      properties:
        content:
          $ref: "./common.yml#/components/schemas/ImageData"
        imageUrl:
          description: "Image URL."
          type: string
        type:
          $ref: "./common.yml#/components/schemas/ImageSource"

    MatchAndSearchResponse:
      title: "MatchAndSearchResponse"
      allOf:
        - $ref: "./common.yml#/components/schemas/FaceSDKResult"
        - $ref: "#/components/schemas/MatchAndSearchResponseData"

    MatchAndSearchResponseData:
      title: "MatchAndSearchResponseData"
      type: object
      properties:
        results:
          type: array
          description: "The match and search results."
          items:
            $ref: "./match.yml#/components/schemas/MatchImageResult"
        elapsedTime:
          type: number
          description: "Server processing time, ms. Does not include the time taken to receive the request or deliver the response."
          format: float
          example: 1.317137987
        metadata:
          type: object
          additionalProperties: true
          description: "A free-form object containing person's extended attributes."
        detections:
          type: array
          description: "The detection results."
          items:
            $ref: "#/components/schemas/MatchAndSearchResponseDataDetectionsItem"

    MatchAndSearchResponseDataDetectionsItem:
      title: "MatchAndSearchResponseDataDetectionsItem"
      type: object
      properties:
        faces:
          type: array
          description: "Detected faces."
          items:
            $ref: "#/components/schemas/FacesResponse"
        imageIndex:
          $ref: "./match.yml#/components/schemas/MatchImageIndex"
        status:
          $ref: "./common.yml#/components/schemas/FaceSDKResultCode"

    PersonWithImages:
      title: "PersonWithImages"
      allOf:
        - $ref: "#/components/schemas/PersonWithImagesData"
        - $ref: "./identification.yml#/components/schemas/Person"

    PersonWithImagesData:
      title: "PersonWithImagesData"
      type: object
      properties:
        images:
          type: array
          description: "Detected Persons."
          items:
            $ref: "./search.yml#/components/schemas/RecognizeImage"

    FacesResponse:
      title: "FacesResponse"
      allOf:
        - $ref: "./match.yml#/components/schemas/DetectionFace"
        - $ref: "#/components/schemas/FacesResponseData"

    FacesResponseData:
      title: "FacesResponseData"
      type: object
      properties:
        persons:
          type: array
          description: "Detected Persons."
          items:
            $ref: "#/components/schemas/PersonWithImages"