## Integration Guide
* API Playground
You can use the API Playground to test the AI Hairstyle Generator feature. This allows you to experiment with your ideas and gain a better understanding of the try-on process.
Access the API Playground at:
[https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/](https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/)
* API Workflow
This guide walks you through:
Workflow for AI Hairstyle Generator API:
**Endpoint:** `/s2s/v2.1/file/hair-transfer`
**Authentication Required:** `Authorization: Bearer YOUR_API_KEY`
**Workflow Steps:**
1. **Image Upload Preparation:**
- The process begins with preparing a selfie.
2. **List predefined templates or using your own reference photo**
**Choose Reference Source**
You have two options for styling references:
| Option | Use Case | Implementation Tip |
| --- | --- | --- |
| **Predefined Templates** (`template_id`) | Quick start (e.g., "Curly Bob", "Side-Swept Bangs") | Call `/s2s/v2.1/task/template/hair-transfer` and pick `template_id`. |
| **Custom Reference Image** (`ref_file_url` / `ref_file_id`) | User uploads own style photo or uses provided image link | Upload via same file API;
Use `ref_file_url` if your reference image is already hosted online. |
1. **Initiate AI Task and Obtain Task ID:**
- Send the uploaded image along with the style configuration via an HTTP POST request to `/s2s/v2.1/file/hair-transfer`.
- Await a unique task ID in the response, which identifies this interaction.
2. **Poll Task Status (Continuous Check):**
- Use the obtained `task_id` to periodically poll the task status using an HTTP GET request (e.g., `GET /task/${task_id}`).
- Continuously monitor for:
- `Task_status = "success"` (process completed).
- `Task_status = "error"` (resolve or retry if applicable).
- Update the workflow accordingly once the status transitions to success.
This structured workflow ensures efficient integration with user inputs, automated monitoring of tasks, and seamless retrieval of results.
* Authentication
- 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/.
* API Usage Guide
This guide explains how to upload images, prepare reference images, and create virtual try-on tasks using the AI Hairstyle Generator API.
* Step 1. Upload a File Using the File API or provide a valid image URL
Use the **File API** (`/s2s/v2.1/file/hair-transfer`) to upload a target user image.
Alternatively, skip step 1 to 3 if you already have a public image URL.
**Image Requirements:**
* Upload a high-resolution selfie 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.1/file/hair-transfer \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"files": [
{
"content_type": "image/jpg",
"file_name": "selfie_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. Prepare a Reference Image
* 4.1 Fetch Predefined Image Templates
Use the **Template API** (`/s2s/v2.1/task/template/hair-transfer`) to retrieve a list of predefined reference templates:
```bash
curl --request GET \
--url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
* 4.2 Upload a Reference Image
You can:
* Upload an reference image using the File API (`/s2s/v2.1/file/hair-transfer`), or
* Provide a valid image URL.
**Supported Images:**
* Another selfie photo as an reference image.
Refer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.
* Step 5. Create an AI Hairstyle Generator Task
Use the **AI Task API** (`/s2s/v2.1/task/hair-transfer`) to create a virtual try-on task.
**Parameters:**
* For the user image: `src_file_id` or `src_file_url`.
* For the reference image: `ref_file_id`, `ref_file_url`, or `template_id`.
**Example Request:**
```bash
curl --request POST \
--url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--data '{
"src_file_url": "https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg",
"ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png"
}'
```
**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.1/task/hair-transfer/ \
--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:
Use case:
Suggestions for How to Shoot:
