Image Expansion API

Try on PicWish

AI expands an image beyond its original canvas, generating natural background and scene details for the extended area. It supports canvas mode and four-side mode for product photos, portraits, and design materials, 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 image expansion task

POST /api/tasks/visual/advanced-image-expand

Body Parameters

image_url string optional

Source image download URL. One of image_url or image_file is required. Supports HTTP and OSS URLs, up to 512 characters, with a 10-second download timeout. If both image_file and image_url are provided, image_file takes priority.

one required

image_file file optional

Source image file as binary data. One of image_file or image_url is required. Only JPG, JPEG, and PNG are supported. The file must be up to 5MB and between 64x64 and 4096x4096. It takes priority over image_url.

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

mask_url string optional

Mask image URL. Optional. If provided, canvas mode is used. Supports HTTP and OSS URLs, up to 512 characters, with a 10-second download timeout. If both mask_file and mask_url are provided, mask_file takes priority.

one optional

mask_file file optional

Mask image file as binary data. Optional. If provided, canvas mode is used. It takes priority over mask_url.

The mask must match the image dimensions; see Guidelines and Limits #5.

return_type integer optional

Result return type. 1 returns the image download URL (default); 2 returns the image as a Base64 string.

top number optional

Top expansion ratio. Default is 0.1. Range: (0, 1].

bottom number optional

Bottom expansion ratio. Default is 0.1. Range: (0, 1].

left number optional

Left expansion ratio. Default is 0.1. Range: (0, 1].

right number optional

Right expansion ratio. Default is 0.1. Range: (0, 1].

strength number optional

Source image similarity. Recommended range: [0.1, 1.0]. Smaller values stay closer to the source image, while larger values follow the text prompt more strongly. When set to 0, the result remains almost identical to the source image.

scale number optional

Prompt guidance scale. Default is 7.0. Range: [1, 20].

steps integer optional

Sampling steps. Default is 30. Higher values may produce finer results, but they also increase processing time significantly.

seed integer optional

Random seed. Default is -1. -1 means a random seed is used. If the same positive seed and all other parameters are identical, the generated result is highly likely to be the same.

prompt string optional

Prompt used to guide image generation. Chinese and English are both supported. Keep it concise and accurate, ideally within 100 Chinese characters or English words. This field is subject to content review.

sync integer optional

Whether to return the result synchronously. Use 0 to return task_id first and poll the query endpoint later; use 1 to return the result directly. We recommend keeping the total polling duration within 180 seconds and polling once every 1 second.

Return Parameters

status number

HTTP response status code. 200 means the HTTP request succeeded, not necessarily that image expansion succeeded. See Status Code Definitions.

message string

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

data.task_id string

Async image expansion task ID returned after the task is created. Use it to query the result later.

status number

HTTP response status code. 200 means the HTTP request succeeded, not necessarily that image expansion succeeded. See Status Code Definitions.

message string

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

data.task_id string

Image expansion 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.download_time number

Image download time.

data.image string

Result image URL or Base64 data. The URL is valid for 1 hour.

data.image1 string

Alternative result image field used in some responses.

data.image_1 string

First result image field returned in some responses.

data.image_2 string

Second result image field returned in some responses.

data.image_3 string

Third result image field returned in some responses.

data.image_4 string

Fourth result image field returned in some responses.

data.return_type number

Result return type.

data.progress number

Task progress percentage, ranging from 0 to 100.

data.state number

Task status code. 1 means completed, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

data.state_detail string

Detailed task state.

data.time_elapsed string

Total processing time.

Query image expansion result

GET /api/tasks/visual/advanced-image-expand/{task_id}

Path Parameters

task_id string required

Image expansion task ID returned after creating an async task. Use it to query the processing result.

Return Parameters

status number

HTTP response status code. 200 means the HTTP request succeeded, not necessarily that image expansion succeeded. See Status Code Definitions.

message string

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

data.task_id string

Image expansion 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.download_time number

Image download time.

data.image string

Result image URL or Base64 data. The URL is valid for 1 hour.

data.image1 string

Alternative result image field used in some responses.

data.image_1 string

First result image field returned in some async responses.

data.image_2 string

Second result image field returned in some async responses.

data.image_3 string

Third result image field returned in some async responses.

data.image_4 string

Fourth result image field returned in some async responses.

data.return_type number

Result return type.

data.progress number

Task progress percentage, ranging from 0 to 100.

data.state number

Task status code. 1 means completed, greater than 1 means processing, and less than 0 means failed. See Status Code Definitions.

data.state_detail string

Detailed task state.

data.time_elapsed string

Total processing time.

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 that image expansion succeeded. Determine the task result with data.state. See Status Code Definitions.
When passing URLs as parameters, follow URL encoding standards to prevent parameter parsing confusion.
If a mask parameter is provided, canvas mode is used. Otherwise, use top, bottom, left, and right to control four-side expansion ratios.
The mask image must have the same dimensions as the image.
In canvas mode, the image inside the red box is the image input, including the original image and the area to be expanded.

Canvas mode diagram
Uploaded images must meet the following format, resolution, and file size limits.

Format Resolution Size

jpg, jpeg, png Min 64x64, max 4096 x 4096 Up to 5MB

Format	Resolution	Size
jpg, jpeg, png	Min 64x64, max 4096 x 4096	Up to 5MB

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.
    "download_time": 1200, // Only present in async polling results.
    "image": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/advanced-image-expand/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "image1": "https://wxtechhk.oss-hongkong.aliyuncs.com/tasks/output/advanced-image-expand/93a5e47b-a9c1-47ac-9b5e-22cb89f7d358-image.jpg", // Only present in async polling results.
    "return_type": 1, // Only present in async polling results.
    "progress": 100, // Only present in async polling results.
    "state": 1, // Only present in async polling results.
    "state_detail": "success", // Only present in async polling results.
    "time_elapsed": "4.23s" // Only present in async polling results.
  }
}