openapi: 3.0.0
info:
  title: AI Makeup Virtual Try-On API (v1.8)
  description: >-
    The AI Makeup API provides a powerful, hyper-realistic virtual makeover
    experience powered by patented face-analyzing technology. This service
    enables applications to apply true-to-life makeup effects onto user-provided
    selfie images with unprecedented customization capabilities.
  version: 1.0.0
servers:
  - url: https://api.example.com/v2.0
    description: Production server
paths:
  /task/makeup-vto:
    post:
      summary: Apply virtual makeup to a photo
      description: >
        Apply hyper-realistic makeup effects to user photos with customizable
        options.


        Key Features:

        - Hyper-realistic Rendering: Leverages revolutionary 3D face AI
        technology

        - Patented Technology: Powered by jitter-free, lag-free deep learning
        algorithms

        - Real-time Precision: Ultra-precise facial tracking

        - True-to-life Matching: Accurately matches real-world product colors
        and textures
      operationId: applyMakeupVTO
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MakeupVTORequest'
      responses:
        '200':
          description: Task created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    MakeupVTORequest:
      type: object
      required:
        - effects
      oneOf:
        - required:
            - src_file_url
          properties:
            src_file_url:
              type: string
              description: >-
                URL of the file to process. The URL should be publicly
                accessible.
              example: https://example.com/selfie.jpg
        - required:
            - src_file_id
          properties:
            src_file_id:
              type: string
              description: ID of file from upload file API.
              example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
      properties:
        version:
          type: string
          default: '1.0'
          description: Version of the makeup effect specification.
          example: '1.0'
        effects:
          type: array
          description: >-
            Array of makeup effects to apply. Each effect object MUST specify a
            category and match the schema for that makeup type.
          items:
            oneOf:
              - $ref: '#/components/schemas/SkinSmoothEffect'
              - $ref: '#/components/schemas/BlushEffect'
              - $ref: '#/components/schemas/BronzerEffect'
              - $ref: '#/components/schemas/ConcealerEffect'
              - $ref: '#/components/schemas/ContourEffect'
              - $ref: '#/components/schemas/EyebrowsEffect'
              - $ref: '#/components/schemas/EyelinerEffect'
              - $ref: '#/components/schemas/EyeshadowEffect'
              - $ref: '#/components/schemas/EyelashesEffect'
              - $ref: '#/components/schemas/FoundationEffect'
              - $ref: '#/components/schemas/HighlighterEffect'
              - $ref: '#/components/schemas/LipColorEffect'
              - $ref: '#/components/schemas/LipLinerEffect'
    SkinSmoothEffect:
      type: object
      required:
        - category
      properties:
        category:
          type: string
          enum:
            - skin_smooth
          description: Must always be "skin_smooth"
        skinSmoothStrength:
          type: integer
          minimum: 0
          maximum: 100
          default: 50
          description: Strength of smoothing applied to overall skin texture
        skinSmoothColorIntensity:
          type: integer
          minimum: 0
          maximum: 100
          default: 50
          description: Intensity of color blending applied during smoothing
    BlushEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - blush
        pattern:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: Name of the blush pattern
        palettes:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - color
              - texture
              - colorIntensity
            properties:
              color:
                type: string
                pattern: ^#?[0-9A-Fa-f]{6}$
                description: Primary blush color in hex format
              texture:
                type: string
                enum:
                  - matte
                  - satin
                  - shimmer
              colorIntensity:
                type: integer
                minimum: 0
                maximum: 100
              glowStrength:
                type: integer
                minimum: 0
                maximum: 100
                nullable: true
              shimmerColor:
                type: string
                nullable: true
              shimmerDensity:
                type: integer
                minimum: 0
                maximum: 100
                nullable: true
    BronzerEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - bronzer
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    ConcealerEffect:
      type: object
      required:
        - category
        - palettes
      properties:
        category:
          type: string
          enum:
            - concealer
        palettes:
          type: array
          items:
            type: object
    ContourEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - contour
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    EyebrowsEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - eyebrows
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    EyelinerEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - eye_liner
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    EyeshadowEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - eye_shadow
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    EyelashesEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - eyelashes
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    FoundationEffect:
      type: object
      required:
        - category
        - palettes
      properties:
        category:
          type: string
          enum:
            - foundation
        palettes:
          type: array
          items:
            type: object
    HighlighterEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - highlighter
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    LipColorEffect:
      type: object
      required:
        - category
        - shape
        - palettes
        - style
      properties:
        category:
          type: string
          enum:
            - lip_color
        shape:
          type: object
        palettes:
          type: array
          items:
            type: object
        style:
          type: object
        morphology:
          type: object
          nullable: true
    LipLinerEffect:
      type: object
      required:
        - category
        - pattern
        - palettes
      properties:
        category:
          type: string
          enum:
            - lip_liner
        pattern:
          type: object
        palettes:
          type: array
          items:
            type: object
    TaskResponse:
      type: object
      properties:
        task_id:
          type: string
          description: Unique identifier for the task
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        results:
          type: object
          properties:
            url:
              type: string
              description: URL to the processed image
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
