openapi: 3.0.0
info:
  title: AI Fabric Virtual Try-On
  description: >
    # Overview

    Transform your look with stunning realism! Explore unique fabric styles with
    photo mode — whether it's the elegance of silky textures or the vibrance of
    bold prints, the AI Fabric API brings materials to life! Developers can
    craft immersive experiences that let users see and feel fabrics like never
    before. Plus, fresh fabric updates are always on the way!


    ---


    ## Integration Guide


    * AI Fabric API Usage Guide


    This guide explains how to upload images, fetch predefined fabric styles,
    and create virtual try-on tasks using the AI Fabric API.


    ***

       * Step 1. Upload a File Using the File API

    Use the **File API** (`/s2s/v2.0/file`) to upload a target user image.


    **Image Requirements:**


    *   Upload a high-resolution full-body photo.

    *   Ensure the photo clearly shows the entire body.

    *   Avoid backgrounds with multiple people or distracting objects.


    **Example Request:**


    ```bash

    curl --request POST \
      --url https://yce-api-01.makeupar.com/s2s/v2.0/file \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'content-type: application/json' \
      --data '{
        "files": [
          {
            "content_type": "image/jpg",
            "file_name": "full_body_photo_01_3dbd1b6683.jpg",
            "file_size": 547541
          }
        ]
      }'
    ```


    ***

       * Step 2. Retrieve File API Response

    The response includes:


    *   `file_id` for creating an AI task.

    *   `requests.url` for uploading the actual image file.


    **Sample Response:**


    ```json

    {
      "status": 200,
      "data": {
        "files": [
          {
            "content_type": "image/jpg",
            "file_name": "full_body_photo_01_3dbd1b6683.jpg",
            "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud",
            "requests": [
              {
                "method": "PUT",
                "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...",
                "headers": {
                  "Content-Length": "547541",
                  "Content-Type": "image/jpg"
                }
              }
            ]
          }
        ]
      }
    }

    ```


    ***

       * Step 3. Upload Image to Provided URL

    Use the `requests.url` from the File API response to upload the image:


    ```bash

    curl --location --request PUT
    'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \
      --header 'Content-Type: image/jpg' \
      --header 'Content-Length: 547541' \
      --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'
    ```


    ***

       * Step 4. Fetch Predefined Fabric Templates

    Use the **Template API** (`/s2s/v2.0/task/template/fabric`) to retrieve a
    list of predefined fabric templates:


    ```bash

    curl --request GET \
        --url 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/fabric?page_size=20&starting_token=73a3c9e69b89' \
        --header 'Authorization: Bearer YOUR_API_KEY'
    ```


    ***

       * Step 5. Create an AI Task

    Use the **AI Task API** (`/s2s/v2.0/task/fabric`) to create a virtual try-on
    task.


    **Parameters:**


    *   For the user image: `src_file_id` or `src_file_url`.

    *   For the fabric style: `template_id`.


    **Example Request:**


    ```bash

    curl --request POST \
        --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric \
        --header 'Authorization: Bearer YOUR_API_KEY' \
        --header 'content-type: application/json' \
        --data '{
        "template_id":"good_template_001",
        "src_file_url":"https://example.com/selfie.jpg"
        }'
    ```


    **Sample Response:**


    ```json

    {
      "status": 200,
      "data": {
        "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT"
      }
    }

    ```


    ***

       * Step 6. Poll for Task Result

    Use the task ID to check the status:


    ```bash

    curl --request GET \
      --url https://yce-api-01.makeupar.com/s2s/v2.0/task/fabric/<YOUR_TASK_ID> \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'content-type: application/json'
    ```


    ***

       * Step 7. Retrieve Result

    A successful response includes a download URL for the result image:


    ```json

    {
      "status": 200,
      "data": {
        "error": null,
        "results": {
          "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
        },
        "task_status": "success"
      }
    }

    ```


    Invalid API Key error response:


    ```json

    {
      "status": 401,
      "error": "Unauthorized",
      "error_code": "InvalidAccessToken"
    }

    ```


    ---



    Use cases:

    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Fabric.png)


    ![](https://plugins-media.makeupar.com/smb/blog/post/2024-05-07/b103976d-1b0e-4bed-aab4-9307308b84d7.jpg)


    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/03%20ai%20clothes%20changer.jpg)


    Suggestions for How to Shoot:

    ![Suggestions for How to
    Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI-Cloth-Guideline.png
    "Suggestions for How to Shoot")


    ---


    ## File Specs & Errors

    * Supported Formats & Dimensions


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

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

    |AI Fabric|long side <= 4096, single person only, The abdomen, face, and
    shoulders should all be visible. The face must not be obstructed. The body
    should be upright and facing forward, without any unusual poses like sitting
    or squatting.|< 10MB|jpg/jpeg|


    * Error Codes


    |Error Code|Description|

    |  ----  | ----  |

    |error_apply_region_not_detected|The clothing area is either too small or
    wasn’t detected in the input 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>   - Safari
    >= 13.1 |

    | PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or
    allow_url_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 Fabric Virtual Try-On V1.0 | 2 |


    ---
  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: >-
      AI Fabric API allows you to apply fabric styles to images using predefined
      templates and source images.
paths:
  /s2s/v2.0/task/template/fabric:
    get:
      summary: List predefined templates.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      parameters:
        - name: page_size
          in: query
          schema:
            type: integer
            example: 20
          description: >-
            Number of results to return in this page. Valid value should be
            between 1 and 20. Default 20.
        - name: starting_token
          in: query
          schema:
            type: string
            example: 73a3c9e69b89
          description: >-
            Token for current page. Start with `null` for the first page, and
            use `next_token` from the previous response to start next page
      responses:
        '200':
          description: Successful retrieval of styles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateResponseSchema'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidParametersSchema'
        '401':
          description: Invalid API Key or Inactive API Key or Expired API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeySchema'
  /s2s/v2.0/task/fabric:
    post:
      summary: Run an Fabric task.
      description: Please refer to the polling guide for checking task status.
      tags:
        - V1.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunWithSingleTemplateAndSrcUrl'
      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/RunErrorSchema'
        '401':
          description: Invalid API Key or Inactive API Key or Expired API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeySchema'
        '429':
          description: Too many requests within a given amount of time
          content:
            application/json:
              schema:
                type: object
  /s2s/v2.0/task/fabric/{task_id}:
    get:
      summary: Check the status of the Fabric task.
      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':
          description: Invalid task id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTaskIdSchema'
        '401':
          description: Invalid API Key or Inactive API Key or Expired API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeySchema'
        '500':
          description: The task has no response in the expected time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskTimeoutSchema'
components:
  schemas:
    Template:
      type: object
      properties:
        id:
          type: string
          description: The ID of the template. Use this as `template_id` when run task.
          example: good_template_001
        thumb:
          type: string
          description: The thumbnail of style.
        title:
          type: string
          description: The title of the template.
        category_name:
          type: string
          description: The category name of the template.
    TemplateResponseSchema:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 200
        data:
          type: object
          properties:
            templates:
              type: array
              items:
                $ref: '#/components/schemas/Template'
            next_token:
              type: string
              example: 73a3c9e69b89
              description: Token to query next page.
    RunWithSingleTemplateAndSrcUrl:
      title: RunWithSingleTemplateAndSrcUrl
      allOf:
        - $ref: '#/components/schemas/RunWithSingleTemplate'
        - $ref: '#/components/schemas/BasicRunTaskV2'
    RunWithSingleTemplate:
      title: RunWithSingleTemplate
      type: object
      properties:
        template_id:
          type: string
          description: >-
            ID of the template. List predefined templates first, and use the id
            of a template.
          example: good_template_001
      required:
        - template_id
    BasicRunTaskV2SrcFileUrl:
      title: Run task with src file url
      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
    BasicRunTaskV2SrcFileId:
      title: Run task with src file ID
      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=
    BasicRunTaskV2:
      title: BasicRunTaskV2
      anyOf:
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - $ref: '#/components/schemas/BasicRunTaskV2SrcFileId'
    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
    EngineErrorCode:
      type: string
      nullable: true
      enum:
        - 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:

        - `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:
              $ref: '#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2'
    InvalidParametersSchema:
      type: object
      properties:
        status:
          type: integer
          example: 400
          description: Response status
        error:
          type: string
          description: Error message
          example: The operation could not be completed
        error_code:
          type: string
          enum:
            - InvalidParameters
          description: |
            Error code:
              * InvalidParameters - Invalid request parameters or body
    InvalidApiKeySchema:
      type: object
      properties:
        status:
          type: integer
          example: 401
          description: Response status
        error_code:
          type: string
          enum:
            - InvalidApiKey
            - InactiveApiKey
            - ExpiredApiKey
          description: |
            Error code:
              * InvalidApiKey - API Key is not given or not valid
              * InactiveApiKey - API Key is inactivated
              * ExpiredApiKey - API Key is expired
    RunErrorSchema:
      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:
            - CreditInsufficiency
            - InvalidStyleGroup
            - InvalidStyle
            - BadRequest
            - InvalidParameters
          description: |
            Error code:
              * CreditInsufficiency - Insufficient unit to run
              * BadRequest - Unexpected request parameter
              * InvalidStyleGroup - Invalid style group id
              * InvalidStyle - Invalid style id
              * InvalidParameters - Invalid request parameters
    InvalidTaskIdSchema:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 400
        error_code:
          type: string
          enum:
            - InvalidTaskId
          description: |
            Error code:
              * InvalidTaskId - Invalid task id
    TaskTimeoutSchema:
      type: object
      properties:
        status:
          type: integer
          description: Response status
          example: 500
        error_code:
          type: string
          enum:
            - TaskTimeout
          description: |
            Error code:
              * TaskTimeout - The task has no response in the expected time
  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'.
