1. 接口描述
接口请求域名: aiart.tencentcloudapi.com 。
AI 写真分为上传训练图片、训练写真模型(可选跳过)、生成写真图片3个环节,需要依次调用对应接口。
本接口用于上传人像图片并指定对应的写真模型 ID。上传的图片要求是同一个人,建议上传单人、正脸、脸部区域占比较大、脸部清晰无遮挡、无大角度偏转、无夸张表情的图片。
可选模式:
- 常规训练模式:上传20 - 25张图片用于模型训练,完成训练后可生成写真图片。
- 快速训练模式:仅需上传1张图片用于模型训练,训练速度更快,完成训练后可生成写真图片。
- 免训练模式:仅需上传1张图片,跳过训练环节,直接生成写真图片。
上传写真训练图片默认提供1个并发。
推荐使用 API Explorer
点击调试
API Explorer 提供了在线调用、签名验证、SDK 代码生成和快速检索接口等能力。您可查看每次调用的请求内容和返回结果以及自动生成 SDK 调用示例。
2. 输入参数
以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表见 公共请求参数。
参数名称 | 必选 | 类型 | 描述 |
---|---|---|---|
Action | 是 | String | 公共参数,本接口取值:UploadTrainPortraitImages。 |
Version | 是 | String | 公共参数,本接口取值:2022-12-29。 |
Region | 是 | String | 公共参数,详见产品支持的 地域列表。 |
ModelId | 是 | String | 写真模型 ID。由英文大小写字母、数字及下划线组成。 用于唯一标识一个写真模型,一个写真模型只能用于一个人物的写真图片生成。 |
BaseUrl | 否 | String | 写真模型训练用的基础图像 URL,用于固定写真模型可生成的人物。 图片数量:1张。 图片内容:单人,脸部清晰。 图片限制:单边分辨率小于2000,转成 Base64 字符串后小于 5MB。 |
Urls.N | 否 | Array of String | 写真模型训练用的图像 URL 列表,仅常规训练模式需要上传。 图片数量:19 - 24 张。 图片内容:单人,脸部清晰,和基础图像中的人物为同一人。 图片限制:单边分辨率小于2000,转成 Base64 字符串后小于 5MB。 |
Filter | 否 | Filter | 训练图像质量过滤开关配置。 支持开启或关闭对训练图像分辨率下限、脸部区域大小、脸部遮挡的过滤,默认开启以上过滤。 如果训练图像内包含多人脸或无人脸、和 Base 人像不为同一人也将被过滤,不可关闭该过滤条件。 建议:关闭以上过滤可能导致写真生成效果受损,建议使用单人、正脸、脸部区域占比较大、脸部清晰无遮挡、无大角度偏转、无夸张表情的图像进行训练。 |
TrainMode | 否 | Integer | 训练模式。 默认使用常规训练模式。如果使用快速训练模式和免训练模式,只需要在 BaseUrl 中传入1张图片,Urls.N 中无需传入图片。 0:常规训练模式,上传多张图片用于模型训练,完成训练后可生成写真图片。 1:快速训练模式,仅需上传1张图片用于模型训练,训练速度更快,完成训练后可生成写真图片。 2:免训练模式,仅需上传1张图片,跳过模型训练环节,直接生成写真图片。 |
3. 输出参数
参数名称 | 类型 | 描述 |
---|---|---|
ResultDetails | Array of String | 用于提示对应上传的Urls训练图片是否符合要求,如果未通过需要重新上传。如果基础图像不符合要求会直接通过ErrorCode提示。如果您选择了快速模式,该参数返回为空数组。 示例值:["Success"] |
RequestId | String | 唯一请求 ID,由服务端生成,每次请求都会返回(若请求因其他原因未能抵达服务端,则该次请求不会获得 RequestId)。定位问题时需要提供该次请求的 RequestId。 |
4. 示例
示例1 成功
成功调用上传
输入示例
POST / HTTP/1.1
Host: aiart.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: UploadTrainPortraitImages
<公共请求参数>
{
"ModelId": "test",
"BaseUrl": "https://xxx.com/xxx.jpg",
"Urls": [
"https://xxx.com/yyy.jpg"
]
}
输出示例
{
"Response": {
"RequestId": "948182a1-e669-42f8-a00e-fa9f5b7d287a",
"ResultDetails": [
"SUCCESS"
]
}
}
5. 开发者资源
腾讯云 API 平台
腾讯云 API 平台 是综合 API 文档、错误码、API Explorer 及 SDK 等资源的统一查询平台,方便您从同一入口查询及使用腾讯云提供的所有 API 服务。
API Inspector
用户可通过 API Inspector 查看控制台每一步操作关联的 API 调用情况,并自动生成各语言版本的 API 代码,也可前往 API Explorer 进行在线调试。
SDK
云 API 3.0 提供了配套的开发工具集(SDK),支持多种编程语言,能更方便的调用 API。
- Tencent Cloud SDK 3.0 for Python: GitHub Gitee
- Tencent Cloud SDK 3.0 for Java: GitHub Gitee
- Tencent Cloud SDK 3.0 for PHP: GitHub Gitee
- Tencent Cloud SDK 3.0 for Go: GitHub Gitee
- Tencent Cloud SDK 3.0 for Node.js: GitHub Gitee
- Tencent Cloud SDK 3.0 for .NET: GitHub Gitee
- Tencent Cloud SDK 3.0 for C++: GitHub Gitee
- Tencent Cloud SDK 3.0 for Ruby: GitHub Gitee
命令行工具
6. 错误码
以下仅列出了接口业务逻辑相关的错误码,其他错误码详见 公共错误码。
错误码 | 描述 |
---|---|
FailedOperation.RequestTimeout | 后端服务超时。 |
FailedOperation.ServerError | 服务内部错误。 |
InvalidParameter.InvalidParameter | 参数不合法。 |
InvalidParameterValue.UrlIllegal | URL格式不合法。 |
RequestLimitExceeded.JobNumExceed | 同时处理的任务数过多,请稍后重试。 |