face-transform

人脸变换

通过 AceDataCloud 的人脸 API 套件分析和变换人脸。

首次设置

1. 使用 clawhub install @acedatacloud/face-transform 安装官方 Skill。请确认 ClawHub 发布者为 @acedatacloud。
2. 登录 AceDataCloud → Applications，打开 General application，检查 Face Transform 的访问权限、余额和当前定价。复制其 API 密钥，或选择 Manage Keys → Create 创建单独的密钥。复制密钥值时不要包含 Bearer ；platform-... 管理令牌不是服务 API 密钥。
3. 如果启用了 Allowed APIs 限制，请为第一个示例添加 /face/analyze；其他人脸操作需要各自的访问权限。下方的高级工作流可能会调用其他路由。
4. 在 OpenClaw Gateway 主机上，将 ACEDATACLOUD_API_TOKEN=your_api_key_here 写入 ~/.openclaw/.env，然后重启 Gateway 并开始新会话。若要直接在终端测试，请在该 shell 中运行 export ACEDATACLOUD_API_TOKEN="your_api_key_here"。切勿将密钥放入提示词或提交 .env 文件。
5. 运行下方的 Quick Start。如果此工作流返回任务 ID，请查询同一个任务，直到任务完成；不要为了查看进度而重复提交同一个计费请求。

密钥设置、首次运行和故障排除图解 · 令牌详情

快速开始

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"}'

可用 API

端点	用途	描述
POST /face/analyze	人脸检测	检测人脸关键点（每张脸 90 个以上）
POST /face/beautify	美颜	应用美颜／装饰效果
POST /face/change-age	年龄变换	让人脸看起来更老或更年轻
POST /face/change-gender	性别转换	变换人脸的性别特征
POST /face/swap	人脸替换	用一个人的脸替换另一个人的脸
POST /face/cartoon	卡通风格	将肖像转换为动画／卡通风格
POST /face/detect-live	活体检测	检测人脸图像是否来自真人

工作流

1. 人脸分析

检测人脸并提取每张脸的 90 个以上关键点。

POST /face/analyze
{
  "image_url": "https://example.com/photo.jpg"
}

响应包含详细的关键点：nose、mouth、left_eye、right_eye、left_eyebrow、right_eyebrow、contour，每项均为 {x, y} 坐标数组。

2. 人脸美化

POST /face/beautify
{
  "image_url": "https://example.com/portrait.jpg"
}

3. 年龄变换

age_infos 为必填项，每张脸对应一条记录，每条记录包含目标 age。

POST /face/change-age
{
  "image_url": "https://example.com/portrait.jpg",
  "age_infos": [{ "age": 60 }]
}

4. 性别转换

gender_infos 为必填项。gender 为 0 时将男性面孔变为女性面孔，为 1 时则相反。

POST /face/change-gender
{
  "image_url": "https://example.com/portrait.jpg",
  "gender_infos": [{ "gender": 1 }]
}

5. 人脸替换

将目标图像中的人脸替换为源图像中的人脸。

POST /face/swap
{
  "source_image_url": "https://example.com/source-face.jpg",
  "target_image_url": "https://example.com/target-person.jpg"
}

6. 卡通风格

POST /face/cartoon
{
  "image_url": "https://example.com/portrait.jpg"
}

7. 活体检测

POST /face/detect-live
{
  "image_url": "https://example.com/face-photo.jpg"
}

参数

通用参数

参数	必填	描述
image_url	是（除 /face/swap 外的所有接口）	源人脸图像 URL

/face/change-age

参数	必填	描述
age_infos	是	{ "age": <number> } 数组，每张脸对应一条。省略此项会返回 400 age_infos is required

/face/change-gender

参数	必填	描述
gender_infos	是	{ "gender": 0|1 } 数组——0 表示男性→女性，1 表示女性→男性。每条记录还可选填 face_rect

/face/swap

参数	必填	描述
source_image_url	是	要使用的人脸 URL（用于替换）
target_image_url	是	要将人脸放入的图像 URL
callback_url	否	用于异步发送结果的 Webhook URL
timeout	否	最长等待时间，单位为秒（默认值：120）

/face/beautify

参数	必填	描述
image_url	是	图片 URL
smoothing	否	磨皮程度 0–100（默认值：10）
whitening	否	美白程度 0–100（默认值：30）
face_lifting	否	瘦脸程度 0–100（默认值：70）
eye_enlarging	否	大眼程度 0–100（默认值：70）

/face/analyze

参数	必填	描述
image_url	是	图片 URL
mode	否	0 = 分析所有人脸（默认值），1 = 仅分析最大的人脸
face_model_version	否	算法版本（推荐：3.0）
need_rotate_detection	否	0 = 禁用（默认值），1 = 启用

注意事项

• 所有人脸 API 都会同步返回结果。/face/swap 还支持可选的 callback_url 参数，用于异步接收结果（传入该参数后，结果将通过 webhook 返回，无需在当前请求中等待）
• 人脸分析会为每张检测到的人脸返回 90 多个关键点，并支持分析单张图片中的多张人脸
• 人脸交换使用 source_image_url（要应用的人脸）和 target_image_url（要将人脸应用到的身体）
• 所有 API 目前都处于 Alpha 阶段，接口可能会发生变化
• 为获得最佳效果，图片中应包含清晰可见、正面朝向的人脸
• 活体检测有助于区分真人照片与打印照片或屏幕照片