Photo Enhancement API

Try on PicWish

AI improves blurry or low-quality images by enhancing detail, clarity, and resolution. It works for product photos, portraits, and design assets, 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 a photo enhancement task

POST /api/tasks/visual/scale

Body Parameters

image_url string optional

Source image URL. If this parameter is present, the other image source parameters must be empty.

one required

image_file file optional

Source image file as binary data. If this parameter is present, the other image source parameters must be empty.

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

sync integer optional

Whether to return the result image in real time. Results are kept for up to 1 hour.

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

type string optional

Enhancement type. Default is clean.

clean: General image enhancement, best for non-portrait images such as products;
face: Face enhancement, best for portraits. Up to 10 portraits can be enhanced in one image.

scale_factor integer optional

Scale factor. By default, images are scaled automatically: (10,512] upscales to 4x, (512,1024] upscales to 2x, and (1024,4096] keeps the original resolution.

1: Keep the original resolution;
2: Upscale to 2x;
4: Upscale to 4x.

return_type integer optional

Result return type. Default is 1.

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

format string optional

Output format for the processed image. Default is empty.

empty: Return PNG when the result contains an alpha channel; otherwise return JPG;
png: Always return PNG with alpha-channel support;
jpg: Always return JPG. Transparent areas are filled with a white background.

Return Parameters

status number

HTTP response status code. See Status Code Definitions.

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

message string

API response message. Usually success for a successful request.

data.task_id string

Async photo 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. Usually success for a successful request.

data.task_id string

Photo enhancement 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. The URL is 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 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/scale/{task_id}

Path Parameters

task_id string required

Photo 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. Usually success for a successful request.

data.task_id string

Photo enhancement 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. The URL is 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.
A successful call consumes 2 credits when the long edge is <= 2048px, and 3 credits when 2048px < long edge <= 4096px.
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/scale/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.
  }
}