SKILL.md
Face Transform
Analyze and transform faces through AceDataCloud's Face API suite.
Setup: See [authentication](../_shared/authentication.md) for token setup.
Quick Start
curl -X POST https://api.acedata.cloud/face/analyze \
-H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://example.com/portrait.jpg"}'Available APIs
| Endpoint | Purpose | Description |
|---|---|---|
POST /face/analyze |
Face Detection | Detect face keypoints (90+ points per face) |
POST /face/beautify |
Beautification | Apply beauty/decoration effects |
POST /face/change-age |
Age Transform | Make a face look older or younger |
POST /face/change-gender |
Gender Swap | Transform facial gender characteristics |
POST /face/swap |
Face Swap | Replace one person's face with another |
POST /face/cartoon |
Cartoon Style | Convert portrait to animated/cartoon style |
POST /face/detect-live |
Liveness Check | Detect if a face image is from a live person |
Workflows
1. Face Analysis
Detect faces and extract 90+ keypoints per face.
POST /face/analyze
{
"image_url": "https://example.com/photo.jpg"
}Response includes detailed keypoints: nose, mouth, lefteye, righteye, lefteyebrow, righteyebrow, contour — each as arrays of {x, y} coordinates.
2. Face Beautification
POST /face/beautify
{
"image_url": "https://example.com/portrait.jpg"
}3. Age Transformation
age_infos is required — one entry per face, each carrying the target age.
POST /face/change-age
{
"image_url": "https://example.com/portrait.jpg",
"age_infos": [{ "age": 60 }]
}4. Gender Swap
gender_infos is required. gender is 0 to turn a male face female, 1 for the reverse.
POST /face/change-gender
{
"image_url": "https://example.com/portrait.jpg",
"gender_infos": [{ "gender": 1 }]
}5. Face Swap
Replace the face in the target image with the face from the source.
POST /face/swap
{
"source_image_url": "https://example.com/source-face.jpg",
"target_image_url": "https://example.com/target-person.jpg"
}6. Cartoon Style
POST /face/cartoon
{
"image_url": "https://example.com/portrait.jpg"
}7. Liveness Detection
POST /face/detect-live
{
"image_url": "https://example.com/face-photo.jpg"
}Parameters
Common
| Parameter | Required | Description |
|---|---|---|
image_url |
Yes (all except /face/swap) |
Source face image URL |
/face/change-age
| Parameter | Required | Description |
|---|---|---|
age_infos |
Yes | Array of { "age": <number> }, one per face. Omitting it returns 400 age_infos is required |
/face/change-gender
| Parameter | Required | Description | |
|---|---|---|---|
gender_infos |
Yes | Array of `{ "gender": 0\ | 1 } — 0 male→female, 1 female→male. Each entry also accepts an optional face_rect` |
/face/swap
| Parameter | Required | Description |
|---|---|---|
sourceimageurl |
Yes | URL of the face to use (replaces the face) |
targetimageurl |
Yes | URL of the image to put the face onto |
callback_url |
No | Webhook URL for async delivery |
timeout |
No | Max wait time in seconds (default: 120) |
/face/beautify
| Parameter | Required | Description |
|---|---|---|
image_url |
Yes | Image URL |
smoothing |
No | Skin smoothing 0–100 (default: 10) |
whitening |
No | Whitening 0–100 (default: 30) |
face_lifting |
No | Face slimming 0–100 (default: 70) |
eye_enlarging |
No | Eye enlarging 0–100 (default: 70) |
/face/analyze
| Parameter | Required | Description |
|---|---|---|
image_url |
Yes | Image URL |
mode |
No | 0 = all faces (default), 1 = largest face only |
facemodelversion |
No | Algorithm version (recommended: 3.0) |
needrotatedetection |
No | 0 = disabled (default), 1 = enabled |
Gotchas
- All face APIs return results synchronously.
/face/swapadditionally supports an optionalcallback_urlparameter for async delivery (pass it to receive the result via webhook instead of waiting inline) - Face analyze returns 90+ keypoints per detected face, supporting multiple faces in one image
- Face swap uses
sourceimageurl(the face to apply) andtargetimageurl(the body to apply it to) - All APIs are currently in Alpha stage — interfaces may evolve
- Images should contain clearly visible, front-facing faces for best results
- Liveness detection helps distinguish live photos from printed/screen photos