face-transform — Claude Code skill: face analysis and transforms
face-transform is a Claude Code skill that connects seven AceDataCloud face APIs for keypoint detection, retouching, age and gender changes, face swaps, cartoon conversion, and liveness checks.
Apache-2.0 228 installs ★ 17 updated 2026-10-25
npx skills add AceDataCloud/Skills --skill face-transform -a claude-codeWhat face-transform does
The skill works through seven AceDataCloud endpoints: /face/analyze detects up to 90 keypoints per face, /face/beautify retouches portraits, /face/change-age ages or de-ages a person, /face/change-gender swaps gender, /face/swap replaces one face with another, /face/cartoon turns a photo into cartoon style, /face/detect-live checks whether the image was taken from a live person. Age and gender transforms require an array of parameters — one entry per face.
Before the first call, sign up at AceDataCloud, create an API key in the Applications section, and put it in ~/.openclaw/.env as ACEDATACLOUD_API_TOKEN=your_key. The key starts with platform-, not Bearer. If Allowed APIs restrictions are enabled in your application settings, add the routes you need — /face/analyze, /face/beautify, and others. Without a key or balance, requests return an authorization error.
All APIs run synchronously and return results immediately; only /face/swap additionally accepts a callback_url parameter for async delivery via webhook. For best results, the image should contain a clear, front-facing face. All APIs are in Alpha stage — interfaces may change.
What it helps with
- detect face keypoints (nose, eyes, eyebrows, contour) in an image
- age or de-age a person in a photo to a specified age
- swap the gender of a face in a portrait (male to female and vice versa)
- replace one person's face with another in a photo
- check whether an image was taken from a live person or a screen
Example prompts for the agent
- Detect face keypoints in the image at
https://cdn.acedata.cloud/lrbtcn.jpgusing/face/analyze - Swap the face from
source-face.jpgonto the body intarget-person.jpgusing/face/swap - Age the person in
portrait.jpgto 60 years using/face/change-age
How to install face-transform
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill face-transform -a claude-code2Manually: put the files in place
~/.claude/skills/face-transform/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/face-transform/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill face-transform -a codex2Manually: put the files in place
.agents/skills/face-transform/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill face-transform -a cursor2Manually: put the files in place
.cursor/skills/face-transform/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install AceDataCloud/Skills skills/face-transform2Manually: put the files in place
.github/skills/face-transform/SKILL.md1Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill face-transform -a gemini-cli2Platform CLI
gemini skills install https://github.com/AceDataCloud/Skills --path skills/face-transformManually: put the files in place
.devin/skills/face-transform/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add AceDataCloud/Skills --skill face-transform -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about face-transform
How do I install face-transform in Claude Code?
Run npx skills add AceDataCloud/Skills --skill face-transform -a claude-code, then open ~/.claude/skills/face-transform/SKILL.md.
What does face-transform do?
Connects seven AceDataCloud face APIs: detects keypoints (up to 90 per face), retouches portraits, changes age and gender, swaps faces, converts photos to cartoon style, and checks whether an image was taken from a live person.
What does face-transform require to run?
An API key from AceDataCloud (Applications section, General application) in the ACEDATACLOUD_API_TOKEN variable in ~/.openclaw/.env. The key starts with platform-, not Bearer. If Allowed APIs restrictions are enabled in your application settings, add the routes you need — /face/analyze, /face/beautify, and others.
Source text
SKILL.md · Apache-2.0
---
name: face-transform
description: Analyze and transform faces via AceDataCloud API. Use when detecting face keypoints, beautifying portraits, aging/de-aging faces, swapping genders, replacing faces between photos, creating cartoon avatars, or detecting liveness. Provides 7 specialized face APIs.
license: Apache-2.0
metadata:
author: acedatacloud
version: "1.0"
compatibility: Requires ACEDATACLOUD_API_TOKEN in .env file (get an API key at https://platform.acedata.cloud/console/applications).
---
# Face Transform
Analyze and transform faces through AceDataCloud's Face API suite.
## First-time setup
1. Install the official Skill with `clawhub install @acedatacloud/face-transform`. Check that the ClawHub publisher is **@acedatacloud**.
2. Sign in at [AceDataCloud → Applications](https://platform.acedata.cloud/console/applications), open **General application**, and check Face Transform access, balance, and current pricing. Copy its API key, or select **Manage Keys → Create** for a separate key. Copy the key value without `Bearer `; a `platform-...` management token is not a service API key.
3. If you enable **Allowed APIs** restrictions, include `/face/analyze` for the first example; other face actions need their own access. Advanced workflows below may call additional routes.
4. On the OpenClaw Gateway host, put `ACEDATACLOUD_API_TOKEN=your_api_key_here` in `~/.openclaw/.env`, then restart the Gateway and start a new session. For a direct terminal test, run `export ACEDATACLOUD_API_TOKEN="your_api_key_here"` in that shell. Never put the key in a prompt or commit an `.env` file.
5. Run the **Quick Start** below. If this workflow returns a task ID, query that same task until it finishes; do not submit the same billable request again just to check progress.
[Illustrated key setup, first run, and troubleshooting](https://github.com/AceDataCloud/Skills#first-run-with-clawhub-and-openclaw) · [Token details](https://github.com/AceDataCloud/Skills/blob/main/skills/_shared/authentication.md)
## Quick Start
```bash
curl -X POST https://api.acedata.cloud/face/analyze \
-H "Authorization: Bearer $ACEDATACLOUD_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"image_url": "https://cdn.acedata.cloud/lrbtcn.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.
```json
POST /face/analyze
{
"image_url": "https://example.com/photo.jpg"
}
```
Response includes detailed keypoints: `nose`, `mouth`, `left_eye`, `right_eye`, `left_eyebrow`, `right_eyebrow`, `contour` — each as arrays of `{x, y}` coordinates.
### 2. Face Beautification
```json
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`.
```json
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.
```json
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.
```json
POST /face/swap
{
"source_image_url": "https://example.com/source-face.jpg",
"target_image_url": "https://example.com/target-person.jpg"
}
```
### 6. Cartoon Style
```json
POST /face/cartoon
{
"image_url": "https://example.com/portrait.jpg"
}
```
### 7. Liveness Detection
```json
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 |
|-----------|----------|-------------|
| `source_image_url` | Yes | URL of the face to use (replaces the face) |
| `target_image_url` | 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 |
| `face_model_version` | No | Algorithm version (recommended: `3.0`) |
| `need_rotate_detection` | No | `0` = disabled (default), `1` = enabled |
## Gotchas
- All face APIs return results synchronously. `/face/swap` additionally supports an optional `callback_url` parameter 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 `source_image_url` (the face to apply) and `target_image_url` (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
© acedatacloud · Apache-2.0 · AceDataCloud/Skills