标准照片美化任务 API说明

本文档描述花容自有标准任务接口。

1. 接口概览

POST https://api.hrlj.cn/api/v1/task/add
Content-Type: application/json
Authorization: HMAC-SHA512-V1 Credential=<AK>,Signature=<签名>,Timestamp=<Unix秒时间戳>

请求参数校验、身份校验和账户校验均通过后，接口按门店套餐规则计费并创建异步任务：有效时长套餐内不扣片量，否则扣减 1 个片量。提交成功只表示任务已入队，不表示照片已经处理完成；最终结果通过 notifyUrl 回调。

重要：当前接口通常以 HTTP 200 返回业务成功和业务异常。调用方必须判断响应 JSON 的 code，不能只判断 HTTP 状态码。

2. 导入 Collection

导入文件：docs/postman/standard-task.postman_collection.json

Collection 已包含 Postman/Apifox 兼容的签名脚本、标准请求、响应断言和成功/异常示例。脚本使用 const CryptoJS = require('crypto-js')，未使用 Apifox 不支持的 pm.require。示例 URL 未替换时脚本会终止请求，避免误扣片量。

3. Collection 变量

变量	必填条件	说明
`base_url`	是	服务地址，默认 `https://api.hrlj.cn`，末尾不要加 `/`
`ak`	是	门店用户 Access Key
`sk`	是	门店用户 Secret Key；只参与本地签名，不放进请求体
`input_image_url`	是	原图 HTTP(S) 绝对 URL，服务端及 Linux consumer 均需可访问
`notify_url`	是	异步结果回调 HTTP(S) 绝对 URL
`storage_provider`	是	结果图存储类型，见下表；默认 `4`
`result_upload_url`	provider=4	结果图预签名上传绝对 URL
`result_key`	非 PRE 通常需要	结果对象 Key，例如 `retouch/2026/result.jpg`
`storage_bucket`	按存储类型	Bucket；ImageX 时填写 ServiceId
`storage_endpoint`	按存储类型	Endpoint 主机名，不带协议和路径
`storage_region_id`	按存储类型	区域 ID，例如 `cn-guangzhou`
`storage_token`	临时凭证时	STS Token 或存储服务 Token
`storage_access_key`	按存储类型	存储 AK
`storage_access_secret`	按存储类型	存储 SK
`storage_domain`	可选	自定义访问域名，写入 `auth.options.domain`
`trace_id`	自动生成	前置脚本生成的调用跟踪 ID
`server_task_id`	自动保存	成功后保存服务端任务 ID

AK/SK 建议放在 Environment 中，不要将真实值保存到共享 Collection。

4. 请求参数

请求体支持 protobuf JSON 的 camelCase 和 snake_case 字段名。本文统一使用 camelCase；同一字段不要重复传两种写法。

4.1 顶层字段

字段	类型	必填	校验/说明
`url`	string	是	原图绝对 URI，建议使用 HTTP(S) URL
`auth`	object	是	结果图片上传授权，见 4.2
`parameter`	object	是	输出和美化参数，见 4.3～4.9
`notifyUrl`	string	是	异步回调绝对 URI；snake_case 为 `notify_url`
`notifyAttach`	string	否	回调原样返回，最长 255；对象应先序列化为 JSON 字符串

4.2 `auth` 结果存储授权

字段	类型	必填	校验/说明
`provider`	integer	是	枚举 `1～6`，不能为 `0`
`preUrl`	string	provider=4	完整预签名上传 URL，必须是绝对 URI，不能只传对象 Key
`bucket`	string	按 provider	最长 255；ImageX 时为 ServiceId
`endpoint`	string	按 provider	主机名格式，不能带协议和路径
`regionId`	string	按 provider	最长 255；snake_case 为 `region_id`
`token`	string	临时授权时	最长 1024
`accessKey`	string	按 provider	最长 1024
`accessSecret`	string	按 provider	最长 1024
`uploadKey`	string	非 PRE 通常需要	非空时长度 `1～1024`
`options`	object<string,string>	否	最多 32 对，值必须为字符串

provider	存储类型	建议提供的字段
`1`	AWS S3 / S3 兼容	`bucket`、`endpoint`、`regionId`、`accessKey`、`accessSecret`、`uploadKey`，临时凭证另加 `token`
`2`	七牛	`bucket`、`token`、`uploadKey`；访问域名可放 `options.domain`
`3`	阿里云 OSS	`bucket`、`endpoint`、`accessKey`、`accessSecret`、`uploadKey`，临时凭证另加 `token`
`4`	PRE 预签名上传	`preUrl`；入库时会作为实际上传地址
`5`	火山 TOS	`bucket`、`endpoint`、`regionId`、`accessKey`、`accessSecret`、`uploadKey`，临时凭证另加 `token`
`6`	火山 ImageX	`bucket`（ServiceId）、`regionId`、`accessKey`、`accessSecret`、`uploadKey`，临时凭证另加 `token`

提交阶段只校验格式，不会连接对象存储验证授权。Bucket、Token 或预签名 URL 无效时，任务可能提交成功但随后上传失败。

4.3 `parameter` 和 `output`

字段	类型	必填	范围/说明
`parameter.version`	integer	是	`>=1`，当前传 `1`
`parameter.output`	object	是	输出参数
`parameter.params`	object	是	美化参数主体，允许传 `{}`
`parameter.ageRange`	int[2]	否	男女共用 `[最小年龄,最大年龄]`，每项 `0～100`
`parameter.menAgeRange`	int[2]	否	男性独立范围，优先于 `ageRange`
`parameter.womenAgeRange`	int[2]	否	女性独立范围，优先于 `ageRange`
`output.quality`	integer	是	`50～100`，建议 `95`；省略后的零值不合法
`output.maxSize`	integer	否	`>=0`，`0` 表示不限制
`output.waterMark`	string	否	水印配置，最长 255
`output.ppi`	integer	否	`>=0`，`0` 表示不调整
`output.keepOriginalSize`	integer	否	`0/1`，是否保持原图尺寸

协议层当前只校验年龄数组长度和 0～100；调用方还应保证最小年龄不大于最大年龄。

4.4 基础调整和开关

字段	类型/范围	作用
`intellectColorAdjust`	integer `0/1`	智能色彩增强
`autoExposure`	integer `0/1`	自动曝光，与智能色彩增强独立
`temperature` / `tint`	integer `-100～100`	色温 / 色调
`saturation` / `vibrance`	integer `-100～100`	饱和度 / 自然饱和度
`exposure` / `brightness`	integer `-100～100`	曝光 / 亮度
`blacks` / `shadows` / `highlights` / `whites`	integer `-100～100`	黑色 / 阴影 / 高光 / 白色
`contrast` / `clarity` / `dehaze`	integer `-100～100`	对比度 / 清晰度 / 祛雾
`sharpen` / `denoiseLum` / `denoiseColor`	integer `0～100`	锐化 / 亮度降噪 / 彩色降噪
`backgroundSmooth`	integer `0/1`	背景平滑
`backgroundGoofRemove`	integer `0/1`	背景穿帮去除
`backgroundRefine`	integer `0/1`	背景修复
`bodyHeight`	integer `0～100`	身高调整

未传数字字段按 0 处理。0 对开关表示关闭，对调整项表示不调整。

4.5 人像效果数组

大部分人像参数为长度固定的 int[4]。当前 Linux consumer 的映射为：

[男性成年值, 女性成年值, 兼容保留值, 少年值]

consumer 会把第 1 位用于男性成年/老年，并作为女性老年的兼容值；第 2 位用于女性成年；第 4 位用于男女少年；第 3 位当前未独立消费。不区分人群时建议四位相同，例如 [40,40,40,40]。

以下为 int[4] 且每项 0～100：

字段	作用	字段	作用
`backgroundFlyawaysRemove`	背景祛碎发	`bodyFlyawaysRemove`	人物祛碎发
`nevusRemove`	祛痣	`faceDefectRemove`	面部祛瑕疵
`bodyDefectRemove`	身体祛瑕疵	`faceNeutralGrey`	面部中性灰
`bodyNeutralGrey`	身体中性灰	`faceSmooth`	面部匀肤
`bodySmooth`	身体匀肤	`faceTextureEnhance`	面部纹理增强
`bodyTextureEnhance`	身体纹理增强	`skinWhite`	皮肤美白
`skinRed`	皮肤红润	`skinGloss`	皮肤光泽
`skinShadow`	皮肤阴影	`skinHighlights`	皮肤高光
`wrinkleForeheadRemove`	祛抬头纹	`shinyClean`	祛油光
`faceLightBalance`	光影平整	`faceLightDefinition`	光影立体
`faceContour`	面部轮廓	`pouchRemove`	祛黑眼圈
`wrinklePeriorbitalRemove`	祛眼周纹	`wrinkleNasolabialRemove`	祛法令纹
`lipRemove`	祛唇纹	`wrinkleNeckRemove`	祛颈纹
`doubleChinRemove`	祛双下巴	`beautyBellyRemove`	祛妊娠纹
`clothesWrinkleThinRemove`	祛细褶皱	`clothesWrinkleThickRemove`	祛粗褶皱
`faceAutoBeauty`	智能面部美化	`eyeBright`	亮眼
`faceSkinUnify`	面部肤色统一	`bodySkinUnify`	身体肤色统一
`faceLowFreqSmooth`	面部低频磨皮	`bodyLowFreqSmooth`	身体低频磨皮
`faceHighlights`	面部高光	`teethWhite`	牙齿美白
`chinReduce`	削下巴

teethBeauty 为 int[4]，但每项只能为 0/1，表示牙齿修复开关。

以下为液化/形变 int[4]，每项 -100～100：

字段	作用	字段	作用
`shrinkHead`	小头	`faceV`	V 脸
`faceSize`	大小脸	`faceSlim`	瘦脸
`hairline`	发际线	`mandibleSlim`	瘦颌骨
`zygomaticBoneSlim`	瘦颧骨	`chinAugmentation`	垫下巴
`chinHeight`	下巴高度	`browLeftHeight` / `browRightHeight`	左/右眉高度
`browLeftTilt` / `browRightTilt`	左/右眉倾斜	`eyeLeftSize` / `eyeRightSize`	左/右眼大小
`eyeLeftWidth` / `eyeRightWidth`	左/右眼宽	`eyeDistance`	眼距
`eyeLeftSlant` / `eyeRightSlant`	左/右眼倾斜	`noseSize` / `noseHeight`	鼻子大小/高度
`mouthSize` / `mouthHeight` / `mouthWidth`	嘴巴大小/高低/宽度	`lipTopThickness` / `lipBottomThickness`	上/下唇厚薄
`faceShadow`	面部阴影

bodyAutoSlim 为 int[5]，每项 0～100。前四位采用上述人群位，第五位为孕肚保护值。

4.6 LUT、曲线、HSL、暗角和颗粒

字段	子字段和范围	说明
`luts`	`[{"path":string,"opacity":0～100}]`	LUT 列表；`opacity=0` 等同关闭
`rgbCurves`	`all/red/green/blue` 点数组	每点 `{x:0～255,y:0～255}`
`hsl`	`hue/saturation/lightness`	各固定 8 项，每项 `-100～100`
`vignette`	`amount/size/feather/roundness`	均为 `0～100`
`grain`	`count/size/value`	数量、大小、强度，均为 `0～100`
`selectiveColor.mode`	`0/1`	可选色模式
`selectiveColor.red/green/blue/cyan/magenta/yellow/white/black/neutral`	int[4]	各固定 4 项，每项 `-100～100`

HSL 的 8 位颜色通道顺序由处理 SDK 约定，调用方应沿用预设顺序且不得增减长度。

4.7 换背景和换天空

字段	类型/范围	说明
`replaceBackground.enable`	`0/1`	是否换背景
`replaceBackground.path`	string	背景素材路径
`replaceBackground.rgb`	int[3] `0～255`	背景 RGB
`replaceBackground.opacity` / `edgeIntensity`	`0～100`	透明度 / 边缘强度
`replaceSky.enable` / `syncBasicAdjust`	`0/1`	是否开启 / 是否同步基础调整
`replaceSky.path`	string	天空素材路径，空时无效
`replaceSky.opacity` / `blur`	`0～100`	透明度 / 模糊；透明度 0 等同关闭
`replaceSky.xPos` / `yPos`	`-100～100`	水平 / 垂直位置
`replaceSky.exposure` / `contrast` / `temperature` / `tint` / `saturation`	`-100～100`	天空基础调整
`replaceSky.edgeEffect` / `colorBias` / `scale`	`0～100`	边缘过渡 / 色彩偏向 / 缩放

4.8 美妆 `cosmetic`

enable 为 0/1。foundation、lipstick、brow、iris、eyeShadow、blush、groom、lashes 均为 CosmeticItems[4]，依次表示粉底、口红、眉毛、虹膜、眼影、腮红、美容和睫毛。

每个 CosmeticItems 格式为 {"items":[...]}，非空时允许 1～10 项。单项格式：

{"type":"素材或效果类型","intensity":50,"color":[255,128,96]}

type 不能为空，intensity 为 0～100，color 非空时必须为 3 项且每项 0～255。

5. 请求示例

{
  "url": "https://cdn.example.test/input.jpg?signature=...",
  "auth": {
    "provider": 4,
    "preUrl": "https://bucket.example.test/output.jpg?signature=..."
  },
  "parameter": {
    "version": 1,
    "output": {
      "quality": 95,
      "maxSize": 0,
      "waterMark": "",
      "ppi": 0,
      "keepOriginalSize": 0
    },
    "params": {
      "intellectColorAdjust": 0,
      "autoExposure": 1,
      "faceDefectRemove": [40, 40, 40, 40],
      "faceNeutralGrey": [30, 30, 30, 30],
      "faceAutoBeauty": [20, 20, 20, 20],
      "eyeBright": [20, 20, 20, 20]
    },
    "ageRange": [12, 60]
  },
  "notifyUrl": "https://client.example.test/retouch/callback",
  "notifyAttach": "{\"source\":\"postman\",\"traceId\":\"standard-001\"}"
}

6. 签名算法

timestamp = 当前 Unix 秒时间戳
rawBody   = 变量替换后、最终实际发送的原始 JSON 字符串
data      = timestamp + rawBody
signature = lowercase_hex(HMAC-SHA512(key=SK, message=data))
header    = HMAC-SHA512-V1 Credential=AK,Signature=signature,Timestamp=timestamp

时间戳单位是秒，与服务端误差不能超过 5 分钟。
三个认证字段之间不要加空格。
签名覆盖原始请求体；签名后修改空格、换行、字段顺序或格式化 JSON 都会验签失败。
签名为小写十六进制字符串。

7. 同步返回值

成功响应：

{
  "code": 200,
  "message": "success",
  "data": {"id": "66bf1234567890abcdef1234"}
}

字段	类型	说明
`code`	integer	业务码；`200` 表示创建成功
`message`	string	成功时为 `success`
`data.id`	string	服务端生成的 24 位任务 ID，用于日志和回调关联

失败响应：

{
  "code": 1001,
  "message": "参数错误:invalid SdkTaskAddRequest.Parameter: ..."
}

失败时没有 data。客户端应记录完整 message，程序分支以 code 为准。

8. 本接口异常码

code	含义	常见原因	处理建议
`200`	成功	已按套餐规则计费并入队	等待回调，不要重提
`1001`	参数错误	JSON 绑定失败、URI 非法、数值越界、数组长度错误、`provider=0`	修正请求
`1005`	内部服务器错误	未分类内部异常	稍后重试前先核对是否已创建
`1006`	数据库错误	账户数据解析等已归类的数据库异常	核对账户状态后再重试
`1100`	缺少认证头	未执行脚本或缺少 `Authorization`	修正请求头
`1101`	认证头格式错误	逗号后有空格、字段缺失、时间戳不是整数秒	修正签名实现
`1300`	用户不存在	AK 不存在或错误	更换正确 AK
`1303`	用户已禁用	AK 对应账户被禁用	联系管理员
`1500`	门店不存在	用户绑定门店不存在	联系管理员
`1600`	余额不足	无可用片量/有效套餐	充值后重提
`1604`	扣费失败	余额更新冲突或账户写入失败	先核对账单再决定重试
`1801`	签名无效	SK 错误、签名 body 不一致、编码错误	重新计算签名
`1802`	签名已过期	超出 ±5 分钟或使用毫秒时间戳	校时并重新签名
`1803`	不支持的算法	算法不是 `HMAC-SHA512-V1`	修改算法名

1002/1003/1004 是统一响应层保留的未授权、禁止访问和资源不存在码，主流程通常不直接产生，调用方可作通用兼容。

参数异常应从 message 最末层字段定位。例如 invalid Params.IntellectColorAdjust: value must be in list [0 1] 表示 parameter.params.intellectColorAdjust 只能传整数 0/1，不能传 true/false。

9. 异步回调

回调请求为 POST application/json：

{
  "code": 2,
  "message": "success",
  "data": {
    "id": "66bf1234567890abcdef1234",
    "attach": "{\"source\":\"postman\",\"traceId\":\"standard-001\"}"
  }
}

字段	类型	说明
`code`	integer	任务状态，不是提交接口业务码
`message`	string	处理说明；失败时为失败原因
`data.id`	string	与提交响应 `data.id` 一致
`data.attach`	string	`notifyAttach` 原样字符串

回调 code	状态	说明
`2`	完成	处理并上传完成
`-1`	失败	下载、处理或上传失败，原因见 `message`
`-2`	取消	任务被取消
`0`	待处理	内部保留状态，正常终态回调通常不用
`1`	处理中	内部保留状态，正常终态回调通常不用

接收方必须返回：

HTTP/1.1 200 OK
Content-Type: text/plain

success

HTTP 状态不是 200，或响应体不是精确的小写文本 success，都会被判为通知失败并按配置重试。不要返回 JSON、Success 或附加内容。

10. 重试和幂等

标准接口没有调用方自定义任务 ID，也没有幂等键。网络超时后盲目重发可能重复创建任务并再次扣片量。

收到响应时按 code 处理。
仅在连接中断、完全无响应时进入人工或业务侧核对流程。
保留请求时间、AK（不要记录 SK）、trace_id、响应和回调日志，确认未创建后再重试。
业务侧如需幂等，应建立请求状态表；

11. 常见排查

pm.require is not a function：使用本 Collection，不要改成 pm.require。
请先配置 ak 和 sk：在 Collection 或 Environment 中填写实际值并选中正确环境。
PreUrl: value must be absolute：preUrl 必须是完整 https://... 上传 URL，不能是对象 Key。
签名无效：确认对变量替换后的最终 body 签名，并关闭签名后自动格式化 body 的功能。
提交成功但处理失败：检查原图有效期、consumer 网络、结果上传授权及回调服务。
PRE 上传失败：预签名 URL 必须允许 consumer 的上传方法，并在任务执行期间有效。

最终校验规则以 api/api.proto 和 api/params/params.proto 为准。