openapi: 3.0.0
info:
  title: Api Face Matching
  description: >-
    Complete API collection for face verification and matching services.


    ## Features

    - Verify if two faces match using advanced AI models

    - Automatic face detection and comparison

    - High accuracy face matching with confidence scores

    - Support for various use cases and scenarios


    ## Authentication

    All requests require an API key in the `x-api-co-id` header.


    ## Base URL

    ```

    https://use.api.co.id/face-match

    ```


    ## File Requirements

    - **Supported formats**: JPG, JPEG, PNG

    - **Maximum file size**: 5 MB per image

    - **Content**: Images containing clear, visible faces


    ## Supported Use Cases


    ### 1. ID Card to Selfie Verification

    Compare a person's ID card photo with their current selfie photo. Ideal for:

    - Identity verification in onboarding processes

    - KYC (Know Your Customer) compliance

    - Account registration and authentication

    - Access control systems


    ### 2. Selfie to Selfie Comparison

    Compare two selfie photos to verify they are the same person. Useful for:

    - Multi-step verification processes

    - Profile photo updates verification

    - Account recovery procedures


    ### 3. ID Card to ID Card Comparison

    Compare photos from two different ID cards. Suitable for:

    - Document authenticity verification

    - Cross-reference identity checks

    - Duplicate detection


    ### 4. Profile Photo to Selfie Verification

    Compare a profile photo with a live selfie. Perfect for:

    - Social media account verification

    - Dating platform identity checks

    - Professional profile verification


    ### 5. Historical Photo Comparison

    Compare an old photo with a current selfie. Useful for:

    - Long-term identity verification

    - Age progression verification

    - Historical record matching


    ### 6. Group Photo Face Extraction

    Extract and compare faces from group photos. Ideal for:

    - Event attendance verification

    - Group membership validation

    - Photo tagging and organization


    ## Response Fields

    - **match**: Boolean indicating if faces match (true/false)

    - **confidence**: Float value (0.0 to 1.0) representing match confidence
    score


    ## Pricing

    - **Cost per successful verification**: 400 points

    - Charges apply only on successful API calls

    - Failed requests are not charged
  version: 1.0.0
servers:
  - url: https://use.api.co.id
tags:
  - name: Face Verification
    description: Face verification endpoints for comparing and matching faces in images.
paths:
  /face-match/verify:
    post:
      tags:
        - Face Verification
      summary: Verify Faces
      description: >-
        Verify if two faces match by comparing images. Maximum file size: 5 MB per image.
        Supported formats: JPG, JPEG, PNG. Both images should contain clear, visible faces.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image1
                - image2
              properties:
                image1:
                  type: string
                  format: binary
                  description: 'First image containing a face. Maximum size: 5 MB. Supported formats: JPG, JPEG, PNG'
                image2:
                  type: string
                  format: binary
                  description: 'Second image containing a face. Maximum size: 5 MB. Supported formats: JPG, JPEG, PNG'
      parameters:
        - name: x-api-co-id
          in: header
          schema:
            type: string
          description: Your API key for authentication
          example: '{{api_key}}'
      responses:
        '200':
          description: Success - Faces Verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  match:
                    type: boolean
                    description: Boolean indicating if faces match
                    example: true
                  confidence:
                    type: number
                    format: float
                    description: Confidence score from 0.0 to 1.0 (higher is better)
                    example: 0.95
              examples:
                Match:
                  summary: Faces Match
                  value:
                    match: true
                    confidence: 0.95
                No Match:
                  summary: Faces Do Not Match
                  value:
                    match: false
                    confidence: 0.25
        '400':
          description: Bad Request
          content:
            application/json:
              examples:
                Missing Files:
                  summary: Missing Required Files
                  value:
                    error: 'Missing required files: image1 and image2 are required'
                Invalid File Type:
                  summary: Invalid File Type
                  value:
                    error: 'Invalid file type. Supported formats: JPG, JPEG, PNG'
                File Too Large:
                  summary: File Too Large
                  value:
                    error: 'File size exceeds maximum limit of 5 MB'
                No Face Detected:
                  summary: No Face Detected
                  value:
                    error: 'No face detected in one or both images'
        '401':
          description: Unauthorized
          content:
            application/json:
              examples:
                Missing API Key:
                  summary: Missing API Key
                  value:
                    error: 'Missing API key in x-api-co-id header'
                Invalid API Key:
                  summary: Invalid API Key
                  value:
                    error: 'Invalid API key'
        '429':
          description: Too Many Requests
          content:
            application/json:
              examples:
                Rate Limit Exceeded:
                  summary: Rate Limit Exceeded
                  value:
                    error: 'Rate limit exceeded. Please try again later'
