AI Headshot Generation API Integration Guide

This article will introduce an AI Headshot Generation API integration guide. It can create various styles of headshots by inputting portrait photo URLs and templates you like.

¶ Application Process

To use the AI Headshot Generation API, first go to the Ace Data Cloud Console to obtain your API Token and keep it for later use.

If you have not logged in or registered, you will be automatically redirected to the login page to register and log in, and you will automatically return to the current page after completion.

One API Token can call all platform services; there is no need to apply separately for each service. Your first application will receive free credits for a free trial; when credits are insufficient, you can recharge your general balance in the console.

📘 Full documentation: AI Headshot Generation API →

¶ Basic Usage

First, let's understand the basic usage method: simply input the portrait image to be processed and your preferred AI headshot template to obtain the processed result. First, you need to simply pass an image_urls field, which is the array of portrait image links to be processed, as shown in the image:

Then we also need to input our preferred template. This article provides eight popular templates. For specific templates, please refer to the following:

{
   "male_portrait":  男形象照
   "male_portrait2":  男形象照（另一个版本）
   "kindergarten":  幼儿园入园照
   "logo_tshirt": 企业LogoT恤照
   "wedding":  结婚登记照
   "business_photo":  商务风写真
   "bob_suit": 黑西装波波头
   "female_portrait":  女性形象照
}

Afterward, we can also specify the generation speed parameter mode, which is generally divided into two types: slow relax and fast fast. The specific content is as follows:

You can see that we have set Request Headers here, including:

accept: The format of the response result you want to receive. Enter application/json here, namely JSON format.
authorization: The key for calling the API. After applying, you can directly select it from the dropdown.

We also set Request Body, including:

mode: The channel for generating headshots, mainly including fast and relax. When using relax, it is strongly recommended to use the callback_url parameter below.
template: The style of the headshot template.
image_urls: The portrait links of the headshots that need to be uploaded.
callback_url: The URL where results need to be called back.
async: Optional. When set to true, the API immediately returns task_id; there is no need to provide callback_url, and the result can then be obtained by polling through the corresponding task query API.

After selection, you can find that the corresponding code is also generated on the right, as shown in the image:

Click the "Try" button to test. As shown in the image above, we obtain the following result:

{
  "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": "男形象照"
    }
  ]
}

The returned result has multiple fields, introduced as follows:

success: The status of the headshot generation task at this time.
task_id: The ID of the headshot generation task at this time.
data: The result list of the headshot generation task at this time.
- id: The photo ID of the headshot generation task at this time.
- image_url: The image link of the headshot generation task at this time.
- template: The headshot template name of the headshot generation task at this time.

You can see that we have obtained satisfactory headshot information based on the template and portrait image. We only need to obtain the headshot according to the image link address in data from the result.

In addition, if you want to generate corresponding integration code, you can directly copy the generated code. For example, the CURL code is as follows:

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://cdn.zhishuyun.com/2024-11-03-d23744954ca4819503469f04f2268aa0.jpg"]
}'

¶ Asynchronous Callback

Since AI headshot generation takes a relatively long time, approximately 1–2 minutes, if the API does not respond for a long time, the HTTP request will remain connected, resulting in additional system resource consumption. Therefore, this API also provides support for asynchronous callbacks.

The overall process is: when the client initiates a request, it additionally specifies a callback_url field. After the client initiates an API request, the API will immediately return a result containing a task_id field, representing the current task ID. When the task is completed, the result of generating the headshot will be sent in POST JSON format to the callback_url specified by the client, which also includes the task_id field, so that task results can be associated through the ID.

Next, let us understand the specific operation through an example.

First, a Webhook callback is a service that can receive HTTP requests. Developers should replace it with the URL of their own HTTP server. For convenience of demonstration, a public Webhook example website, https://webhook.site/, is used here. Opening this website will provide a Webhook URL, as shown in the image:

Copy this URL, and it can be used as a Webhook. The example here is https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a.

Next, we can set the field callback_url to the Webhook URL above, while entering the portrait image link and template. This article recommends using asynchronous callbacks when the parameter mode is relax. The specific content is shown in the image:

Click Run, and you can find that you will immediately get a result, as follows:

{
  "task_id": "763b1450-8804-434f-acc7-d713be73a28f"
}

Wait a moment, and we can observe the result of generating the song at https://webhook.site/00f38b26-4289-4899-83d6-0cea7308850a, as shown in the figure:

The content is as follows:

{
    "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": "Male Portrait Photo"
        },
        {
            "id": "202411032010132420",
            "image_url": "https://platform.cdn.acedata.cloud/headshots/763b1450-8804-434f-acc7-d713be73a28f.png",
            "template": "Male Portrait Photo"
        }
    ]
}

You can see that there is a task_id field in the result. The other fields are similar to those above, and task association can be implemented through this field.

¶ Error Handling

When calling the API, if an error is encountered, the API will return the corresponding error code and information. For example:

400 token_mismatched: Bad request, possibly due to missing or invalid parameters.
400 api_not_implemented: Bad request, possibly due to missing or invalid parameters.
401 invalid_token: Unauthorized, invalid or missing authorization token.
429 too_many_requests: Too many requests, you have exceeded the rate limit.
500 api_error: Internal server error, something went wrong on the server.

¶ Error Response Example

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

¶ Conclusion

Through this document, you have learned how to use the AI ID Photo Creation API to create ID photos in various styles by entering a portrait photo URL and your preferred template. We hope this document can help you better integrate and use this API. If you have any questions, please feel free to contact our technical support team.