### python scripts/youcam_core.py setup

Source: https://docs.perfectcorp.com/develop/agent_skills

Sets up a local virtual environment and installs dependencies for the skill.

```APIDOC
## [SETUP] python scripts/youcam_core.py setup

### Description
Creates a local virtual environment and installs required dependencies for the skill.

### Method
SETUP

### Endpoint
python scripts/youcam_core.py setup

### Parameters
None

### Request Example
```bash
python scripts/youcam_core.py setup
```

### Response
#### Success Response
- **exit code** (integer) - 0 on success

#### Response Example
```
Virtual environment created and dependencies installed.
```

```

--------------------------------

### Quick Start: Initialize and Open Camera Kit

Source: https://docs.perfectcorp.com/reference/ai_bracelet/section/overview/integration-guide

Complete HTML example that initializes the Camera Kit, opens the camera, and handles captured images. It listens for the 'loaded' and 'faceDetectionCaptured' events, supports both base64 and Blob image formats, and requires a mandatory mount point with id 'YMK-module'.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Camera Kit Sample</title>
    <style>
      #YMK-module { margin: 20px 0; }
      img { width: 150px; margin: 5px; border: 1px solid #ccc; }
    </style>
  </head>
  <body>

    <!-- Initialization Script -->
    <script>
      // Define async init entry point
      window.YMKAsyncInit = function() {
        YMK.addEventListener('loaded', function() {
          console.log('Module fully loaded and ready');
        });

        YMK.addEventListener('faceDetectionCaptured', function(capturedResult) {
          const container = document.getElementById('captured-results');
          container.innerHTML = '';

          // Handle multiple images if returned (e.g., multi-angle capture)
          for (const item of capturedResult.images) {
            const img = document.createElement('img');
            // Handle both base64 strings and Blob objects
            img.src = typeof item.image === 'string' 
              ? item.image 
              : URL.createObjectURL(item.image);
            container.appendChild(img);
          }
        });
      };

      function openCameraKit() {
        YMK.init({
          faceDetectionMode: 'makeup',
          imageFormat: 'base64',
          language: 'enu'
        });
        YMK.openCameraKit();
      }
    </script>

    <!-- Load SDK -->
    <script src="https://plugins-media.makeupar.com/v2.5-camera-kit/sdk.js"></script>

    <!-- UI Elements -->
    <button onclick="openCameraKit()">Open Camera Kit</button>

    <!-- Mandatory Mount Point -->
    <div id="YMK-module"></div>

    <h3>Captured Results:</h3>
    <div id="captured-results"></div>
  </body>
</html>
```

--------------------------------

### Example Error Response for Start Task

Source: https://docs.perfectcorp.com/_bundle/reference/makeup_vto.json?download=

Example 400 Bad Request error response with error_code CreditInsufficiency.

```json
{
  "status": 400,
  "error": "The operation could not be completed",
  "error_code": "CreditInsufficiency"
}
```

--------------------------------

### Example Success Response for Get Task Status

Source: https://docs.perfectcorp.com/_bundle/reference/makeup_vto.json?download=

Example 200 OK response with task_status success and a results URL.

```json
{
  "status": 200,
  "data": {
    "task_status": "success",
    "results": {
      "url": "https://s3.storage.prod/processed/image_123.jpg?token=..."
    }
  }
}
```

--------------------------------

### Example In-Progress Response for Get Task Status

Source: https://docs.perfectcorp.com/_bundle/reference/makeup_vto.json?download=

Example response when the task is still running, with task_status 'running'.

```json
{
  "status": 200,
  "data": {
    "task_status": "running"
  }
}
```

--------------------------------

### Start preview and auto-focus

Source: https://docs.perfectcorp.com/reference/ai_skin_analysis/section/overview/unit-consumption

Starts the camera preview and optionally triggers auto-focus. Call startPreview() after setting the display/texture and callback; it must be called before sending frames.

```java
// In CameraHandler.startPreview()
camera.startPreview();
isPreviewStarted = true;

// Optional: Auto-focus for better image quality
camera.autoFocus(autoFocusCallback);
```

--------------------------------

### startPreview()

Source: https://docs.perfectcorp.com/reference/ai_skin_analysis/section/overview/js-camera-kit

Starts the camera preview. Must be called after setting display/texture and callback, and before sending frames.

```APIDOC
## startPreview()

### Description
Starts the camera preview. Must be called after setting display/texture and callback, and before sending frames.

### Method
startPreview

### Parameters
None

### Example
```java
camera.startPreview();
isPreviewStarted = true;
```
```

--------------------------------

### Example Query Error Response for Get Task Status

Source: https://docs.perfectcorp.com/_bundle/reference/makeup_vto.json?download=

Example 401 error response with error_code InvalidApiKey. No units are consumed on error.

```json
{
  "status": 401,
  "error_code": "InvalidApiKey"
}
```

--------------------------------

### YMK.init()

Source: https://docs.perfectcorp.com/reference/ai_face_analyzer/section/overview/unit-consumption

Initializes the Camera Kit SDK with configuration options. Must be called before opening the camera.

```APIDOC
## YMK.init()

### Description
Initializes the Camera Kit SDK with the provided configuration. This method must be called before opening the camera.

### Method
`init(config)`

### Parameters
- **config** (Object) - Required - Configuration object for the SDK.
  - **faceDetectionMode** (string) - Required - The face detection mode. Example: `'makeup'`.
  - **imageFormat** (string) - Required - The output image format. Supported values: `'base64'` or `'blob'`.
  - **language** (string) - Optional - The language code for the UI. Example: `'enu'`.

### Request Example
```javascript
YMK.init({
  faceDetectionMode: 'makeup',
  imageFormat: 'base64',
  language: 'enu'
});
```

### Response
No return value. The SDK initializes asynchronously; listen for the `'loaded'` event to know when it is ready.
```

--------------------------------

### Open Camera Kit with YMK.openCameraKit()

Source: https://docs.perfectcorp.com/reference/ai_bracelet/section/overview/file-specs-and-errors

Displays the UI, opens the webcam, and begins real-time monitoring.

```javascript
YMK.openCameraKit();
```

--------------------------------

### YMK.openCameraKit()

Source: https://docs.perfectcorp.com/reference/ai_bracelet/section/overview/file-specs-and-errors

Opens the Camera Kit module, displays the UI, opens the webcam, and begins real-time monitoring.

```APIDOC
## YMK.openCameraKit()

### Description
Opens the Camera Kit module, displays the UI, opens the webcam, and begins real-time monitoring.

### Method
- **YMK.openCameraKit()**

### Parameters
None.

### Request Example
```javascript
YMK.openCameraKit();
```

### Response
No return value documented.
```

--------------------------------

### Example Engine Error Response for Get Task Status

Source: https://docs.perfectcorp.com/_bundle/reference/makeup_vto.json?download=

Example response when the AI task fails after the query was sent successfully. Includes task_status 'error' and error details. No units are consumed on error.

```json
{
  "status": 200,
  "data": {
    "task_status": "error",
    "error": "exceed_max_filesize",
    "error_message": "string",
  }
}
```

--------------------------------

### YMK.init(args)

Source: https://docs.perfectcorp.com/reference/ai_face_lift/v1.0

Initializes the Camera Kit module with configuration options for detection mode, image format, language, and more. Must be called before opening the camera.

```APIDOC
## YMK.init(args)

### Description
Configures the Camera Kit module with detection mode, language, capture format, and other settings. Must be called before `YMK.openCameraKit()`.

### Method
`YMK.init(args)`

### Parameters
#### Request Body
- **faceDetectionMode** (string) - Optional - Detection flow to use. Default: `"skincare"`. Options: `"makeup"`, `"skincare"`, `"hdskincare"`.
- **width** (number) - Optional - Pixel width of module container (300–1920). Default: `360` (≥500px) or `screen width`.
- **height** (number) - Optional - Pixel height of module container (300–1920). Default: `480` (≥500px) or `min(screen.height, innerHeight)`.
- **language** (string) - Optional - UI Language code. Default: `"enu"`. Options: `"chs"`, `"cht"`, `"deu"`, `"enu"`, `"esp"`, `"fra"`, `"jpn"`, `"kor"`, `"ptb"`, `"ita"`, `"mon"`.
- **imageFormat** (string) - Optional - Format returned via `faceDetectionCaptured`. Default: `"base64"`.
- **disableCameraResolutionCheck** (boolean) - Optional - Allow running even if webcam does not meet required resolution. Default: `false`.
- **hideFlipCameraButton** (boolean) - Optional - Controls visibility of the flip front/back camera button if the device supports it. Default: `false`.
- **countingDuration** (number) - Optional - Controls the countdown milliseconds when camera quality check meets criteria before auto-capture. Default: `800`.
- **qualityLevel** (string) - Optional - Controls the camera quality check setting. Options: `relaxed`, `moderate`, `strict`. Default: `relaxed`.
- **qualityOverrides** (object) - Optional - Configure detailed parameters for camera quality verification. See Camera Kit Quality Configuration.
- **videoQuality** (string) - Optional - Configure the output quality to `720p`, `1080p`, or `1920p`. Supported only for `skincare` and `hdskincare`. Default: `720p`.

### Request Example
```json
{
  "faceDetectionMode": "makeup",
  "imageFormat": "base64",
  "language": "enu"
}
```

### Response
No response body. Returns `undefined`.
```

--------------------------------

### Response for GET /s2s/v1.0/client/credit

Source: https://docs.perfectcorp.com/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get

Example JSON response for a successful retrieval of unit info. Contains status and results array.

```json
{
  "status": 200,
  "results": [
    { … }
  ]
}
```

--------------------------------

### YMK.init(args)

Source: https://docs.perfectcorp.com/reference/ai_bracelet/section/overview/file-specs-and-errors

Initializes the Camera Kit module with configuration options for detection mode, output format, language, and more. Must be called before openCameraKit().

```APIDOC
## YMK.init(args)

### Description
Initializes the Camera Kit module with configuration options for detection mode, output format, language, and more. Must be called before openCameraKit().

### Method
- **YMK.init(args)**

### Parameters
- **faceDetectionMode** (string) - Optional - Detection flow to use (see Detection Modes below). Default: `"skincare"`.
- **width** (number) - Optional - Pixel width of module container (300–1920). Default: `360` (≥500px) or `screen width`.
- **height** (number) - Optional - Pixel height of module container (300–1920). Default: `480` (≥500px) or `min(screen.height, innerHeight)`.
- **language** (string) - Optional - UI Language code (`chs`, `cht`, `deu`, `enu`, `esp`, `fra`, `jpn`, `kor`, `ptb`, `ita`, `mon`). Default: `"enu"`.
- **imageFormat** (string) - Optional - Format returned via `faceDetectionCaptured`. Default: `"base64"`.
- **disableCameraResolutionCheck** (boolean) - Optional - Allow running even if webcam does not meet required resolution. Default: `false`.
- **hideFlipCameraButton** (boolean) - Optional - Controls visibility of the flip front/back camera button if the device supports it. Default: `false`.
- **countingDuration** (number) - Optional - Controls the countdown milliseconds when camera quality check meets criteria before auto-capture. Default: `800`.
- **qualityLevel** (string) - Optional - Controls the camera quality check setting, with options of `relaxed`, `moderate`, or `strict`. Default: `relaxed`.
- **qualityOverrides** (object) - Optional - Configure detailed parameters for camera quality verification. See Camera Kit Quality Configuration.
- **videoQuality** (string) - Optional - Configure the output quality to `720p`, `1080p`, or `1920p`. 720p corresponds to 1280 × 720, 1080p to 1920 × 1080, and 1920p to 2560 × 1920. This setting is supported only for `skincare` and `hdskincare`. Default: `720p`.

### Request Example
```javascript
YMK.init({
  faceDetectionMode: 'makeup',
  imageFormat: 'base64',
  language: 'enu'
});
```

### Response
No return value documented.
```

--------------------------------

### Response for GET /s2s/v1.0/client/credit/history

Source: https://docs.perfectcorp.com/reference/unit_system/paths/~1s2s~1v2.0~1credit~1feature-cost/get

Example JSON response for a successful retrieval of unit usage history. Contains status and result object with next_token and history array.

```json
{
  "status": 200,
  "result": {
    "next_token": "73a3c9e69b89",
    "history": [ … ]
  }
}
```

--------------------------------

### Android CameraKit Initialization and Frame Handling

Source: https://docs.perfectcorp.com/reference/ai_skin_analysis/section/overview/mobile-camera-kit

Initializes PerfectLib, creates a CameraKit instance, sets a quality check callback, and sends camera frames. Includes steps for notifying CameraKit when the camera opens and sending each preview frame.

```java
// 1. Initialize PerfectLib SDK first
Configuration configuration = Configuration.builder()
    .setModelPath(PerfectLib.ModelPath.assets("model"))
    .build();

PerfectLib.init(getApplicationContext(), configuration, new PerfectLib.InitialCallback() {
    @Override
    public void onInitialized(Set<Functionality> availableFunctionalities,
                              Map<String, Throwable> preloadErrors) {
        // 2. Create CameraKit instance
        CameraKit.create(new CameraKit.CreateCallback() {
            @Override
            public void onSuccess(CameraKit cameraKit) {
                CameraKitActivity.this.cameraKit = cameraKit;

                // 3. Set quality check callback
                cameraKit.setCameraKitQualityCheckCallback(result -> {
                    boolean isReady = result.getFaceAreaQuality().isOk()
                        && result.getFacePoseQuality().isOk()
                        && result.getLightingQuality().isOk();

                    if (isReady) {
                        enableCaptureButton();
                    } else {
                        disableCaptureButton();
                    }
                });

                // 4. Set initial quality level
                cameraKit.setCameraKitLevel(CameraKitLevel.RELAXED);
            }

            @Override
            public void onFailure(Throwable throwable) {
                Log.e(TAG, "CameraKit create failed", throwable);
            }
        });
    }

    @Override
    public void onFailure(Throwable throwable, Map<String, Throwable> preloadErrors) {
        Log.e(TAG, "PerfectLib init failed", throwable);
    }
});

// 5. Notify CameraKit when camera opens (in your camera implementation)
cameraKit.onCameraOpened(isFrontCamera, cameraOrientation, previewWidth, previewHeight);

// 6. Send each preview frame to CameraKit
CameraFrame frame = new CameraFrame(data, previewWidth, previewHeight, isFirstFrame);
frame.setFrameOrientation(frameRotationDegrees);
cameraKit.sendCameraBuffer(frame);
```

--------------------------------

### Response: Successful AI Aging task execution

Source: https://docs.perfectcorp.com/reference/ai_aging_simulation/v1.0

Example JSON response with HTTP 200 status and a data object containing the task_id. Use this task_id to poll the task status via the GET endpoint.

```json
{
  "status": 200,
  "data": {
    "task_id": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
  }
}
```

--------------------------------

### Initialize YMK module with YMK.init()

Source: https://docs.perfectcorp.com/reference/ai_bracelet/section/overview/file-specs-and-errors

Call YMK.init() before opening the camera. Configures face detection mode, output image format, and UI language.

```javascript
YMK.init({
  faceDetectionMode: 'makeup', // Detection flow
  imageFormat: 'base64',       // Output format
  language: 'enu'              // UI Language
});
```

--------------------------------

### YMK.init(args)

Source: https://docs.perfectcorp.com/reference/ai_hair_density_detection/section/overview/hair-density-classification

Initializes the YMK module with configuration options for face detection mode, image format, language, and other settings.

```APIDOC
## YMK.init(args)

### Description
Configures the module appearance, detection mode, language, and capture format.

### Method
YMK.init

### Parameters
#### Request Body
- **faceDetectionMode** (string) - Required - Detection flow to use (see Detection Modes below). Default: "skincare"
- **width** (number) - Optional - Pixel width of module container (300–1920). Default: 360 (≥500px) or screen width
- **height** (number) - Optional - Pixel height of module container (300–1920). Default: 480 (≥500px) or min(screen.height, innerHeight)
- **language** (string) - Optional - UI Language code (chs, cht, deu, enu, esp, fra, jpn, kor, ptb, ita, mon). Default: "enu"
- **imageFormat** (string) - Optional - Format returned via faceDetectionCaptured. Default: "base64"
- **disableCameraResolutionCheck** (boolean) - Optional - Allow running even if webcam does not meet required resolution. Default: false
- **hideFlipCameraButton** (boolean) - Optional - Controls visibility of the flip front/back camera button if the device supports it. Default: false
- **countingDuration** (number) - Optional - Controls the countdown milliseconds when camera quality check meets criteria before auto-capture. Default: 800
- **qualityLevel** (string) - Optional - Controls the camera quality check setting, with options of relaxed, moderate, or strict. Default: relaxed
- **qualityOverrides** (object) - Optional - Configure detailed parameters for camera quality verification. See Camera Kit Quality Configuration
- **videoQuality** (string) - Optional - Configure the output quality to 720p, 1080p, or 1920p. 720p corresponds to 1280 × 720, 1080p to 1920 × 1080, and 1920p to 2560 × 1920. This setting is supported only for skincare and hdskincare. Default: 720p

### Request Example
```json
{
  "faceDetectionMode": "makeup",
  "imageFormat": "base64",
  "language": "enu"
}
```

### Response
#### Success Response (200)
No explicit response body documented.

#### Response Example
No explicit response example documented.
```

--------------------------------

### Dart: Fetch AI Task with Bearer Token

Source: https://docs.perfectcorp.com/develop/faq

Dart example using the http package to GET an AI task endpoint. Replace the token and the 'ai-task' path with your actual credentials and desired AI feature. Handles 200 success and prints the response body, otherwise prints the status code.

```dart
import 'dart:convert';
import 'package:http/http.dart' as http;

Future<void> fetchData() async {
    String token = "your_bearer_token_here"; // Replace with your actual token

    final response = await http.get(
        Uri.parse("https://yce-api-01.makeupar.com/s2s/v2.0/task/ai-task"), // Replace the `ai-task` with the AI feature you intend to use.
        headers: {
        "Content-Type": "application/json",
        "Authorization": "Bearer $token",
        },
    );

    if (response.statusCode == 200) {
        print("Data fetched successfully: ${response.body}");
    } else {
        print("Failed to fetch data: ${response.statusCode}");
    }
}
```

--------------------------------

### iOS CameraKit Initialization and Delegate Callback

Source: https://docs.perfectcorp.com/reference/ai_skin_analysis/section/overview/mobile-camera-kit

Creates a CameraKit instance with a model path, sets the delegate, notifies when the camera opens, sets the quality level, sends preview frames, and implements the delegate callback for quality results.

```swift
// 1. Create CameraKit instance with model path
let modelPath = Bundle.main.path(forResource: "model", ofType: "")
CameraKit.create(withModelPath: modelPath) { [weak self] cameraKit, error in
    guard let self = self, let cameraKit = cameraKit else { return }

    self.cameraKit = cameraKit

    // 2. Set delegate for quality check callbacks
    self.cameraKit?.delegate = self

    // 3. Notify CameraKit when camera opens
    self.cameraKit?.onCameraOpen(true) // true = front camera

    // 4. Set initial quality level
    self.cameraKit?.setCameraKitLevel(.relaxed)
}

// 5. Send each preview frame to CameraKit (AVCaptureVideoDataOutputSampleBufferDelegate)
func captureOutput(_ output: AVCaptureOutput,
                   didOutput sampleBuffer: CMSampleBuffer,
                   from connection: AVCaptureConnection) {
    cameraKit?.sendCameraBuffer(sampleBuffer)
}

// 6. Implement delegate callback for quality results
extension CameraKitViewController: CameraKitDelegate {
    func cameraKit(_ cameraKit: CameraKit, checkedResult: CameraKitQualityCheck) {
        let canCapture = checkedResult.lightingQuality.isOk &&
                        checkedResult.faceAreaQuality.isOk &&
                        checkedResult.facePoseQuality.isOk

        DispatchQueue.main.async { [weak self] in
            self?.updateCaptureButtonAvailability()
            self?.latestQualityCheck = checkedResult
        }
    }
}
```

--------------------------------

### Webhook Signature Example

Source: https://docs.perfectcorp.com/develop/webhook

Example of the webhook-signature header value used for HMAC-SHA256 verification.

```text
v1,vyVNWrjoZcBK1JXrFGkdDKK2slo5+Q5yfzpkHmqO5R0=
```

--------------------------------

### GET /s2s/v2.0/task/face-swap/pre-process

Source: https://docs.perfectcorp.com/_bundle/reference/ai_face_swap.json?download=

Endpoint to poll the status of a pre-processing task and get detected faces.

```APIDOC
## GET /s2s/v2.0/task/face-swap/pre-process

### Description
Polls the status of a pre-processing task to retrieve detected faces with bounding boxes.

### Method
GET

### Endpoint
https://yce-api-01.makeupar.com/s2s/v2.0/task/face-swap/pre-process?task_id=TASK_ID

### Query Parameters
- **task_id** (string) - Required - The task ID returned from the pre-process creation call.

### Response
#### Success Response (200)
- **faces** (array) - List of detected faces with bounding boxes.
  - **bounding_box** (object) - Coordinates of the face bounding box.

#### Response Example
```json
{
    "faces": [
        {
            "bounding_box": {
                "x": 0,
                "y": 0,
                "width": 100,
                "height": 100
            }
        }
    ]
}
```
```

--------------------------------

### Example Signed Content

Source: https://docs.perfectcorp.com/develop/webhook

Example of the signed content using the webhook-id, timestamp, and minified JSON body.

```text
msg_1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4:1761112848.1761112900.{"created_at":1761112848,"data":{"task_id":"1eWPv9cWJCnEP99UJncmVJ6KjK_xVXRhZPe_eSGnRNbLlXEPjiG3gb3Usg9le3_4","task_status":"success"}}
```

--------------------------------

### Run a skill with the CLI

Source: https://docs.perfectcorp.com/develop/agent_skills

Executes a YouCam feature by uploading the source image, creating an API task, polling for completion, and printing structured JSON output. Use `--param` for repeated key-value API parameters.

```bash
python scripts/youcam_core.py run \
  --feature skin-analysis \
  --src_file selfie.jpg \
  --param format=json \
  --param dst_actions='["hd_pore","hd_skin_type"]'
```