AI身份证照片生成API集成指南

本文将介绍如何集成AI身份证照片生成API，该API可以通过输入人像照片的URL和选择的模板来创建各种风格的身份证照片。无论是用于个人证件、企业名片还是其他需求，这项技术都能提供极大的便利。

环境准备

在开始之前，请确保您已具备以下条件： - 注册并登录 Ace Data Cloud 账户。 - 获取API访问权限。

申请使用API

要使用此API，您首先需要在 AI身份证照片生成API 页面申请相应的服务。进入页面后，点击"获取"按钮，如下图所示：

如果您尚未登录或注册，将会自动跳转到登录页面，完成后会返回当前页面。首次申请将获得免费的使用配额。

基本使用方法

首先，了解基本的使用方式，即输入需要处理的人像图像和选择的AI身份证照片模板以获取处理结果。您需要传递一个 image_urls 字段，该字段是需要处理的人像图像链接的数组，如下图所示：

接下来，您需要输入自己选择的模板。以下是八种常见的模板供您参考：

json 复制代码

{
   "male_portrait":  "男性人像照片",
   "male_portrait2":  "男性人像照片（另一个版本）",
   "kindergarten":  "幼儿园入园照片",
   "logo_tshirt": "公司标志T恤照片",
   "wedding":  "结婚登记照片",
   "business_photo":  "商务风格照片",
   "bob_suit": "黑色西装搭配波波头",
   "female_portrait":  "女性人像照片"
}

然后，您可以指定生成速度参数 mode，通常分为两种类型：慢速 relax 和快速 fast。具体内容如下图所示：

在设置请求头时，包括：

accept: 需要接收的响应结果格式，这里填写为 application/json，表示JSON格式。
authorization: 调用API的密钥，申请后可以直接选择。

同时，设置请求体，包括：

mode: 生成身份证照片的通道，主要有快速和放松两种。当使用放松模式时，强烈建议使用下面的 callback_url 参数。
template: 身份证照片的模板样式。
image_urls: 需要上传的身份证照片人像链接。
callback_url: 接收回调结果的URL。

在选择完毕后，您会发现右侧生成了相应的代码，如下图所示：

点击"尝试"按钮进行测试，得到如下结果：

json 复制代码

{
  "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: 当前身份证照片生成任务的ID。
data: 当前身份证照片生成任务的结果列表。
id: 当前身份证照片生成任务的照片ID。
image_url: 当前身份证照片生成任务的图像链接。
template: 当前身份证照片生成任务使用的模板名称。

您可以通过 data 结果中的图像链接提取满意的身份证照片信息。

如果您想生成相应的集成代码，可以直接复制生成的代码，例如，CURL代码如下：

shell 复制代码

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/direct/a3166f1d2ee84c3faa34d14c10b2a5a1.jpg"]
}'

异步回调

由于AI身份证照片的生成时间相对较长，约1-2分钟，如果API长时间没有响应，HTTP请求将保持连接，导致额外的系统资源消耗。因此，此API还支持异步回调。

整体流程为：当客户端发起请求时，指定额外的 callback_url 字段。客户端发起API请求后，API会立即返回一个包含 task_id 字段信息的结果，表示当前任务ID。当任务完成后，生成的身份证照片结果将以POST JSON的形式发送到客户端指定的 callback_url，同时也包含 task_id 字段，便于通过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 观察到生成的结果，如下图所示：

内容如下：

json 复制代码

{
    "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: 内部服务器错误，服务器出现问题。

错误响应示例

```