AI证件照生成API：快速创建证件照

最新推荐文章于 2025-09-15 00:08:53 发布

原创最新推荐文章于 2025-09-15 00:08:53 发布 · 1w 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#人工智能 #python #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。