# AI 身形塑形

# 概览
AI 身形塑形接口：塑形与瘦身
用 AI 身体编辑，照片里更有底气！把身材瘦下去、塑形、优化，比例自然又亮眼。腰、手臂、大腿、胸，任何部位都能轻松调整；点一下就是自然出彩的效果。
## 接入指南
本指南将带您走完全流程：
AI 身形塑形接口的流程：
**接口地址：** `/s2s/v2.0/task/body-reshape`
**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`
**流程步骤：**
1. **准备图片上传：**
  - 准备好要上传的自拍照。
  - 调用 File 接口
`/s2s/v2.0/file`
 取得上传 URL 与对应的
`file_id`
。
  - 用提供的上传 URL 把自拍照上传上去。
2. **多人合照的可选预处理：**
  - 图中有多于一人时，请先对自拍照做预处理。
3. **设置 AI 身形塑形特效：**
  - 先选好合适的 AI 身形塑形参数。
4. **发起 AI 任务并取得 Task ID：**
  - 把
`file_id`
 连同选好的特效配置，通过 HTTP POST 请求送到
`/s2s/v2.0/task/body-reshape`
。
  - 响应会返回一个唯一的任务 ID，用于标识本次调用。
5. **轮询任务状态（持续检查）：**
  - 用取得的
`task_id`
 通过 HTTP GET 请求定期轮询任务状态（例如
`GET /s2s/v2.0/task/body-reshape/${task_id}`
）。
  - 持续留意：
  - `Task_status = "success"`
（处理完成）。
  - `Task_status = "error"`
（视情况排查或重试）。
  - 状态转为 success 后，按流程继续往下走。

这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。


---

* API Playground

用官方演练场交互式地体验和测试接口：
**API Playground：**
[http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-body-reshape/)


---

* 鉴权

- 请在请求头中以
**Bearer Token**
 方式带上您的 API 密钥：


```
Authorization: Bearer YOUR_API_KEY
```
API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。
*   1. 上传图片

您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。
* 上传接口


```
POST /s2s/v2.0/file
```
如果您已有公开可访问的图片 URL，这一步可以跳过。


---

*   1. 准备特效模板
* 预处理
输出以像素坐标表示的检测边界框。请用结果的索引在稍后创建 AI 身形塑形任务。


```
{
"timed": number,
"result": [
{
 "left": number,
 "top": number,
 "width": number,
 "height": number
}
]
}
```
* 特效模板 JSON Schema


```
{
"version": "1.0",
"index": 0,
"features": {
"arm": 0, // -100~100
"breast_left": 0, // -100~100
"breast_right": 0, // -100~100
"hip": 0, // -100~100
"hip_lift": 0, // -100~100
"leg": 0, // -100~100
"neck_left": 0, // 0~100
"neck_right": 0, // 0~100
"shoulder_left": 0, // -100~100
"shoulder_right": 0, // -100~100
"squared_shoulder_left": 0, // -100~100
"squared_shoulder_right": 0, // -100~100
"slim": 0, // -100~100
"taller": 0, // 0~100
"waist": 0, // -100~100
"belly": 0 // -100~100
}
}
```
index：预处理检测到的身体对象下标。选填，默认 0。
features：至少需要 1 项非零的 AI 身形塑形参数，不能全为 0。
* 请求示例（可直接发送）


```
{
 "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/body_reshape_02_7777218379.jpg",
 "version": "1.0",
 "index": 0,
 "features": {
"arm": 0,
"waist": -20,
"taller": 80,
"squared_shoulder_left": 10,
"squared_shoulder_right": 10,
"neck_left": 0,
"neck_right": 0,
"hip": 10,
"breast_left": 30,
"breast_right": 30,
"slim": -70,
"shoulder_left": 30,
"shoulder_right": 30,
"leg": -30,
"hip_lift": 0,
"belly": -50
 }
}
```
*   1. 创建 AI 身形塑形任务并轮询结果

图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。
* 创建任务接口


```
POST /s2s/v2.0/task/body-reshape
```
* 轮询接口


```
GET /s2s/v2.0/task/body-reshape/{task_id}
```


---

## 文件规格与错误码
* AI 身形塑形规格

**支持的自拍视角**
全身照，面部表情与身体姿态都要清楚可见。
![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_body_reshape_02_7777218379.jpg)
**可见性与姿态要求**
| **部位** | **源图必须满足的条件** |
|  --- | --- |
| **颈部** | 源图中颈部必须可见。 |
| **手臂** | 双臂——上臂、前臂与手——都要完整呈现。 |
| **腿部** | 整条腿都要在画面内。 |
| **臀部** | 臀部需要在画面内。 |
| **提臀** | 臀部需要在画面内。 |
| **肩部** | • 肩部必须可见。• 不允许举手。• 不允许 90° 侧身姿态。 |
| **腹部** | 腹部必须可见。 |
| **腰部** | 腰部必须可见。 |
| **胸部** | • 胸部区域需在画面内。• 拍摄范围应包含臀部（即不能是"不含臀部的半身照"）。• 胸部中间位置必须呈现。 |
| **显瘦** | 肩部需要在画面内。 |
| **增高** | • 臀部必须呈现。• 半身照应包含腿部（即腿部可见）。 |

**AI 身形塑形自定义参数说明**
| 类别 | 参数 | 作用 | 最小值（-100 / 0） | 最大值（100） |
|  --- | --- | --- | --- | --- |
| 手臂 | Intensity | 调整手臂粗细 | 细 | 粗 |
| 腹部 | Intensity | 调整腹部凸起 | 平坦 | 凸出 |
| 胸部 | Intensity（左 / 右） | 分别调整两侧胸部体积 | 平坦 | 饱满 |
| 提臀 | Intensity | 调整臀部曲线与上提（起到提臀效果） | 紧致（上提收紧） | 圆润（上提且更饱满） |
| 臀宽 | Intensity | 调整臀部整体宽度 | 窄 | 宽 |
| 腿部 | Intensity | 调整腿部粗细 | 细 | 粗 |
| 颈部 | Intensity（左 / 右） | 分别调整两侧颈部轮廓与收紧 | 原样（0） | 收进去 |
| 肩宽 | Intensity（左 / 右） | 分别调整两侧肩部跨度 | 窄 | 宽 |
| 肩型 | Intensity（左 / 右） | 分别调整两侧肩部角度与斜度 | 溜肩 | 平肩 |
| 显瘦 | Intensity | 调整整体身体曲线 | 纤瘦 | 曲线明显 |
| 增高 | Intensity | 调整整体人物身高 | 原样（0） | 更高 |
| 腰部 | Intensity | 调整腰线的宽窄 | 窄 | 宽 |

**说明：** *“左”与“右”以人物自身视角为准，不是观看者屏幕的左右侧。*


---

* 支持的格式与尺寸

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI 身形塑形 | 长边 <= 2048，短边 >= 320 | < 10MB | jpg/jpeg/png |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| RUNTIME_ERROR | 运行时发生未知错误 |
| PHOTO_DETECTION_FAIL | 用户图片无法正确处理，例如未检测到手 |
| PHOTO_CHECK_INVALID | 用户图片的姿态或尺寸不符合要求 |
| INPUT_ERROR | 输入文件格式有误 |
| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |

* 运行环境与依赖

| 示例代码语言 / 工具 | 建议运行时版本 |
|  --- | --- |
| cURL | - bash >= 3.2- curl >= 7.58 (modern TLS/HTTP support)- jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80- Firefox >= 74- Safari >= 13.1 |
| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |
| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |
| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |



---

## 点数消耗
| AI 功能 | 消耗点数 |
|  --- | --- |
| AI 身形塑形 V1.0 | 1 |



---

License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。

Type: http
Scheme: bearer

## Download OpenAPI description

 - [AI 身形塑形](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_body_reshape.yaml)

## V1.0

 - [POST /s2s/v2.0/task/body-reshape/pre-process](https://docs.perfectcorp.com/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process/post.md): 当源图中可能存在多个有效目标，或您的接入需要显式指定特效作用在哪个已检测目标上时，请使用预处理任务。若图片只有一个目标，且功能支持默认的 `index` 取值、您的应用也不需要手动挑选目标，这一步可以省略。 预处理任务会在源图中检测候选目标，并把它们的坐标返回在 `data.results.result` 中。结果数组里的每一项对应一个检测到的目标。请查看返回的坐标，与源图中您要处理的脸部或区域对
 - [GET /s2s/v2.0/task/body-reshape/pre-process/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1pre-process~1%7Btask_id%7D/get.md)
 - [POST /s2s/v2.0/task/body-reshape](https://docs.perfectcorp.com/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We
 - [GET /s2s/v2.0/task/body-reshape/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_body_reshape/v1.0/paths/~1s2s~1v2.0~1task~1body-reshape~1%7Btask_id%7D/get.md)