> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a face > Adds a user-drawn face box to an asset, for a face the detector missed. To remove a face detection instead, use `delete_face`; to introduce a brand-new identity first, use `create_person`. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json post /api/faces openapi: 3.1.0 info: title: Gumnut API description: API for using Gumnut to manage photos and videos version: 0.1.0 servers: [] security: [] paths: /api/faces: post: tags: - faces summary: Create a face description: >- Adds a user-drawn face box to an asset, for a face the detector missed. To remove a face detection instead, use `delete_face`; to introduce a brand-new identity first, use `create_person`. operationId: create_face requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FaceCreate' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FaceResponse' '404': description: Not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: FaceCreate: properties: asset_id: type: string title: Asset Id description: >- ID of the asset (with `asset_` prefix) to draw the face box on. The asset must belong to the target library. bounding_box: $ref: '#/components/schemas/BoundingBoxInput' description: >- Where the face is, as a box in display-space pixels matching the asset's reported `width`/`height`. The box must fit inside those dimensions. person_id: anyOf: - type: string - type: 'null' title: Person Id description: >- Optional person ID (with `person_` prefix) to assign this face to at creation. Omit to leave it unassigned; assign it later via `update_face`. Use `create_person` first if the identity doesn't exist yet. library_id: anyOf: - type: string - type: 'null' title: Library Id description: >- Library to create the face in. Optional if the user has a single library; required when they have multiple. type: object required: - asset_id - bounding_box title: FaceCreate FaceResponse: properties: id: type: string title: Id description: Unique face identifier with 'face_' prefix asset_id: type: string title: Asset Id description: ID of the asset containing this face person_id: anyOf: - type: string - type: 'null' title: Person Id description: ID of the person this face belongs to (if identified) bounding_box: additionalProperties: type: integer type: object title: Bounding Box description: Face location as {x, y, w, h} coordinates in pixels confidence: anyOf: - type: number - type: 'null' title: Confidence description: >- Detector confidence on a 0-1 scale; higher is more confident among faces detected under the same configuration (values are not comparable across detector generations). Null on legacy faces without a stored score and on manually added faces. source: type: string enum: - automatic - manual title: Source description: >- How this face was added: 'automatic' for detector-found faces, 'manual' for user-drawn face boxes. timestamp_ms: anyOf: - type: integer - type: 'null' title: Timestamp Ms description: For video files, timestamp in milliseconds when face appears asset_urls: anyOf: - additionalProperties: $ref: '#/components/schemas/AssetVariant' type: object - type: 'null' title: Asset Urls description: 'Asset variants for this face: ''thumbnail'' with face crop' created_at: type: string format: date-time title: Created At description: When this face was detected and recorded updated_at: type: string format: date-time title: Updated At description: When this face record was last updated cluster_assignment: anyOf: - $ref: '#/components/schemas/ClusterAssignmentResponse' - type: 'null' description: >- Cluster-assignment diagnostics for this face. Populated only when `include=cluster_assignment` is requested on the faces endpoint; null otherwise. See `ClusterAssignmentResponse` for the shape. type: object required: - id - asset_id - bounding_box - source - created_at - updated_at title: FaceResponse description: Represents a detected face in an asset with facial recognition data. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BoundingBoxInput: properties: x: type: integer minimum: 0 title: X description: Left edge, in pixels from the asset's left side (0-based). 'y': type: integer minimum: 0 title: 'Y' description: Top edge, in pixels from the asset's top side (0-based). w: type: integer minimum: 1 title: W description: Box width in pixels. `x + w` must not exceed the asset's width. h: type: integer minimum: 1 title: H description: Box height in pixels. `y + h` must not exceed the asset's height. type: object required: - x - 'y' - w - h title: BoundingBoxInput description: |- A face bounding box in display-space pixels — the same coordinate space and resolution as the asset's reported ``width``/``height`` (post-EXIF, original resolution). AssetVariant: properties: url: type: string title: Url description: URL to fetch this image variant mimetype: type: string title: Mimetype description: MIME type of the served image width: anyOf: - type: integer - type: 'null' title: Width description: Target width in pixels (null if unknown) type: object required: - url - mimetype title: AssetVariant description: A single image variant with its URL, MIME type, and target width. ClusterAssignmentResponse: properties: distance_to_person: anyOf: - type: number - type: 'null' title: Distance To Person description: >- Cosine distance from the face's embedding to its currently-assigned Person's centroid. Lower = better fit. Null when the face is unassigned or when the assigned Person has no centroid. candidates: items: $ref: '#/components/schemas/FaceCandidatePersonResponse' type: array title: Candidates description: >- Persons in the same library that pass the same gate shape as production face assignment, surfaced with deliberately relaxed thresholds so the list is a superset of what the automated path would admit. Sorted ascending by distance. Excludes the face's currently-assigned Person (its distance is in `distance_to_person`). Empty when no eligible Persons pass the gate. type: object title: ClusterAssignmentResponse description: |- Per-face cluster-assignment diagnostics: how well the face fits its currently-assigned Person, and which other Persons are nearby in embedding space. Surfaced via ``include=cluster_assignment`` on the faces endpoints — used by the operator-facing face cleanup dashboard to triage mis-clustered faces. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError FaceCandidatePersonResponse: properties: person_id: type: string title: Person Id description: Person ID (with 'person_' prefix) of the candidate. name: anyOf: - type: string - type: 'null' title: Name description: >- Display name of the candidate Person, or null for unnamed clusters. Candidates surface the same Persons production assignment considers, which includes unnamed clusters. distance: type: number title: Distance description: >- Cosine distance from the face's embedding to this Person's centroid (lower = closer). type: object required: - person_id - distance title: FaceCandidatePersonResponse description: |- A Person whose centroid is close enough to a given face's embedding that it would be considered for assignment — surfaced under ``ClusterAssignmentResponse.candidates``. ````