# YouCam API # API Document Last modified: Feb. 4, 2026 af99e44 The YouCam APIs are series of AI effects that let you beautify your photos, as well as generate amazing aesthetic creations beyond human imagination. Let the magic begin. PLEASE NOTE that by reading this API documentation, or by setting up code pursuant to the instructions in this API documentation, you acknowledge it adheres to Perfect Corp's [Privacy policy](https://www.makeupar.com/youcamapps/youcam/privacy-policy.html), and [Terms of Service](https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api). And If you have any issue, please contact: [YouCamOnlineEditor_API@perfectcorp.com](mailto:YouCamOnlineEditor_API@perfectcorp.com) ![YouCam API](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/YCO_AI_API.png "YouCam API") ## Introduction [YouCam API](https://yce.makeupar.com/) is a powerful and easy-to-use AI platform that provides beautiful and true-to-life visual effects thanks to the latest AI technology. This API document will briefly introduce how to integrate these awesome AI effects into your business. YouCam API are standard RESTful APIs to let you easily integrate to your website, e-commerce platforms, iOS/Android APP, applets, mini-programs, and more. ![YouCam API](https://d3anovxlgi5hpq.cloudfront.net/assets/images/aiApi/banner/yce-topbanner-dt.png "YouCam API") ## API Server The YouCam APIs are built on top of RESTful web APIs. The API server is the host of all APIs. Once you complete the authentication, you can start your AI tasks through the API Server. - ### YouCam API server: https://yce-api-01.makeupar.com ## Rate Limit To ensure fair usage and prevent abuse, our API implements rate limiting. There are two types of rate limits: - ### Per IP Address Each IP address is allowed a maximum of 250 requests per 300 seconds with 5 queries per second(QPS). If this limit is exceeded, subsequent requests will receive a `429 Too Many Requests` error. - ### Per Access Token Each access token is allowed a maximum of 250 requests per 300 seconds with 5 queries per second(QPS). If this limit is exceeded, subsequent requests will receive a `429 Too Many Requests` error. Both conditions must be met for a request to be accepted. If either condition is not met, the request will receive a `429 Too Many Requests` error. Please note that each query related to unit will be processed real-time. Other APIs can use the access token util expired. It is recommended that you handle rate limit errors gracefully in your application by implementing the appropriate backoff and retry mechanisms. ## File Retention Period Any files you upload are stored on our server for **24 hours**, and then they're automatically deleted. Processed results are retained for **24 hours** after completion. > **Warning:** Even though those result files are still good for 7 days, the link to download them might only be active for about two hours after they're created. If that download link expires, you can still access the file using its file ID – you can use that ID with another feature to get it. ## Supported Formats & Dimensions |AI Photo Editing|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Photo Enhance|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Photo Colorize|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Photo Color Correction|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Photo Lighting|4096x4096 (long side <= 4096, short side >= 256)|< 10MB|jpg/jpeg/png| |AI Image Extender|Input: long side <= 4096, Output: short side <= 1024, long side <= 2048|< 10MB|jpg/jpeg/png| |AI Replace|Input: long side <= 4096, Output: short side <= 1024, long side <= 2048|< 10MB|jpg/jpeg/png| |AI Object Removal|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Image Generator|Input: long side <= 4096, Output: long side <= 1024|< 10MB|jpg/jpeg/png| |Al Photo Background Removal|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Photo Background Blur|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Photo Background Change|Input: long side <= 4096, Output: long side <= 4096|< 10MB|jpg/jpeg/png| |AI Portrait|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Avatar Generator|Input: long side <= 4096, Output: long side <= 1024|< 10MB|jpg/jpeg/png| |AI Face Swap|4096x4096 (long side <= 4096), single face only, need to show full face|< 10MB|jpg/jpeg/png| |AI Video Editing|Supported Dimensions|Supported File Size|Supported Formats| | ---- | ---- | ---- | ---- | |AI Video Enhance|input: long side <= 1920; output: max 2x input resolution, up to 60 sec, 30 FPS, 8 bit|<100MB|container: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3;| |AI Video Face Swap|input: long side <= 4096; output: 1280x720, 30 FPS, up to 30 sec, 8 bit, single face only|<100MB|container: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3| |AI Video Style Transfer|input: long side <= 4096; output: long side <= 1280, 16 FPS, up to 30 sec, 8 bit|<100MB|container: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3| ## Error Codes - Successful responses (100 - 399) - Client error responses (400 - 499) - Server error response (500 - 599) | General Error Code | Description | | ------------------ | ----------- | | exceed_max_filesize | The input file size exceeds the maximum limit | | invalid_parameter | The parameter value is invalid | | error_download_image | There was an error downloading the source image | | error_download_mask | There was an error downloading the mask image | | error_decode_image | There was an error decoding the source image | | error_decode_mask | There was an error decoding the mask image | | error_download_video | There was an error downloading the source video | | error_decode_video | There was an error decoding the source video | | error_nsfw_content_detected | NSFW content was detected in the source image | | error_no_face | No face was detected in the source image | | error_pose | Failed to detect pose in the source image | | error_face_parsing | Failed to perform face parsing on the source image | | error_inference | An error occurred in the inference pipeline | | exceed_nsfw_retry_limits | Retry limits exceeded to avoid generating NSFW image | | error_upload | There was an error uploading the result image | | error_multiple_people | Multiple people were detected in the source image | | error_no_shoulder | Shoulders are not visible in the source image | | error_large_face_angle | The face angle in the uploaded image is too large | | error_hair_too_short | The input hair is too short | | error_unexpected_video_duration | The video duration does not match the expected duration | | error_bald_image | The input hairstyle is bald | | error_unsupport_ratio | The aspect ratio of the input image is unsupported | | unknown_internal_error | Other internal errors | --- # Quick Start Guide First, you need to register a YouCam API account for free at [https://yce.makeupar.com/](https://yce.makeupar.com/). You can then purchase or subscribe to get your units to use the service. You can see your subscription plan, pay as you go units, and your usage record at [https://yce.makeupar.com/api-console/en/api-keys/](https://yce.makeupar.com/api-console/en/api-keys/). You can go to the API Key tab under your account page to generate and maintain your API keys to start using the YouCam API. ## V2 API ### **Overview** Starting from **API version v1.5**, we have introduced a **simplified V2 API** to streamline integration processes. **Scope:** Starting from **API version v1.7**, all YouCam APIs are supported V2 API. > **Note:** V2 API is designed for workflow simplification only. It does not introduce advanced functionality. Both V1 APIs and V2 APIs use the same underlying AI models. V1 API legacy API document: [https://yce.makeupar.com/document/v1.x/index.html](https://yce.makeupar.com/document/v1.x/index.html) --- ### **Key Changes in V2 API** #### **1. Endpoint Reduction** There is no need to call a separate authentication API to complete the authentication process. - **V1 API Endpoints:** - `POST /s2s/v1.0/client/auth` – Authentication - `POST /s2s/v1.1/file/ai-task` – Upload a file - `POST /s2s/v1.0/task/ai-task` – Run an AI task - `GET /s2s/v1.0/task/ai-task` – Get the result - **V2 API Endpoints:** - `POST /s2s/v2.0/file/ai-task` – Upload a file or provide a file URL - `POST /s2s/v2.0/task/ai-task` – Run an AI task - `GET /s2s/v2.0/task/ai-task` – Get the result > **Warning:** Ensure that you replace the placeholder **`ai-task`** with the exact AI feature name supported by the API (for example, **`skin-analysis`**, **`cloth`**, **`hair-style`**, **`makeup-vto`**, or **`skin-tone-analysis`**). Using an incorrect or generic placeholder will result in an invalid request or API error. Always refer to the latest API specification for the list of valid feature identifiers. #### **2. Authentication** - **V1 API:** Requires explicit call to Authentication endpoint.- **V2 API:** No separate authentication endpoint. - 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/. #### **3. Image Input** - Supports **both file upload and file URL** as input sources. #### **4. Polling Mechanism** - Processed results are retained for **24 hours** after completion. - No need for short-interval polling. - Flexible polling intervals within the 24-hour window. - **Important:** Polling is still required to check task status, as execution time is not guaranteed. #### **5. JSON Structure Simplification** - **List Style API** now uses a simplified JSON parameter structure. - AI Hairstyle Generator: https://yce-api-01.makeupar.com/s2s/v2.0/task/template/hair-style - AI Clothes: https://yce-api-01.makeupar.com/s2s/v2.0/task/template/cloth --- ### **Summary** - **V2 API = Simplified workflow, same AI models.**- Reduced endpoints, easier authentication, flexible input options, improved polling, and cleaner JSON. --- # FAQ ## Q&A Hub 1. **Q: What does 'Unit' mean, and how is it used?**
**A:** Please note that credits are exclusively used within the YouCam Online Editor UI, whereas units are designated solely for AI API usage. Throughout this document, all references to 'credit' or 'unit' pertain to the Unit.
Please check the page https://yce.makeupar.com/ai-api for details on how many units each AI feature consumes.

1. **Q: Why am I getting InvalidTaskId error?**
**A:** You will get a ***InvalidTaskId*** error once you check the status of a timed out task. So, once you run an AI task, you need to **polling** to check the status within the ***polling_interval*** until the status become either *success* or *error*.

1. **Q: What is client_id, client_secret and id_token?**
**A:** Your API Key is the ***client_id*** and the Secret key is the ***client_secret***. And please follow the Quick start guide to get the ***id_token*** to complete the authentication process. For more information and questions, please refer to our [blog page](https://www.makeupar.com/consumer/blog) and the [FAQ page](https://yce.makeupar.com/faq). Or send an e-mail to [YouCamOnlineEditor_API@perfectcorp.com](mailto:YouCamOnlineEditor_API@perfectcorp.com). Our customer success team are very happy to help. ;)

1. **Q: How to uplaod an image through curl?**
**A:** curl --location --request PUT '{url_api_response}' --header '{headers_in_api_response}' --data-binary @'{local_file_path}' ``` curl --location --request PUT 'https://example.com/sample-result-url' --header 'Content-Type: image/jpg' --header 'Content-Length: 50000'  --data-binary @'./test.jpg' ```

1. **Q: What platforms does the AI API support? Can it be used on mobile devices?**
**A:** The AI API works seamlessly across different platforms. Since it's built on a standard RESTful API, you can use it for server-to-server communication, on mobile devices, or in a web browser - whatever best fits your needs.

1. **Q: Is it possible to use the AI API with Flutter on both Android and iOS?**
**A:** Absolutely. Since AI APIs are standard RESTful APIs, you can access them using Flutter's built-in HTTP APIs to make requests. Here are some official Flutter documents on making network queries. * https://docs.flutter.dev/cookbook/networking/fetch-data * https://pub.dev/packages/http And here’s a simple way to call a http GET with Bearer Authentication using Flutter’s http package: ```dart import 'dart:convert'; import 'package:http/http.dart' as http; Future 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/v1.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}"); } } ``` Key Steps to Auth: - Retrieve the Token – You can store and retrieve the token using SharedPreferences or another secure storage method. - Include the Token in Headers – Use "Authorization": "Bearer $token" in the request headers. - Handle Expired Tokens – If the API returns a 401 InvalidAccessToken error, refresh the token if needed.

1. **Q: API key is the API key, Where can I find the secret key?**
**A:** The secret key is created only when you first generate it. So make sure to save it right away, you won't be able to see it again later.

1. **Q: Is it possible to integrate AI APIs into your website using Wix?**
**A:** We do not currently have an official integration guide for using AI APIs with Wix. However, the RESTful API itself does not impose any restrictions on the platform, provided it supports standard web queries. We strongly recommend to begin by reading the official documentation provided by Wix: https://dev.wix.com/docs/develop-websites/articles/get-started/integrate-with-3rd-parties Wix offers several methods for integrating with third-party APIs, primarily through its Velo development platform: * Fetch API: This is the most common method and an implementation of the standard JavaScript Fetch API. It allows you to make HTTP requests to external APIs from your Wix site's frontend or backend code. Backend calls: Recommended for security (especially for APIs requiring keys) and to avoid CORS issues. Use the Secrets Manager to securely store API keys. Frontend calls: Possible but less secure and may encounter CORS restrictions. * npm Packages: Velo supports the use of approved npm packages, allowing you to leverage a wide array of prebuilt JavaScript modules to extend your site's functionality with third-party features. * Service Plugins (formerly SPIs/Custom Extensions): These enable you to inject custom logic or integrate third-party services directly into Wix's business solutions (e.g., Wix Stores, Wix Bookings). Service plugins allow you to customize specific parts of existing app flows or integrate external services for functionalities like custom shipping rates, dynamic pricing, or alternative payment providers. * HTTP Functions: You can expose your site's functionality as an API, allowing third-party services to call your Wix site''s backend functions and interact with your site's data or logic. Steps for Integration (using Fetch API as an example): * Store API Keys: If the third-party API requires authentication, store sensitive credentials like API keys securely in Wix's Secrets Manager. Import wix-fetch: In your Velo backend or frontend code, import the wixFetch module. ```JavaScript import { fetch } from 'wix-fetch'; ``` * Make API Calls: Use the fetch function to send requests to the third-party API, including necessary headers and body data. ```JavaScript export async function getWeatherData() { const apiKey = await getSecret("yourApiKeyName"); // Retrieve from Secrets Manager const response = await fetch(`https://api.weatherapi.com/v1/current.json?key=${apiKey}&q=London`, { method: 'GET', headers: { 'Content-Type': 'application/json' } }); const data = await response.json(); return data; } ``` * Handle Responses: Process the data received from the API and integrate it into your site's design or functionality.

1. **Q: Is it possible to integrate AI APIs into WooCommerce?**
**A:** We do not currently have an official integration guide for using AI APIs with WooCommerce. However, the RESTful API itself does not impose any restrictions on the platform, provided it supports standard web queries. We strongly recommend to begin by reading the official documentation provided by WooCommerce: https://woocommerce.com/document/woocommerce-rest-api/ Integrating third-party APIs with WooCommerce enhances store functionality and streamlines operations. This can be achieved through various methods: * Utilizing WooCommerce REST API: WooCommerce provides a robust REST API that allows external applications to interact with your store data. You can create API keys with specific permissions (Read, Write, or Read/Write) in WooCommerce > Settings > Advanced > REST API. This enables you to automate tasks like inventory syncing, order processing, customer data synchronization, and more, by building custom integrations or using third-party services that leverage this API. * Employing Plugins: Many WordPress and WooCommerce plugins are designed specifically for integrating with popular third-party services like payment gateways, shipping carriers, CRM systems, and accounting software. Plugins often offer pre-built integrations, simplifying the setup process and reducing the need for custom coding. Examples include plugins for specific payment processors (e.g., Stripe, PayPal), shipping solutions (e.g., FedEx, USPS), or general API integration tools like WPGet API. * Custom Code and Webhooks: For unique integration needs or when a suitable plugin isn't available, you can implement custom code within your WordPress theme or a custom plugin. This involves using WordPress/WooCommerce hooks and filters to trigger API calls at specific events (e.g., woocommerce_payment_complete for post-purchase actions). Webhooks can also be used to send real-time data from WooCommerce to a third-party service when certain events occur (e.g., new order, product update).

## Debugging Guide 1. **Invalid TaskId Error**
**Why:** You’ll receive an InvalidTaskId error if you attempt to check the status of a task that has timed out. Therefore, once an AI task is initiated, you’ll need to poll for its status within the polling_interval until the status changes to either success or error.
**Solution:** To avoid the task becoming invalid, it’s necessary to implement a timed loop that queries the task status at regular intervals within the allowed polling window. 1. **500 Server Error / unknown_internal_error**
**A:** ***Important***: Simply calling the File API does not upload your file. You must manually upload the file to the URL provided in the File API response. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.
Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a ***file_id*** in the response, this ID is what you'll use to access AI features related to that file.

1. **404 Not Found error when using AI APIs**
**A:** ***Important***: Simply calling the File API does not upload your file. You must manually upload the file to the URL provided in the File API response. That URL is your upload destination, make sure the file is successfully transferred there before proceeding.
Before calling the AI API, ensure your file has been successfully uploaded. Use the File API to retrieve an upload URL, then upload your file to that location. Once the upload is complete, you'll receive a ***file_id*** in the response, this ID is what you'll use to access AI features related to that file.

1. **The API response returns the same style ID on the Postman**
**A:** The is because Postman (Pretty view) and Chrome use JavaScript to parse JSON responses. In JavaScript, numbers larger than 9007199254740991 (2^53-1) cannot be represented precisely. They are rounded to the nearest representable value, which makes different IDs appear identical (e.g., 219691778809271815 → 219691778809271800).
* Precision Loss in JavaScript/JSON Error Handling * Cause: JavaScript's Number type cannot safely handle integers beyond 2^53 - 1, leading to silent truncation or rounding. * Solution: Use a JSON parser like ***json-bigint*** to treat IDs as strings and retain full precision.

1. **Beard Authentication 400 Error**
**A:** When using the V2 API, you must include your API key in every request by adding a Bearer authorization header. Failure to do so will result in authentication errors. **Valid Request Header Format** ``` Authorization: Bearer YOUR_API_KEY ``` **Common Issues** 1. **Missing Bearer Prefix** The `Authorization` header must start with `Bearer` followed by the API key. Example: ``` Authorization: YOUR_API_KEY ``` 1. **Unnecessary Characters** Do not include angle brackets `<` or `>` around the API key. These characters are not required and will cause the request to fail. Example: ``` Authorization: Bearer ``` 2. **Incorrect API Key** Ensure that the API key provided in the `Authorization` header is correct and active. Version: v1.9 License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthentication Use the `access_token` obtained from authentication and pass it in header: `Authorization:Bearer ` Type: http Scheme: bearer ### BearerAuthenticationV2 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'. Type: http Scheme: bearer ## Download OpenAPI description [YouCam API](https://docs.perfectcorp.com/_bundle/developers/unit_system.yaml) ## Unit system Check your unit details and usage history. Please note that credits are exclusively used within the YouCam Online Editor UI, whereas units are designated solely for AI API usage. Throughout this document, all references to 'credit' or 'unit' pertain to the Unit. ### Get unit info - [GET /s2s/v1.0/client/credit](https://docs.perfectcorp.com/developers/unit_system/unit-system/paths/~1s2s~1v1.0~1client~1credit/get.md) ### View unit history - [GET /s2s/v1.0/client/credit/history](https://docs.perfectcorp.com/developers/unit_system/unit-system/paths/~1s2s~1v1.0~1client~1credit~1history/get.md)