ID Photo API

# ID Photo API

Create ID photos by resizing the source image and outputting a transparent PNG or a JPG with a white or custom solid background. It works for ID photo cropping, background adjustment, and size normalization, with 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.

## Providing the source image (image_url vs image_file)

Exactly one image source is required, and the two options are mutually exclusive:

- `image_url` - source image URL. If this parameter is present, the other image source parameters must be empty.
- `image_file` - source image file uploaded as `multipart/form-data` binary data. If this parameter is present, the other image source parameters must be empty.

## Endpoints

| Purpose | Method | Path |
| --- | --- | --- |
| Create an ID photo task | POST | /api/tasks/visual/idphoto |
| Query a task result (async) | GET | /api/tasks/visual/idphoto/{task_id} |

## Create an ID photo task

`POST /api/tasks/visual/idphoto`

Content-Type: `multipart/form-data`

### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| image_url | string | one of image_url / image_file | Source image URL. If this parameter is present, the other image source parameters must be empty. |
| image_file | file | one of image_url / image_file | Source image file as binary data. If this parameter is present, the other image source parameters must be empty. |
| sync | integer | optional | 0 = asynchronous; 1 = synchronous. Results are kept up to 1 hour. |
| size | string | optional | Output ID photo size. Default is the original 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. |
| bg_color | string | optional | Solid background color, only valid when format=jpg. If omitted, JPG uses a white background. Format: RRGGBB, for example FFFFFF. |
| return_type | integer | optional | Result return format. 1 = image URL; 2 = base64-encoded string. Default is 1. |

### 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 | API response message. Usually success for a successful request. |
| 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 | API response message. Usually success for a successful request. |
| data.task_id | string | Task ID. If the task fails, contact support with this task_id. |
| data.created_at | string | Timestamp of task creation. |
| data.processed_at | string | Timestamp when the task started to be processed. |
| data.completed_at | string | Timestamp of task completion. |
| data.image | string | The result image URL or base64 data. URL results are valid for 1 hour. |
| data.progress | number | Task processing progress. 100 means processing is complete. |
| 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. |

### Examples

Asynchronous, image URL:

```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/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/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/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 ID photo result

`GET /api/tasks/visual/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 | API response message. Usually success for a successful request. |
| data.task_id | string | Task ID. If the task fails, contact support with this task_id. |
| data.created_at | string | Timestamp of task creation. |
| data.processed_at | string | Timestamp when the task started to be processed. |
| data.completed_at | string | Timestamp of task completion. |
| data.image | string | The result image URL or base64 data. URL results are valid for 1 hour. |
| data.progress | number | Task processing progress. 100 means processing is complete. |
| 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. |

### Example

```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/idphoto/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```

Example completed response:

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "TASK_ID",
    "state": 1,
    "progress": 100,
    "image": "https://.../id-photo.jpg",
    "completed_at": "1700000000"
  }
}
```

## Recommended asynchronous flow

1. POST to /api/tasks/visual/idphoto with `sync=0` and exactly one image source (`image_url` or `image_file`). Read `data.task_id`.
2. GET /api/tasks/visual/idphoto/{task_id} every 1-2 seconds.
3. Inspect `data.state`: 1 = done (read `data.image`); > 1 = keep polling; < 0 = failed.
4. Download `data.image` within 1 hour.

## Guidelines and Limits

- The result image URL is valid for **1 hour**. Please download and store it promptly.

- A successful call consumes 1 credit.

- HTTP status 200 means the HTTP request succeeded, not that 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.

- The ID photo size parameter uses the {width}x{height} format, and each pixel value must be between 100 and 2000.


- Uploaded images must meet the following format, resolution, and file size limits.

| Format | Resolution | File size |
| --- | --- | --- |
| jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw | Up to 4096 x 4096 | Up to 20MB |

## 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. |