AI写真_API专区_云市场-阿里云



POST/swapface

请求参数（Query）

无参数

请求参数（Body）

无参数



接口信息

调用地址：https://swapface-api.segapi.com/swapface

请求方式：POST

返回类型：JSON

API 调用：API 简单身份认证调用方法（APPCODE）API 签名认证调用方法（AppKey & AppSecret）

获取认证：AppKey & AppCode

接口参数

请求参数（Header）

无参数

请求参数（Query）

无参数

请求参数（Body）

无参数

云市场服务保障

*请勿线下交易！90%的欺诈、纠纷、资金盗取均由线下交易导致。

商品介绍

产品亮点

我们是适合AI写真的换脸技术，独有的特点包括： 1，生成图的脸型与用户完全一致，人脸相似度在96%以上，同时保持目标脸的光影和妆容。 2，可以指定生成图中的脸部表情更接近源脸还是目标脸，当选择接近源脸时，人脸相似度可达98%以上。

产品说明

产品功能

根据客户发送的写真模板图和用户照片，生成制作后的写真照片。

可提供的服务

我们提供服务端接口调用API，客户仅需按我们的接入文档实现相关调用代码即可。

调用说明

这是一个异步接口，调用后，不会直接返回制作后的结果图，而是通过异步通知的形态，将结果发回给调用者。
调用此接口需要进行签名等操作，以确保调用者的身份和数据安全，签名方式，可以参考阿里云文档关于签名部分。

接口说明

1、发起AI写真任务提交接口

https://swapface-api.segapi.com/swapface

参数形式：JSON，比如：

{

"source_url": "https://user/photo/url",

"target_url": "https://target/template/photo/url",

"notify_url": "https://the/result/notify/url",

"user_expression_weight":0.5,

"timeout": 180

}

参数说明

source_url：字符串，必填，待制作的用户图片的url，必须是一个有效的图片的url，图片格式为jpg或者png，建议图片尺寸为640x640到2500x2500个像素之间。要求图中只包含一张人脸，且人脸清晰、完整，占比不太小，脸部没有大的角度，正脸效果最佳。

target_url：字符串，必填，模板图片的url，必须是一个有效的图片的url，图片格式为jpg或者png，建议图片尺寸为800x800到2000x2000个像素之间。要求图中只包含一张人脸，且人脸清晰、完整，占比不太小，脸部没有大的角度，正脸效果最佳。

notify_url：字符串，必填，结果通知接口url。由于本接口是一个异步接口，也就是说本接口调用后，并不会直接返回制作后的结果图，而是在任务执行后，通过异步的方式通知到调用者。所以调用者需要实现一个接受任务通知的异步接口，并将接口的地址放入此参数中。

user_expression_weight：[0, 1.0]之间的浮点数，选填，默认值为0.5。表示生成图的表情更接近源脸还是目标脸，0表示生成图的人脸表情接近目标脸，1.0表示生成图的人脸表情跟源脸相同。

timeout：数字，选填，调用者预期的任务超时时间，单位为秒。但此参数不给定时，默认超时时间为7200秒，当给了超时时间，到达超时时间后，本任务就不再执行。任务超时后，本接口服务将会通过notify_url参数给出的接口地址，将超时错误发送给调用者。所以调用者无需自己维护一个超时队列。

返回数据

当本接口调用成功时，返回json格式：
{
"status": 0,
“errmsg”: “SUCCESSFULLY”,
“error”: “”,
"data": {
“job_id”: "本次任务的id，需要保存起来，用于对应后面的结果异步通知"
}
}
说明：调用成功的标识为status字段的值为0，errmsg和error字段此时可以忽略不用管，
job_id需要保存好，在后面结果异步通知中会使用到

当本接口调用不成功时，返回json格式：
{
"status": -310001,
“error”: “InvalidArguments”,
“errmsg”: “参数错误”,
}
说明：调用失败时，status返回非0指，为错误码，error为错误名称，与status错误码对应，errmsg为错误描述。

2、任务结果异步通知

当换脸任务完成，或者发生错误时，需要将执行结果通过上一个接口设置的notify_url参数，通知到调用者，调用者接到通知后，需要返回http response status code为200，且body中为字符串“successfully”，表示调用者已经正确处理通知。如果返回的response的status code不为200，或者body中的字符串不为“successfully”，则表示通知失败；

通知失败的处理：如果通知失败，接口服务会在一定时后尝试重发通知，一共会重发10次通知，直到成功为止，如果重发10次后，仍然无法获取到成功响应，则会停止发送通知，这个任务就可能就会陷入丢失状态；

通知的数据格式如下：

当换脸操作成功时，通知的json格式：
{
“job_id”: “换脸任务提交接口返回的job_id”,
"status": 0,
"data": {
“result_url”: ["https://结果图片url，有效期为24小时，收到通知后，需要尽快下载到本地"]
}
}
说明：调用成功的标识为status字段的值为0，结果图片在data.result_url字段中，job_id为提交任务时，由接口服务返回的任务id；result_url参数返回的是一个数组，里面包含了所有结果图片的url，但当前版本有且仅有一个元素（即只返回一张结果图片）

当换脸操作失败时，通知的json格式：
{
“job_id”: “换脸任务提交接口返回的job_id”,
"status": -22222,
“error”: "",
"data": {}
}
说明：换脸失败时候，status为非0值，error为错误名称，data字段不存在，或者为空

3、任务状态和结果查询接口

https://swapface-api.segapi.com/query

参数形式：JSON，比如：

{

"job_id": "the_job_id_xxxxxx"

}

参数说明

job_id: 待查询的任务的id，由任务提交接口返回

返回数据

当本接口调用成功时，有可能返回三种不同的数据:

任务完成，并生成结果图片时：