TUTUCLOUD 人像服务 API 文档

接口鉴权

参数 sign 生成步骤：

  1. 抽取所有请求参数 (类型为 file 的参数不参与签名)。
  2. 对 参数名 以字典升序 (a-z) 进行排序。
     sortedParams = {
     "key1": "value1",
     "key2": "value2"
 }
  3. 以 参数名参数值 的形式拼接排序后的参数。
     stringParams = "key1value1key2value2"
  4. 把从控制台创建应用后获取的私钥 api_secret 作为后缀拼接到上一步生成的字符串后面, 得到 待签名字符串。
     stringParams = "key1value1key2value2api_secret"
  5. 最后再对 待签名字符串 用 MD5 摘要算法，得到签名结果 sign (32位小写)。
     sign = md5("key1value1key2value2api_secret")

签名示例：

私钥 api_secret = "my_api_secret"

请求参数 = {
   "url": "http://my.test/my.jpg", 
   "api_key": "my_api_key",
   "timestamp": 123456
}

排序后参数 = {
    "api_key": "my_api_key",
    "timestamp": 123456,
    "url": "http://my.test/my.jpg"
}

待签名字符串 = "api_keymy_api_keytimestamp123456urlhttp://my.test/my.jpgmy_api_secret"

sign = "be83843c50dbfe8211256694c1cc5c58"

上传人脸融合模板

POST https://api.portrait.tutucloud.com/v1/facefuse/model

HTTP header

Content-Type: multipart/form-data

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
img file img, img_base64, url 3选1 图片文件
img_base64 string img, img_base64, url 3选1 图片文件 base64 编码
url string img, img_base64, url 3选1 图片URL
timestamp int 否 unix时间戳, 从接口 /timestamp 获取

cURL 请求示例

curl -X POST \
https://api.portrait.tutucloud.com/v1/facefuse/model \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F img=@test.jpg

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "created": "1553074748",
        "faces": [                  // 人脸检测框 位置信息 (归一化)
            {
                "index": 0,
                "x": 0.375,
                "y": 0.2709832191467285,
                "width": 0.18828125298023225,
                "height": 0.2889688313007355
            }
        ],
        "img": "https://file.portrait.tutucloud.com/g01/M00/01/20/CgoKHFzIDxWARE-FAAG2o9XdQVA533.jpg",
        "model_id": "477cbf8a9a5242fb795b12789b297039"
    }
}

删除人脸融合模板

DELETE https://api.portrait.tutucloud.com/v1/facefuse/model/<model_id>

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
timestamp int 否 unix时间戳, 从接口 /timestamp 获取

cURL 请求示例

curl -X DELETE \
'https://api.portrait.tutucloud.com/v1/facefuse/model/477cbf8a9a5242fb795b12789b297039?api_key=39802830831bed188884e193d8465226&sign=04b29480233f4def5c875875b6bdc3b1'

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "deleted": 1
    }
}

获取已上传人脸融合模板列表

GET https://api.portrait.tutucloud.com/v1/facefuse/model

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
page_index int 否 页数, 默认 1
page_size int 否 每页记录数, 默认 20, 最大为 60
timestamp int 否 unix时间戳, 从接口 /timestamp 接口获取

cURL 请求示例

curl -X GET \
  'https://api.portrait.tutucloud.com/v1/facefuse/model?api_key=39802830831bed188884e193d8465226&sign=04b29480233f4def5c875875b6bdc3b1&page_size=2&page=1'

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "total": 15,
        "count": 2,
        "models": [
            {
                "created": "1553074748",
                "faces": [                  // 人脸检测框 位置信息 (归一化)
                    {
                        "index": 0,
                        "x": 0.375,
                        "y": 0.2709832191467285,
                        "width": 0.18828125298023225,
                        "height": 0.2889688313007355
                    }
                ],                
                "img": "https://file.portrait.tutucloud.com/g01/M00/01/20/CgoKHFzIDxWARE-FAAG2o9XdQVA533.jpg",
                "model_id": "477cbf8a9a5242fb795b12789b297038"
            },
            {
                "created": "1553074749",
                "faces": [],
                "img": "https://file.portrait.tutucloud.com/g01/M00/01/20/CgoKHFzIDxWARE-FAAG2o9XdQVA534.jpg",
                "model_id": "477cbf8a9a5242fb795b12789b297039"
            }
        ]
    }
}

人脸融合

POST https://api.portrait.tutucloud.com/v1/facefuse

HTTP header

Content-Type: multipart/form-data

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
img file img, img_base64, url 3选1 图片文件
img_base64 string img, img_base64, url 3选1 图片文件 base64 编码
url string img, img_base64, url 3选1 图片URL
model_id string 是 模板ID, 需要先调用 上传模板 接口
timestamp int 否 unix时间戳, 从接口 /timestamp 获取
output_format string 否 结果图片返回形式, 可选值 [url: 图片链接, base64: 图片文件 base64 编码], 默认以 url 返回

cURL 请求示例

curl -X POST \
https://api.portrait.tutucloud.com/v1/facefuse \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F model_id=477cbf8a9a5242fb795b12789b297039 \
-F img=@test.jpg

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "input": "https://file.portrait.tutucloud.com/g03/M00/01/0C/wKjIZ1yq69aAecIIAAD5oHJ2ocA15.jpg",
        "output": "https://file.portrait.tutucloud.com/g04/M00/01/0C/wKjIaFyq69qACZArAADvHmvAzBk512.jpg"
    }
}

多人脸融合

POST https://api.portrait.tutucloud.com/v1/facefuse/multi

HTTP header

Content-Type: multipart/form-data

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
img file img, img_base64, url 3选1 图片文件 列表
img_base64 json img, img_base64, url 3选1 图片文件 base64 编码 数组
url json img, img_base64, url 3选1 图片URL 数组
face_index json 是 人脸位置索引 数组, face_index 为 上传模板 接口返回: data.models.faces.index, face_index 需和上传的图片列表一一对应
model_id string 是 模板ID, 需要先调用 上传模板 接口
timestamp int 否 unix时间戳, 从接口 /timestamp 获取
output_format string 否 结果图片返回形式, 可选值 [url: 图片链接, base64: 图片文件 base64 编码], 默认以 url 返回

cURL 请求示例 (img)

curl -X POST \
https://api.portrait.tutucloud.com/v1/facefuse/multi \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F model_id=477cbf8a9a5242fb795b12789b297039 \
-F 'face_index=[1,3]' \
-F img=@face1.jpg \
-F img=@face3.jpg

cURL 请求示例 (url)

curl -X POST \
https://api.portrait.tutucloud.com/v1/facefuse/multi \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F model_id=477cbf8a9a5242fb795b12789b297039 \
-F 'face_index=[1,3]' \
-F 'url=["http://my.img/face_1.jpg","http://my.img/face_3.jpg"]'

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "input_list": [
            {
                "face_index": 1,
                "input": "https://file.portrait.tutucloud.com/img/face_1.jpg",
            },
            {
                "face_index": 3,
                "input": "https://file.portrait.tutucloud.com/img/face_3.jpg",
            }
        ],
        "output": "https://file.portrait.tutucloud.com/g04/M00/01/0C/wKjIaFyq69qACZArAADvHmvAzBk512.jpg"
    }
}

人脸微整形

POST https://api.portrait.tutucloud.com/v1/plastic

HTTP header

Content-Type: multipart/form-data

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
img file img, img_base64, url 3选1 图片文件
img_base64 string img, img_base64, url 3选1 图片文件 base64 编码
url string img, img_base64, url 3选1 图片URL
args json 否 微整形参数, 详见下表
timestamp int 否 unix时间戳, 从接口 /timestamp 获取
output_format string 否 结果图片返回形式, 可选值 [url: 图片链接, base64: 图片文件 base64 编码], 默认以 url 返回

整形参数 args

参数名 值范围 默认值 说明
eyeEnlargeSize [0.0, 1.0] 0.6 大眼
chinSize [0.0, 1.0] 0.5 瘦脸
noseSize [0.0, 1.0] 0.0 瘦鼻
mouthWidth [-1.0, 1.0] 0.0 嘴宽
eyebrowArch [-1.0, 1.0] 0.0 眉宽
eyeDis [-1.0, 1.0] 0.0 眼距
eyeAngle [-1.0, 1.0] 0.0 眼角
jawSize [-1.0, 1.0] 0.0 下巴

cURL 请求示例

curl -X POST \
https://api.portrait.tutucloud.com/v1/plastic \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F 'args={"eyeEnlargeSize": 1.2, "chinSize": 0.05, "jawSize": -0.01}' \
-F img=@test.jpg

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "input": "https://file.portrait.tutucloud.com/g03/M00/01/0C/wKjIZ1yq69aAecIIAAD5oHJ2ocA15.jpg",
        "output": "https://file.portrait.tutucloud.com/g04/M00/01/0C/wKjIaFyq69qACZArAADvHmvAzBk512.jpg"
    }
}

人像美颜

POST https://api.portrait.tutucloud.com/v1/beautify

HTTP header

Content-Type: multipart/form-data

参数

参数名 类型 是否必填 说明
api_key string 是 应用 api_key
sign string 是 参数签名
img file img, img_base64, url 3选1 图片文件
img_base64 string img, img_base64, url 3选1 图片文件 base64 编码
url string img, img_base64, url 3选1 图片URL
mode string 否 美颜模式, 可选值: [natural: 精准, moist: 极致], 默认值：natural
args json 否 微整形参数, 详见下表
timestamp int 否 unix时间戳, 从接口 /timestamp 获取
output_format string 否 结果图片返回形式, 可选值 [url: 图片链接, base64: 图片文件 base64 编码], 默认以 url 返回

美颜参数 args

参数名 值范围 默认值 说明
smoothing [0.0, 1.0] 0.5 磨皮
fair [0.0, 1.0] 0.0 美白
ruddy [0.0, 1.0] 0.0 红润

cURL 请求示例

curl -X POST \
https://api.portrait.tutucloud.com/v1/beautify \
-H 'content-type: multipart/form-data' \
-F api_key=39802830831bed188884e193d8465226 \
-F sign=04b29480233f4def5c875875b6bdc3b1 \
-F mode=moist \
-F 'args={"smoothing": 0.8, "ruddy": 1.0}' \
-F img=@test.jpg

返回示例

{
    "message": "Success",
    "code": 200,
    "data": {
        "input": "https://file.portrait.tutucloud.com/g03/M00/01/0C/wKjIZ1yq69aAecIIAAD5oHJ2ocA15.jpg",
        "output": "https://file.portrait.tutucloud.com/g04/M00/01/0C/wKjIaFyq69qACZArAADvHmvAzBk512.jpg"
    }
}

获取时间戳

GET https://api.portrait.tutucloud.com/timestamp

如请求其它接口时传了timestamp参数, 服务器则会和当前时间进行比较, 如晚于服务器当前时间超过60秒, 则会拒绝服务。

参数

无

返回示例

{
  "message": "Success",
  "code": 200,
  "data": {
    "timestamp": 1553249584
  }
}

返回码

返回码 说明
200 请求成功
4000 无效的请求
4001 无效的 api_key 参数
4002 缺少必填参数
4003 签名验证失败
4004 获取上传文件失败
4005 无效的 model_id 参数
4006 无效的 timestamp 参数
4007 文件格式不支持
4008 文件大小超过最大限制
4009 从 url 下载文件失败
4010 服务未开通
4011 余额不足
4012 请求数超过最大限制
4013 无效的美颜 mode 参数
4014 url 输入文件未找到或已过期
4100 args 参数格式错误, 必须为 json
4101 url 参数格式错误, 必须为 json
4102 img_base64 参数格式错误, 必须为 json
4103 face_index 参数格式错误, 必须为 json
4200 未检到人脸
4201 face_index 和 上传文件 数量不匹配
4202 错误的 face_index 值
500 内部服务错误
5001 服务处理失败
5003 服务不可用

tips

  • 图片参数：当图片参数 img , img_base64, url 同时传入时, 服务器会以 img > img_base64 > url 的优先级顺序去获取图片。
  • 提升效率：根据使用场景，若需要对同一张图片进行不同的参数调节，如切换人脸融合模板或者是调节微整形、美颜参数，只需要将首次请求后返回的 input 字段作为图片参数 url 传入， 即可节省重复传输图片的时间。

  • 在线技术支持
  • 专业售前售后团队
  • 版本定期更新
  • 全方位解决方案

商务合作

关注我们

qrcode

©2019-2025 TUTUCLOUD. All Rights Reserved. 杭州元凡视觉智能科技有限公司 | 浙ICP备14040447号-1 | 浙公网安备33010602001649号