openapi: 3.0.0
info:
  title: AI Photo Background Blur
  description: >
    # Overview

    The bokeh effect is a popular photographic technique used to blur the
    background of a photo and bring the subject into focus. It adds an artistic
    touch to a photograph, making it look more professional and eye-catching.


    Create professional-looking photos with the AI Photo Background Blur API,
    which automatically isolates subjects and applies a natural background blur
    to draw attention where it matters most.



    **Sample Usage Scenarios:**


    * Portrait Enhancement

    Apply a natural bokeh effect to make subjects stand out and improve the
    visual quality of profile or portrait photos.

        Before:
        ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg)

        After:
        ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg)

    * Professional Headshots

    Create studio-like background blur effects from standard photos for business
    profiles and corporate directories.

        Before:
        ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg)

        After:
        ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg)

    ---


    ## Integration Guide


    **Input Requirements & Processing Criteria:**


    - Upload an image containing a clear, prominent foreground subject.

    - The image's longest side must not exceed **4,096 px**.

    - The source file size must be under **10 MB**.

    - At least one clearly visible foreground subject is required.

    - Only single-subject analysis is supported. If multiple people are present,
    the API automatically selects the subject with the largest visible area.



    **Workflow:**


    1. Call the File API.

    2. Retrieve the signed upload URL from the response.

    3. Upload the actual image to the returned URL.

    4. Create an AI task.

    5. Setup a Webhook or Poll the task status until completion.

    6. Download the generated result image when processing is successful.


    ---


    **Step 1 — Upload File Metadata Using the File API**


    Use `POST /s2s/v2.0/file` to create a file record and receive upload details
    for the source image.


    ```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
          }
        ]
      }'
    ```


    **File API 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 2 — Retrieve File API Response Details**


    The response contains:


    | Field | Description |

    | --- | --- |

    | `file_id` | Identifier used to create the AI task. |

    | `requests.url` | Signed URL for uploading the actual image file. |

    | `requests.method` | Upload method, usually `PUT`. |

    | `requests.headers` | Required headers for the upload request. |


    ---


    **Step 3 — Upload Image to Provided URL**


    Use the `requests.url` from the File API response to upload the source
    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 — Create an AI Task**


    Use `POST /s2s/v2.0/task/bg-blur` to create an AI task.


    | Parameter | Description | Example |

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

    | `src_file_id` | File ID returned from the File API upload flow. Required
    when using uploaded-file workflow. |
    `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` |

    | `src_file_url` | Direct URL of the source image. Use this alternative to
    `src_file_id`. | `"https://example.com/selfie.jpg"` |

    | `intensity` | Blue intensity. 0 means no blur, and 100 means the maximum
    blur. | 50 |


    **Example Request:**


    ```javascript

    const resp = await fetch(
      'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'Bearer <YOUR_TOKEN_HERE>'
        },
        body: JSON.stringify({
          src_file_url: 'https://example.com/selfie.jpg',
          intensity: 50
        })
      }
    );


    const data = await resp.json();

    console.log(data);

    ```


    **AI Task API Response:**


    ```json

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

    ```


    ---


    **Step 5 — Setup a Webhook or Poll for Task Result**


    See the [webhook integration guide](/develop/webhook.md) for setup and
    verification details.


    For polling, use the returned `task_id` to check task status.


    ```bash

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


    ---


    **Step 6 — Retrieve Result Image**


    When processing is successful, the response includes a download URL in
    `data.results.url`.


    ```json

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

    ```


    **Invalid API Key Response:**


    If the access token is invalid, the API returns a `401` response.


    ```json

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

    ```


    ---


    ## File Specs & Errors


    **File Specifications:**


    | Specification | Requirement |

    | --- | --- |

    | Image type | The image must contain one clear and prominent foreground
    subject or person. |

    | Maximum long-side resolution | Long side must not exceed **4096 px**. |

    | File size limit | Must be less than **10 MB**. |

    | Supported formats | `jpg`, `png`. |


    **Error Codes:**


    | Error Code | Description |

    | --- | --- |

    | `exceed_max_filesize` | The source image exceeds the maximum allowed
    dimensions or file size. The long side must not exceed 4096 px, and the file
    size must remain below 10 MB. |

    | `error_nsfw_content_detected` | Potential NSFW content was detected in the
    source image or generated result image. |

    | `invalid_parameter` | Invalid parameters were provided for source keys,
    destination keys, actions, mode values, intensity levels, or task
    configuration. |

    | `error_download_image` | The source image could not be downloaded
    successfully. |

    | `error_decode_image` | The source image could not be decoded successfully.
    |


    **Environment & Dependencies:**


    | Tool / Language | Recommended Runtime Versions |

    | --- | --- |

    | cURL | Bash ≥ 3.2; curl ≥ 7.58 with modern TLS/HTTP support; jq ≥ 1.6 for
    robust JSON parsing. |

    | Node.js | Node ≥ 18 for global `fetch` support. |

    | JavaScript Browser Support | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥
    13.1. |

    | PHP | PHP ≥ 7.4 with modern TLS compatibility; ext-curl recommended or
    `allow_url_fopen=On` with OpenSSL and JSON support. |

    | 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 Photo Background Blur V2.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: V2.0
    description: >-
      AI Photo Background Blur API allows you to blur the background of an image
      using AI technology.
paths:
  /s2s/v2.0/task/bg-blur:
    post:
      summary: Run an AI Photo Background Blur task.
      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:
        - V2.0
      security:
        - BearerAuthenticationV2: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/BasicRunTaskV2'
                - type: object
                  properties:
                    intensity:
                      type: integer
                      description: >
                        The intensity of the background blur. 0 means no blur,
                        and 100 means the maximum blur.
                      minimum: 0
                      maximum: 100
                      default: 50
                      example: 50
      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/bg-blur/{task_id}:
    get:
      summary: Check an AI Photo Background Blur task status.
      tags:
        - V2.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
    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=
    BasicRunTaskV2:
      title: BasicRunTaskV2
      anyOf:
        - title: Run task with src file url
          allOf:
            - $ref: '#/components/schemas/BasicRunTaskV2SrcFileUrl'
        - title: Run task with src file ID
          allOf:
            - $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
    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
