Skip to content
/
5. JSON Structure Simplif...

YouCam API (v1.9)

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, and Terms of Service. And If you have any issue, please contact: YouCamOnlineEditor_API@perfectcorp.com

YouCam API

Introduction

YouCam API 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

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 EditingSupported DimensionsSupported File SizeSupported Formats
AI Photo EnhanceInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI Photo ColorizeInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI Photo Color CorrectionInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI Photo Lighting4096x4096 (long side <= 4096, short side >= 256)< 10MBjpg/jpeg/png
AI Image ExtenderInput: long side <= 4096, Output: short side <= 1024, long side <= 2048< 10MBjpg/jpeg/png
AI ReplaceInput: long side <= 4096, Output: short side <= 1024, long side <= 2048< 10MBjpg/jpeg/png
AI Object RemovalInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI Image GeneratorInput: long side <= 4096, Output: long side <= 1024< 10MBjpg/jpeg/png
Al Photo Background RemovalInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI Photo Background BlurInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI Photo Background ChangeInput: long side <= 4096, Output: long side <= 4096< 10MBjpg/jpeg/png
AI PortraitSupported DimensionsSupported File SizeSupported Formats
AI Avatar GeneratorInput: long side <= 4096, Output: long side <= 1024< 10MBjpg/jpeg/png
AI Face Swap4096x4096 (long side <= 4096), single face only, need to show full face< 10MBjpg/jpeg/png
AI Video EditingSupported DimensionsSupported File SizeSupported Formats
AI Video Enhanceinput: long side <= 1920; output: max 2x input resolution, up to 60 sec, 30 FPS, 8 bit<100MBcontainer: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3;
AI Video Face Swapinput: long side <= 4096; output: 1280x720, 30 FPS, up to 30 sec, 8 bit, single face only<100MBcontainer: mov, mp4; video codec: MPEG-4, H.264 AVC; audio codec: aac, mp3
AI Video Style Transferinput: long side <= 4096; output: long side <= 1280, 16 FPS, up to 30 sec, 8 bit<100MBcontainer: 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 CodeDescription
exceed_max_filesizeThe input file size exceeds the maximum limit
invalid_parameterThe parameter value is invalid
error_download_imageThere was an error downloading the source image
error_download_maskThere was an error downloading the mask image
error_decode_imageThere was an error decoding the source image
error_decode_maskThere was an error decoding the mask image
error_download_videoThere was an error downloading the source video
error_decode_videoThere was an error decoding the source video
error_nsfw_content_detectedNSFW content was detected in the source image
error_no_faceNo face was detected in the source image
error_poseFailed to detect pose in the source image
error_face_parsingFailed to perform face parsing on the source image
error_inferenceAn error occurred in the inference pipeline
exceed_nsfw_retry_limitsRetry limits exceeded to avoid generating NSFW image
error_uploadThere was an error uploading the result image
error_multiple_peopleMultiple people were detected in the source image
error_no_shoulderShoulders are not visible in the source image
error_large_face_angleThe face angle in the uploaded image is too large
error_hair_too_shortThe input hair is too short
error_unexpected_video_durationThe video duration does not match the expected duration
error_bald_imageThe input hairstyle is bald
error_unsupport_ratioThe aspect ratio of the input image is unsupported
unknown_internal_errorOther internal errors

Quick Start Guide

First, you need to register a YouCam API account for free at 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/. 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

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.

  2. 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.

  3. 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 and the FAQ page. Or send an e-mail to YouCamOnlineEditor_API@perfectcorp.com. Our customer success team are very happy to help. ;)

  4. 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'



  5. 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.

  6. 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:

    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/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.

  7. 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.

  8. 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.

      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.

      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.

  9. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

    2. 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 <YOUR_API_KEY>

    3. Incorrect API Key Ensure that the API key provided in the Authorization header is correct and active.

Download OpenAPI description
unit_system.json
unit_system.yaml
Overview
E-mail
YouCamOnlineEditor_API@perfectcorp.com
License
Privacy policy
Terms of Service
Languages
Servers
https://yce-api-01.makeupar.com

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.

Operations