AI证件照生成API：快速创建证件照
AI证件照生成API：快速创建证件照
本文将详细介绍一种用于AI证件照制作的API接口，通过输入人像照片的URL和您选择的模板，以生成多种风格的证件照。
以下是AI证件照制作API的对接说明。
申请步骤
要使用该API，首先需要前往 AI证件照制作 API 的页面，申请相应的服务。进入后，请点击“Acquire”按钮，如图所示：
若您尚未注册或登录，页面会自动跳转至注册/登录界面。成功登录后，系统将返回到之前的页面。
首次申请将获得免费的使用额度，可以无需付费地试用该API。
基本用法
首先，了解基本的使用方法，即输入待处理的人像照片以及喜欢的AI证件照模板即可获取处理结果。首先需传递一个 image_urls 字段，其中为待处理人像照片链接数组，如图所示：
之后，我们还需选择自己偏好的模板。本文提供八种受欢迎的模板，具体如下：
{
"male_portrait": "男形象照",
"male_portrait2": "男形象照（版本二）",
"kindergarten": "幼儿园入园照",
"logo_tshirt": "企业LogoT恤照",
"wedding": "结婚登记照",
"business_photo": "商务风写真",
"bob_suit": "黑西装波波头",
"female_portrait": "女性形象照"
}
此外，我们可以指定生成速度参数 mode，通常有两种选择：慢速 relax 和快速 fast，具体内容如下：
如图所示，我们设置了请求头，包括：
accept：指定想接收的响应格式，这里为application/json，即JSON格式。authorization：调用API的密钥，申请后可直接下拉选择。
另外设置了请求体，包括：
mode：生成证件照的速度模式，主要有fast（快速）和relax（慢速）两种。对于relax模式，建议使用以下参数callback_url。template：证件照模板样式。image_urls：需上传的证件照人像链接。callback_url：用于返回结果的URL。
选择好参数后，可以在右侧看到生成的相应代码，如图所示：
点击“Try”按钮进行测试，如上图所示，我们获得了如下结果：
{
"success": true,
"task_id": "ae1e4948-dba1-4a6f-87af-67961b647428",
"data": [
{
"id": "202411031951124776",
"image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
"template": "男形象照"
},
{
"id": "202411031951128490",
"image_url": "https://platform.cdn.acedata.cloud/headshots/ae1e4948-dba1-4a6f-87af-67961b647428.png",
"template": "男形象照"
}
]
}
返回结果的字段说明如下：
success：表示证件照生成任务的状态。task_id：当前证件照生成任务的唯一标识。data：生成的证件照结果列表。id：生成照片的唯一标识。image_url：生成的图像链接。template：使用的证件照模板名称。
上述结果展示了根据模板与人像图像生成的满意证件照信息。只需使用结果中的 image_url 获取证件照即可。
如需生成相应的对接代码，可直接复制生成的代码，例如CURL代码如下：
curl -X POST 'https://api.acedata.cloud/headshots/generate' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"mode": "fast",
"template": "male_portrait",
"image_urls": ["https://i-blog.csdnimg.cn/img_convert/566e5985cbd2f8b32e0c85a76cee9f42.jpeg"]
}'
异步回调
由于AI证件照生成的耗时相对较长，约1-2分钟，若API响应时间过长，HTTP请求会保持连接状态，消耗系统资源。因此，API还提供异步回调功能。
整体流程为：客户端在发起请求时额外指定一个 callback_url 字段。发起API请求后，API会立即返回包含 task_id 的结果，表示当前任务的唯一标识。当任务完成后，生成的证件照结果将以POST JSON格式发送到客户端指定的 callback_url，其中也包括 task_id 字段，以此实现任务结果的关联。
以下示例展示具体操作流程。
首先，Webhook回调是一个可接收HTTP请求的服务，开发者应替换为自建HTTP服务器的URL。为便于演示，此处使用公开的Webhook样例网站 https://webhook.site/，打开后可获取一个Webhook URL，如图所示：
将URL复制下来，即可作为Webhook使用，此处示例为 https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a。
接下来，设置callback_url字段为上述Webhook URL，并输入人像图片链接和模板。建议在 mode 参数为 relax 时使用异步回调，具体内容如下图所示：
点击运行，立即能获得如下结果：
{
"task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}
等待片刻后，在 https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a 上可见生成的结果，如图所示：
具体内容如下：
{
"success": true,
"task_id": "763b1450-8804-434f-acc7-d713be73a28f",
"data": [
{
"id": "202411032010131366",
"image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
"template": "男形象照"
},
{
"id": "202411032010132420",
"image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
"template": "男形象照"
}
]
}
从结果中可以看到 task_id 字段，其他字段与前文类似，通过此字段即可实现任务的关联。
错误处理
在调用API时，如果遇到错误，API会返回相应的错误代码和信息。例如：
400 token_mismatched：请求错误，可能因为缺少或无效的参数。400 api_not_implemented：请求错误，可能因为缺少或无效的参数。401 invalid_token：未经授权，无效或缺失的授权令牌。429 too_many_requests：请求过多，已超过速率限制。500 api_error：服务器内部错误，服务器上出现问题。
错误响应示例
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
结论
通过本说明文档，您已了解如何使用AI证件照制作API，通过输入人像照片的URL和选定的模板，来创建多样风格的证件照。希望此文档能够协助您更好地对接和使用该API。