Photo Cropping and Enhancement API

Try on PicWish

AI intelligently detects image edges, crops the subject or document area, corrects orientation, and can enhance text or remove product backgrounds according to the selected enhancement type. It supports 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 a photo cropping and enhancement task

POST /api/tasks/visual/correction

Body Parameters

image_url string optional

Source image URL. Use either image_url or image_file. If this parameter is present, the other image source parameter must be empty.

one required

image_file file optional

Source image file as binary data. Use either image_file or image_url. If this parameter is present, the other image source parameter must be empty.

For image upload requirements, see Guidelines and Limits #4.

sync integer optional

Whether to wait for and return the result immediately. Results are kept for up to 1 hour.

0: Return a task_id asynchronously for later polling;
1: Wait for and return the result synchronously.

type integer optional

Enhancement type. Default: 1.

0: Crop and correct orientation for text or document images;
1: Enhance text or document images;
2: Crop, correct orientation, and enhance text or document images;
3: Crop and correct orientation for product images;
4: Crop, correct orientation, and remove the background for product images.

return_type integer optional

Result return format.

1: Return an image URL;
2: Return a Base64-encoded image;
3: Return binary image data, available only for synchronous requests.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

200: Request succeeded;
Non-200: Request failed.

message string

API response message. If the task fails, refer to this message or contact support with it.

data.task_id string

Async photo cropping and enhancement task ID returned after the task is created. Use it to query the result later.

status number

HTTP response status code. See Status Code Definitions.

200: Request succeeded;
Non-200: Request failed.

message string

API response message. If the task fails, refer to this message or contact support with it.

data.task_id string

Photo cropping and enhancement task ID.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.image string

Result image URL or base64 data, depending on return_type. URL results are valid for 1 hour.

data.progress number

Task progress.

100: Processing is complete.

data.state number

Task status code. See Status Code Definitions.

1: Succeeded;
> 1: Processing;
< 0: Failed.

Query photo cropping and enhancement result

For asynchronous requests, poll the result once every 1 second. The maximum polling duration for this API is 60 seconds; if the total polling time exceeds this without a result, treat it as a timeout failure.

GET /api/tasks/visual/correction/{task_id}

Path Parameters

task_id string required

Photo cropping and enhancement task ID returned after creating an async task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

200: Request succeeded;
Non-200: Request failed.

message string

API response message. If the task fails, refer to this message or contact support with it.

data.task_id string

Photo cropping and enhancement task ID. If the task fails, contact support with this task_id.

data.created_at string

Task creation time as a Unix timestamp string.

data.processed_at string

Task processing start time as a Unix timestamp string.

data.completed_at string

Task completion time as a Unix timestamp string.

data.image string

Result image URL or base64 data, depending on return_type. URL results are valid for 1 hour.

data.progress number

Task progress.

100: Processing is complete.

data.state number

Task status code. See Status Code Definitions.

1: Succeeded;
> 1: Processing;
< 0: Failed.

Guidelines and Limits

The result image URL is valid for 1 hour. Please download and store it promptly.
HTTP status 200 indicates that the HTTP request succeeded, not necessarily that the image task succeeded. See Status Code Definitions for details.
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing confusion.
Uploaded images must meet the following format, resolution, and file size limits.

Format Resolution Size

jpg, jpeg, bmp, png, webp, tiff, tif, bitmap, raw, rgb, jfif, lzw Up to 4096 x 4096 Up to 20MB

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

Response

{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "xxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "created_at": "1634884056", // Only present in async polling results.
    "processed_at": "1634884056", // Only present in async polling results.
    "completed_at": "1634884056", // Only present in async polling results.
    "image": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/segmentation/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1 // Only present in async polling results.
  }
}