openapi: 3.0.0
info:
  title: AI Nail Transfer
  description: >
    # Overview

    AI Nail Transfer API is a powerful generative AI solution for virtual nail
    try-on experiences. Powered by YouCam API’s advanced AI models and image
    transformation technology, users can instantly transfer any desired nail
    design from a reference photo onto their own hand with remarkable realism
    and precision.


    From gel nails, nail art, and polish finishes to intricate embellishments
    such as glitter, shell accents, and metallic textures, the AI accurately
    recreates a wide range of nail styles in a natural, high-definition virtual
    preview. This enables consumers to explore and visualize designs with
    confidence before making a purchase.


    For beauty brands, salons, and nail artists, AI Nail Transfer API provides a
    fast and engaging way to showcase nail designs to clients, helping increase
    customer engagement, improve satisfaction, and drive higher conversion rates
    through immersive virtual experiences.


    ![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg)


    ## Integration Guide

    This guide walks you through:


    Workflow for AI Nail Transfer API:


    **Endpoint:** `/s2s/v2.0/task/ai-nail`


    **Authentication Required:** `Authorization: Bearer YOUR_API_KEY`


    **Workflow Steps:**


    1. **Image Upload Preparation:**

    - The process begins with preparing a hand image via the File API to
    `/s2s/v2.0/file`.


    2. **Reference Photo Upload:**

    - Upload a reference photo featuring your desired nail design via the File
    API to `/s2s/v2.0/file`. For best results, ensure all fingernails are
    clearly visible.


    1. **Initiate AI Task and Obtain Task ID:**

    - Send the uploaded image(s) via an HTTP POST request to
    `/s2s/v2.0/task/ai-nail`.

    - Await a unique `task_id` in the response, which identifies this
    interaction.


    1. **Poll Task Status (Continuous Check):**

    - Use the obtained `task_id` to periodically poll the task status using an
    HTTP GET request (e.g., `GET /task/${task_id}`).

    - Continuously monitor for:

    - `Task_status = "success"` (process completed).

    - `Task_status = "error"` (resolve or retry if applicable).

    - Update the workflow accordingly once the status transitions to success.


    This structured workflow ensures efficient integration with user inputs,
    automated monitoring of tasks, and seamless retrieval of results.


    ---


    * Authentication

    - Include your API key in the request header using **Bearer Token**:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```

    You can find your API Key at
    https://yce.makeupar.com/api-console/en/api-keys/.



    * 1. Upload an Image


    You may upload a file directly to the server or provide a valid image URL in
    the AI task payload.


    * Upload Endpoint


    ```

    POST /s2s/v2.0/file

    ```


    Alternatively, skip this step if you already have a public image URL.


    ---


    * 2. Upload a reference photo


    You may upload a file directly to the server or provide a valid image URL in
    the AI task payload. Ensure all fingernails are visible for the most
    accurate virtual try-on experience.


    * Upload Endpoint


    ```

    POST /s2s/v2.0/file

    ```


    ---


    * 3. Create a AI Nail Transfer AI Task and Poll for Results


    Once you have an image and a complete effect payload, create a task. The API
    processes the request asynchronously. You must poll the task status until it
    reaches `success` or `error`.


    * Create Task Endpoint


    ```

    POST /s2s/v2.0/task/ai-nail

    ```


    * Polling Endpoint


    ```

    GET /s2s/v2.0/task/ai-nail/{task_id}

    ```


    ---


    ## File Specs & Errors


    * AI Nail Transfer Specification

        **Supported hand view**

        Supports up to two hands per image. Additional hands will be ignored. For optimal detection, each hand should occupy at least 0.5% of the image area (approximately 102×102 px in FHD, 139×139 px in 2K, and 204×204 px in 4K images).

        ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png)


        **Supported reference image**

        ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_6_341b11df3d.png)

        ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_2_86a47c1c26.png)

    ---


    * Supported Formats & Dimensions


    |AI Feature|Supported Dimensions|Supported File Size|Supported Formats|

    | ---- | ---- | ---- | ---- |

    | AI Nail Transfer | long side <= 4096 | < 10MB | jpg/jpeg/png |


    * Error Codes


    | Error Code | Description |

    | ---- | ---- |

    | exceed_max_filesize | Image file is too large |

    | invalid_parameter | The input parameters are missing or in wrong format |

    | error_download_image | File upload was not complete or the image URL is
    invalid |

    | error_inference | The inference was failed, please check if the input and
    reference images are supported |

    | no_hand_detected | No hand is detected in the source image |



    * Environment & Dependency


    | Sample Code Language / Tool | Recommended Runtime Versions |

    |---|---|

    | cURL | - bash >= 3.2</br>- curl >= 7.58 (modern TLS/HTTP support)</br>- jq
    >= 1.6 (robust JSON parsing) |

    | Node.js (JavaScript) | Node >= 18 (for global fetch) |

    | JavaScript | - Chrome / Edge >= 80</br>- Firefox >= 74</br>- Safarin b\

    | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) orn
    b\_fopen=On + ext-openssl, ext-json |

    | Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |

    | Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |


    ---


    ## Unit Consumption


    | AI Feature | Unit Consumed |

    |---|---|

    | AI Nail Transfer V1.0 | 1 |


    ---
  version: ''
  termsOfService: https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api
  contact:
    email: YouCamOnlineEditor_API@perfectcorp.com
  license:
    name: Privacy policy
    url: https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api
servers:
  - url: https://yce-api-01.makeupar.com
tags:
  - name: V1.0
    description: >-
      Transform reference nail designs into hyper-realistic hand previews using
      advanced AI technology.
paths:
  /s2s/v2.0/task/ai-nail:
    post:
      summary: Run an AI Nail Transfer task.
      x-display-name: AI Nail Transfer
      x-engine-version: V1.0
      description: >
        AI tasks are asynchronous. Prefer webhook-based completion handling when
        the feature supports webhooks. Configure your webhook endpoint, verify
        webhook signatures, and use the received `task_id` to query the task
        result after a `success` or `error` notification. See the [webhook
        integration guide](/develop/webhook.md) for setup and verification
        details.


        If webhooks are not supported for the feature, or if your integration
        cannot use webhooks, implement polling. After starting an AI task, keep
        polling the task status endpoint at the given `polling_interval` until
        the task status is either `success` or `error`.


        Do not stop polling a running task for longer than the allowed polling
        window. If the task is not polled in time, the task may expire; a later
        status check can return `InvalidTaskId` even if processing finished, and
        the consumed units may still be charged.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BasicRunTaskV2WithRequiredRef'
      responses:
        '200':
          description: Successful execution of the task
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicRunTaskResponseV2'
        '400':
          description: Failed execution of task
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/RunError'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /s2s/v2.0/task/ai-nail/{task_id}:
    get:
      summary: Check the status of a AI Nail Transfer task.
      x-display-name: AI Nail Transfer
      x-engine-version: V1.0
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
          description: ID of task to check
      responses:
        '200':
          description: Successful check of the task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponseV2'
        '400':
          $ref: '#/components/responses/InvalidTaskId'
        '401':
          $ref: '#/components/responses/InvalidApiKey'
        '500':
          $ref: '#/components/responses/TaskTimeout'
components:
  securitySchemes:
    BearerAuthenticationV2:
      type: http
      scheme: bearer
      description: >-
        Use the standard 'Bearer authentication'. Put your 'API Key' in header:
        `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space
        between 'Bearer' and the 'YOUR_API_KEY'.
  schemas:
    BasicRunTaskV2SrcFileUrl:
      type: object
      required:
        - src_file_url
      properties:
        src_file_url:
          type: string
          description: Url of the file to run task. The url should be publicly accessible.
          example: https://example.com/selfie.jpg
    BasicRunTaskV2RefFileUrl:
      type: object
      properties:
        ref_file_url:
          type: string
          description: >-
            Url of the reference file to run task. The url should be publicly
            accessible.
          example: https://example.com/accessory.jpg
    BasicRunTaskV2RefFileId:
      type: object
      properties:
        ref_file_id:
          type: string
          description: ID of the reference file to run task. File ID from upload file API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
    BasicRunTaskV2SrcFileId:
      type: object
      required:
        - src_file_id
      properties:
        src_file_id:
          type: string
          description: ID of file to run task. File ID from upload file API.
          example: pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=
    BasicRunTaskV2WithRequiredRef:
      title: BasicRunTaskV2WithRef
      anyOf:
        - allOf:
            - title: Run task with src file url & ref file url
              required:
                - ref_file_url
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileUrl'
        - allOf:
            - title: Run task with src file url & ref file ID
              required:
                - ref_file_id
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileId'
        - allOf:
            - title: Run task with src file ID & ref file url
              required:
                - ref_file_url
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileUrl'
        - allOf:
            - title: Run task with src file ID & ref file ID
              required:
                - ref_file_id
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
            - $ref: '#/components/schemas/BasicRunTaskV2RefFileId'
    BasicRunTaskResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_id:
              type: string
              description: >-
                ID of this task. Task result is valid to query by this ID for 24
                hours.
              example: grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe
    RunError:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 400
        error:
          type: string
          description: Error message
          example: The operation could not be completed
        error_code:
          type: string
          enum:
            - InvalidParameters
            - CreditInsufficiency
            - InvalidStyleGroup
            - InvalidStyle
            - BadRequest
          description: |
            Error code:
              * InvalidParameters - Invalid request parameters
              * CreditInsufficiency - Insufficient unit to run
              * BadRequest - Unexpected request parameter
              * InvalidStyleGroup - Invalid style group id
              * InvalidStyle - Invalid style id
    EngineErrorCode:
      type: string
      nullable: true
      enum:
        - error_exceed_max_image_size
        - exceed_max_filesize
        - invalid_parameter
        - error_download_image
        - error_download_mask
        - error_decode_image
        - error_decode_mask
        - error_nsfw_content_detected
        - error_no_face
        - error_pose
        - error_face_parsing
        - error_inference
        - exceed_nsfw_retry_limits
        - error_upload
        - unknown_internal_error
      description: >
        Errors:

        - \`error_exceed_max_image_size\`  - Input image size exceeds the
        maximum limit

        - \`exceed_max_filesize\` - Input file size exceeds the maximum limit

        - \`invalid_parameter\` - Invalid parameter value

        - \`error_download_image\` - Download source image error

        - \`error_download_mask\` - Download mask image error

        - \`error_decode_image\` - Decode source image error

        - \`error_decode_mask\` - Decode mask image error

        - \`error_nsfw_content_detected\` - NSFW content detected in source
        image

        - \`error_no_face\` - No face detected on source image

        - \`error_pose\` - Failed to detect pose on source image

        - \`error_face_parsing\` - Failed to do face segmentation on source
        image

        - \`error_inference\` - Inference pipeline error

        - \`exceed_nsfw_retry_limits\` - Exceed the retry limits to avoid
        generated NSFW image

        - \`error_upload\` - Upload result image error

        - \`unknown_internal_error\` - Others
    TaskStatusResponseBodySingleUrlResultsV2:
      type: object
      properties:
        url:
          type: string
          description: URL to download this result. Valid for 2 hours
          example: https://example.com/sample-result-url
    TaskStatusResponseV2:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            task_status:
              type: string
              enum:
                - running
                - success
                - error
              description: Status of this task
            error:
              $ref: '#/components/schemas/EngineErrorCode'
            error_message:
              type: string
              description: Detailed description of error
            results: null
      $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2'
  responses:
    InvalidApiKey:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 401
                description: Response status
              error:
                type: string
                example: Invalid API key
    TooManyRequests:
      description: Too many requests
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 429
                description: Response status
              error:
                type: string
                example: Too many requests
    InvalidTaskId:
      description: Invalid task ID
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 400
                description: Response status
              error:
                type: string
                example: Invalid task ID
    TaskTimeout:
      description: Task execution timeout
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 500
                description: Response status
              error:
                type: string
                example: Task execution timed out
