Create advanced ID photos with custom dimensions, background colors, face-position constraints, beauty enhancement, outfit changes, watermarked preview, and layout output. It works for ID photo specification, background adjustment, outfit replacement, and printable layouts, with async and sync request modes.
The result image URL is valid for 1 hour. Please download and store it promptly.
Authentication
Every API request must include your API Key in the X-API-KEY request header. Send it with each request exactly as shown in the examples and parameter descriptions.
X-API-KEY: YOUR_API_KEY Create an advanced ID photo task
/api/tasks/visual/external/idphoto Body Parameters
image_file file optional Image file. Supports jpg, jpeg, bmp, png, webp, tiff, bitmap. Either image_file or image_url. Priority: image_file>image_url. Image size <15MB, max resolution 4096x4096
For image upload requirements, see Guidelines and Limits #7.
image_url string optional Image download URL. Supports HTTP and OSS protocols, max 512 characters, download timeout 10s
last_id string optional Reuse last task input. image_id from task return (not task_id), if provided, image input can be omitted
sync integer optional Synchronous/Asynchronous. 1=sync, 0=async
size string optional ID photo size. Default is the original image size. Format: {width}x{height}, for example 300x400. Use a lowercase x as the separator, and each pixel value must be between 100 and 2000.
format string optional Output format. Default is png. png returns a transparent background; jpg returns a white background.
return_type integer optional Result return format. 1 returns an image URL; 2 returns a base64-encoded string. Default is 1.
spec_id integer optional Specification ID. Specification includes size, background color, face size, file size
dpi integer optional Resolution DPI. Min 10, max 1000
px_width integer optional Pixel width. Can pass (px_width, px_height) or (mm_width, mm_height), default (295, 413), <1800 pixels
px_height integer optional Pixel height. Used with px_width, <1800 pixels
mm_width integer optional Millimeter width. Used with mm_height, <180mm
mm_height integer optional Millimeter height. Used with mm_width, <180mm
change_bg integer optional Whether to cutout and change background. 0 or 1
bg_color string optional Background color. Hex format, common colors: white FFFFFF, red FF0000, blue 438EDB, default white
bg_color2 string optional Gradient background color. Hex format, background gradients from top bg_color to bottom bg_color2, default empty
face_width integer optional Face width. Face width (pixels)
min_face_width integer optional Minimum face width. Minimum face width (pixels)
max_face_width integer optional Maximum face width. Maximum face width (pixels)
face_height integer optional Face height. Face height (pixels)
min_face_height integer optional Minimum face height. Minimum face height (pixels)
max_face_height integer optional Maximum face height. Maximum face height (pixels)
head_top integer optional Head top distance. Distance from head top to top edge (pixels)
min_head_top integer optional Minimum head top. Minimum distance from head top (pixels)
max_head_top integer optional Maximum head top. Maximum distance from head top (pixels)
chin_top integer optional Chin top distance. Distance from chin to top edge (pixels)
min_chin_top integer optional Minimum chin top. Minimum distance from chin (pixels)
max_chin_top integer optional Maximum chin top. Maximum distance from chin (pixels)
eyes_top integer optional Eyes top distance. Distance from eyes to top edge (pixels)
min_eyes_top integer optional Minimum eyes top. Minimum distance from eyes (pixels)
max_eyes_top integer optional Maximum eyes top. Maximum distance from eyes (pixels)
auto_bright integer optional Auto brighten. 0 or 1, whether to auto adjust brightness
bright_factor number optional Brightness intensity. [0, 1], brightness coefficient
auto_smooth integer optional Auto smooth skin. 0 or 1, whether to auto smooth skin
smooth_factor number optional Smoothing intensity. [0, 1], smoothing coefficient
auto_thin_face integer optional Auto slim face. 0 or 1, whether to auto slim face
thin_face_factor number optional Face slimming intensity. [0, 1], face slimming coefficient
auto_sharp integer optional Auto sharpen. 0 or 1, whether to auto sharpen
sharp_factor number optional Sharpening intensity. [0, 1], sharpening coefficient
clothes_id string optional Clothing template ID. man_1~man_20, woman_1~woman_20, child_1~child_10, default empty
preview integer optional Preview only. 0 or 1, preview has watermark and does not consume credits
quality integer optional Compression quality. [1, 100], larger value means larger file size
min_file_size integer optional Target minimum size (Bytes). [0, inf], e.g. 10240 means min file size 10KB, only takes effect when quality is empty, default empty
max_file_size integer optional Target maximum size (Bytes). [0, inf], only takes effect when quality is empty, default empty
add_label integer optional Add label. 0 or 1, whether to add label at bottom
label_text string optional Label text. Label content at bottom, default empty
label_height integer optional Label height. Label height at bottom (pixels)
layout integer optional Layout. 0 or 1, whether to return layout
layout_vertical integer optional Layout direction. 0 or 1, horizontal or vertical layout, default horizontal
layout_size string optional Paper size. "5inch" or "6inch", 5-inch or 6-inch layout
layout_bg_color string optional Canvas background color. Hex format, e.g. white FFFFFF, default gray
layout_qr_code_data string optional QR code data. Layout additional QR code data, default empty
layout_qr_code_size integer optional QR code size. Layout additional QR code size in pixels
layout_label_text string optional Canvas label text. Layout additional text, use \n for line breaks, default empty
Return Parameters
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
message string API response message. If the task fails, refer to this field or contact support.
data.task_id string Advanced ID photo task ID used for polling.
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
message string API response message. If the task fails, refer to this field or contact support.
data.task_id string Task ID. If processing fails, contact support with this task_id.
data.image_id string The image_id returned from the task, not the task_id. Use it as last_id to reuse the image in the next request.
data.created_at integer Task creation timestamp.
data.processed_at integer Timestamp when task processing started.
data.completed_at integer Task completion timestamp.
data.image string Download URL or base64 data of the processed ID photo result. URL results are valid for 1 hour.
data.progress number Task progress. 100 means processing is complete.
data.return_type number Result return method.
data.state number Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See Status Code Definitions.
data.state_detail string Detailed task status.
Query advanced ID photo result
/api/tasks/visual/external/idphoto/{task_id} Path Parameters
task_id string required Task ID returned after creating an advanced ID photo task. Use it to query the processing result.
Return Parameters
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
message string API response message. If the task fails, refer to this field or contact support.
data.task_id string Task ID. If processing fails, contact support with this task_id.
data.image_id string The image_id returned from the task, not the task_id. Use it as last_id to reuse the image in the next request.
data.created_at integer Task creation timestamp.
data.processed_at integer Timestamp when task processing started.
data.completed_at integer Task completion timestamp.
data.image string Download URL or base64 data of the processed ID photo result. URL results are valid for 1 hour.
data.progress number Task progress. 100 means processing is complete.
data.return_type number Result return method.
data.state number Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See Status Code Definitions.
data.state_detail string Detailed task status.
Guidelines and Limits
-
The result image URL is generally valid for 1 hour. Please download and store it promptly.
-
HTTP status 200 means the HTTP request succeeded, not that advanced ID photo generation succeeded. Check data.state for the task result. See Status Code Definitions.
-
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing issues.
-
Either image_file or image_url is required, and image_file has higher priority when both are sent. You can also provide last_id to reuse the previous task input and omit the image input.
-
Standard ID photo costs 6 credits per request; outfit change with clothes_id costs 15 credits; enabling any beauty enhancement adds 8 credits; layout=1 adds 5 credits; preview=1 returns a watermarked preview and consumes no credits.
-
Use spec_id for preset ID photo specifications, or pass px_width/px_height or mm_width/mm_height. Pixel values must be less than 1800, millimeter values less than 180, and dpi must be between 10 and 1000.
-
Uploaded images must meet the following format, resolution, and file size limits.
Format Resolution Size jpg, jpeg, bmp, png, webp, tiff, bitmap Up to 4096 x 4096 Up to 15MB
# Advanced ID Photo API
Create advanced ID photos with custom dimensions, background colors, face-position constraints, beauty enhancement, outfit changes, watermarked preview, and layout output. Supports asynchronous and synchronous request modes.
> Note: The result image URL is valid for 1 hour. Please download and store it promptly.
## Base URL
All paths below are relative to the Base URL:
```
https://techhk.aoscdn.com
```
## Authentication
Every request must include your API key in the `X-API-KEY` request header:
```http
X-API-KEY: YOUR_API_KEY
```
Get or manage your API key from [API Key](https://picwish.com/my-account?subRoute=api-key).
Requests without a valid key are rejected.
## Choosing a request mode (sync vs async)
The mode is controlled by the `sync` body parameter on the create request:
- Asynchronous (`sync=0`, recommended): the create request returns immediately with `data.task_id`. Poll the query endpoint with that task ID until processing finishes.
- Synchronous (`sync=1`): the create request waits for processing to finish and returns the result directly in the same response.
In both modes, results are retained for up to 1 hour.
## Source image and reuse
Provide an image source by using `image_file` or `image_url`. The old API parameter table states that `image_file` has higher priority than `image_url` when both are sent. You can also provide `last_id` to reuse the `image_id` from a previous task, in which case the image input can be omitted.
## Endpoints
| Purpose | Method | Path |
| --- | --- | --- |
| Create an advanced ID photo task | POST | /api/tasks/visual/external/idphoto |
| Query a task result (async) | GET | /api/tasks/visual/external/idphoto/{task_id} |
## Create an advanced ID photo task
`POST /api/tasks/visual/external/idphoto`
Content-Type: `multipart/form-data`
### Body parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| image_file | file | optional | Image file. Supports jpg, jpeg, bmp, png, webp, tiff, bitmap. Either image_file or image_url. Priority: image_file>image_url. Image size <15MB, max resolution 4096x4096 |
| image_url | string | optional | Image download URL. Supports HTTP and OSS protocols, max 512 characters, download timeout 10s |
| last_id | string | optional | Reuse last task input. image_id from task return (not task_id), if provided, image input can be omitted |
| sync | integer | optional | Synchronous/Asynchronous. 1=sync, 0=async |
| size | string | optional | ID photo size. Default is the original image size. Format: {width}x{height}, for example 300x400. Use a lowercase x as the separator, and each pixel value must be between 100 and 2000. |
| format | string | optional | Output format. Default is png. png returns a transparent background; jpg returns a white background. |
| return_type | integer | optional | Result return format. 1 returns an image URL; 2 returns a base64-encoded string. Default is 1. |
| spec_id | integer | optional | Specification ID. Specification includes size, background color, face size, file size |
| dpi | integer | optional | Resolution DPI. Min 10, max 1000 |
| px_width | integer | optional | Pixel width. Can pass (px_width, px_height) or (mm_width, mm_height), default (295, 413), <1800 pixels |
| px_height | integer | optional | Pixel height. Used with px_width, <1800 pixels |
| mm_width | integer | optional | Millimeter width. Used with mm_height, <180mm |
| mm_height | integer | optional | Millimeter height. Used with mm_width, <180mm |
| change_bg | integer | optional | Whether to cutout and change background. 0 or 1 |
| bg_color | string | optional | Background color. Hex format, common colors: white FFFFFF, red FF0000, blue 438EDB, default white |
| bg_color2 | string | optional | Gradient background color. Hex format, background gradients from top bg_color to bottom bg_color2, default empty |
| face_width | integer | optional | Face width. Face width (pixels) |
| min_face_width | integer | optional | Minimum face width. Minimum face width (pixels) |
| max_face_width | integer | optional | Maximum face width. Maximum face width (pixels) |
| face_height | integer | optional | Face height. Face height (pixels) |
| min_face_height | integer | optional | Minimum face height. Minimum face height (pixels) |
| max_face_height | integer | optional | Maximum face height. Maximum face height (pixels) |
| head_top | integer | optional | Head top distance. Distance from head top to top edge (pixels) |
| min_head_top | integer | optional | Minimum head top. Minimum distance from head top (pixels) |
| max_head_top | integer | optional | Maximum head top. Maximum distance from head top (pixels) |
| chin_top | integer | optional | Chin top distance. Distance from chin to top edge (pixels) |
| min_chin_top | integer | optional | Minimum chin top. Minimum distance from chin (pixels) |
| max_chin_top | integer | optional | Maximum chin top. Maximum distance from chin (pixels) |
| eyes_top | integer | optional | Eyes top distance. Distance from eyes to top edge (pixels) |
| min_eyes_top | integer | optional | Minimum eyes top. Minimum distance from eyes (pixels) |
| max_eyes_top | integer | optional | Maximum eyes top. Maximum distance from eyes (pixels) |
| auto_bright | integer | optional | Auto brighten. 0 or 1, whether to auto adjust brightness |
| bright_factor | number | optional | Brightness intensity. [0, 1], brightness coefficient |
| auto_smooth | integer | optional | Auto smooth skin. 0 or 1, whether to auto smooth skin |
| smooth_factor | number | optional | Smoothing intensity. [0, 1], smoothing coefficient |
| auto_thin_face | integer | optional | Auto slim face. 0 or 1, whether to auto slim face |
| thin_face_factor | number | optional | Face slimming intensity. [0, 1], face slimming coefficient |
| auto_sharp | integer | optional | Auto sharpen. 0 or 1, whether to auto sharpen |
| sharp_factor | number | optional | Sharpening intensity. [0, 1], sharpening coefficient |
| clothes_id | string | optional | Clothing template ID. man_1~man_20, woman_1~woman_20, child_1~child_10, default empty |
| preview | integer | optional | Preview only. 0 or 1, preview has watermark and does not consume credits |
| quality | integer | optional | Compression quality. [1, 100], larger value means larger file size |
| min_file_size | integer | optional | Target minimum size (Bytes). [0, inf], e.g. 10240 means min file size 10KB, only takes effect when quality is empty, default empty |
| max_file_size | integer | optional | Target maximum size (Bytes). [0, inf], only takes effect when quality is empty, default empty |
| add_label | integer | optional | Add label. 0 or 1, whether to add label at bottom |
| label_text | string | optional | Label text. Label content at bottom, default empty |
| label_height | integer | optional | Label height. Label height at bottom (pixels) |
| layout | integer | optional | Layout. 0 or 1, whether to return layout |
| layout_vertical | integer | optional | Layout direction. 0 or 1, horizontal or vertical layout, default horizontal |
| layout_size | string | optional | Paper size. "5inch" or "6inch", 5-inch or 6-inch layout |
| layout_bg_color | string | optional | Canvas background color. Hex format, e.g. white FFFFFF, default gray |
| layout_qr_code_data | string | optional | QR code data. Layout additional QR code data, default empty |
| layout_qr_code_size | integer | optional | QR code size. Layout additional QR code size in pixels |
| layout_label_text | string | optional | Canvas label text. Layout additional text, use \n for line breaks, default empty |
### Return parameters - asynchronous (sync=0)
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means the request succeeded, and non-200 means failure. See /states. |
| message | string | Response message. If the task fails, refer to this field or contact support. |
| data.task_id | string | Task ID. Use it to query the result later. |
### Return parameters - synchronous (sync=1)
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means the request succeeded, and non-200 means failure. See /states. |
| message | string | Response message. If the task fails, refer to this field or contact support. |
| data.task_id | string | Task ID. If processing fails, contact support with this task_id. |
| data.image_id | string | The image_id returned from the task, not the task_id. Use it as last_id to reuse the image in the next request. |
| data.created_at | integer | Task creation timestamp. |
| data.processed_at | integer | Timestamp when task processing started. |
| data.completed_at | integer | Task completion timestamp. |
| data.image | string | Download URL or base64 data of the processed ID photo result. URL results are valid for 1 hour. |
| data.progress | number | Task progress. 100 means processing is complete. |
| data.return_type | number | Result return method. |
| data.state | number | Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See /states. |
| data.state_detail | string | Detailed task status. |
### Examples
Asynchronous, image URL:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/idphoto' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_url=YOUR_IMAGE_URL'
```
Asynchronous, image file upload:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/idphoto' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'image_file=@/path/to/image.jpg'
```
Synchronous, image URL:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/idphoto' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'image_url=YOUR_IMAGE_URL'
```
Example async create response:
```json
{
"status": 200,
"message": "success",
"data": { "task_id": "TASK_ID" }
}
```
## Query advanced ID photo result
`GET /api/tasks/visual/external/idphoto/{task_id}`
Use this in asynchronous mode to poll for the result.
### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| task_id | string | required | The task ID returned by the create request. |
### Return parameters
| Name | Type | Description |
| --- | --- | --- |
| status | number | HTTP response status code. 200 means the request succeeded, and non-200 means failure. See /states. |
| message | string | Response message. If the task fails, refer to this field or contact support. |
| data.task_id | string | Task ID. If processing fails, contact support with this task_id. |
| data.image_id | string | The image_id returned from the task, not the task_id. Use it as last_id to reuse the image in the next request. |
| data.created_at | integer | Task creation timestamp. |
| data.processed_at | integer | Timestamp when task processing started. |
| data.completed_at | integer | Task completion timestamp. |
| data.image | string | Download URL or base64 data of the processed ID photo result. URL results are valid for 1 hour. |
| data.progress | number | Task progress. 100 means processing is complete. |
| data.return_type | number | Result return method. |
| data.state | number | Task status. 1 means succeeded, greater than 1 means processing, and less than 0 means failed. -7 means invalid image file. See /states. |
| data.state_detail | string | Detailed task status. |
### Example
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/external/idphoto/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```
Example completed response:
```json
{
"status": 200,
"message": "success",
"data": {
"task_id": "TASK_ID",
"image_id": "IMAGE_ID",
"state": 1,
"progress": 100,
"image": "https://.../id-photo.jpg",
"completed_at": "1700000000"
}
}
```
## Recommended asynchronous flow
1. POST to /api/tasks/visual/external/idphoto with `sync=0` and either an image source or `last_id`. Read `data.task_id`.
2. GET /api/tasks/visual/external/idphoto/{task_id} every 1 second. Polling should not exceed 5 minutes.
3. Inspect `data.state`: 1 = done (read `data.image` and `data.image_id`); > 1 = keep polling; < 0 = failed.
4. Download `data.image` within 1 hour. Store `data.image_id` if you want to reuse the same input image later through `last_id`.
## Guidelines and Limits
- The result image URL is valid for **1 hour**. Please download and store it promptly.
- HTTP status 200 means the HTTP request succeeded, not that advanced ID photo generation succeeded. Check data.state for the task result. See /states.
- When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing issues.
- Either image_file or image_url is required, and image_file has higher priority when both are sent. You can also provide last_id to reuse the previous task input and omit the image input.
- Standard ID photo costs 6 credits per request; outfit change with clothes_id costs 15 credits; enabling any beauty enhancement adds 8 credits; layout=1 adds 5 credits; preview=1 returns a watermarked preview and consumes no credits.
- Use spec_id for preset ID photo specifications, or pass px_width/px_height or mm_width/mm_height. Pixel values must be less than 1800, millimeter values less than 180, and dpi must be between 10 and 1000.
- Uploaded images must meet the following format, resolution, and file size limits.
| Format | Resolution | File size |
| --- | --- | --- |
| jpg, jpeg, bmp, png, webp, tiff, bitmap | Up to 4096 x 4096 | Up to 15MB |
## Status codes
Determine success by combining the HTTP response status code (`status`) with the task status code (`data.state`).
### HTTP response status codes
| Code | Meaning |
| --- | --- |
| 200 | The request is successful. |
| 400 | Wrong parameter passed by the client. Check whether a parameter is missing or has an incorrect value. |
| 401 | Unauthorized API key. Check that X-API-KEY is correct and the service is enabled. |
| 404 | The requested URL or resource does not exist. Check that the URL or task_id is correct. |
| 413 | The uploaded file exceeds the allowed size. Refer to the supported image size. |
| 429 | Request frequency exceeds the QPS limit (default QPS is 2). Slow down or contact us to raise your QPS. |
| 500 | Server-side exception. Please contact support. |
### Task status codes (data.state)
1 = succeeded; greater than 1 = still processing; less than 0 = failed.
| Code | Meaning |
| --- | --- |
| -17 | Processing failed because the prompt is invalid. |
| -16 | Processing failed because a third-party review detected prohibited content. |
| -15 | Processing failed due to insufficient resources. |
| -14 | Processing failed because the input image content does not meet the requirements. |
| -13 | Processing failed because the task was canceled due to an exception. |
| -11 | Processing failed because the result is empty. |
| -10 | Processing failed because internal review detected prohibited content. |
| -9 | Processing failed because the internal program failed during loop processing. |
| -8 | Processing timed out. The maximum processing time is 180 seconds. |
| -7 | Invalid image file (e.g. corrupted image or incorrect format). |
| -5 | The image_url image exceeds the size limit (30MB). |
| -3 | The server failed to download your file. Check that the source image URL is available. |
| -2 | Processing completed, but uploading the result to OSS failed. |
| -1 | Processing failed. |
| 0 | Queued. The task is waiting in the queue. |
| 1 | Completed. Processing succeeded. |
| 2 | Preparing. |
| 3 | Waiting. |
| 4 | Processing in progress. |
| 5 | Internally publishing the result. |
| 6 | Processing. Internal loop processing is in progress. |