AI generates natural matching backgrounds from a transparent foreground PNG and a prompt or template ID. It works for product photos, marketing posters, and design assets. This endpoint currently supports asynchronous requests.
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 background generation task
/api/tasks/visual/background Body Parameters
image_url string optional Source image URL. If this parameter is present, the other image source parameter must be empty.
image_file file optional Source image file as binary data. If this parameter is present, the other image source parameter must be empty.
For image upload requirements, see Guidelines and Limits #5.
batch_size integer optional Number of images generated in each batch. Currently only 1 or 2 is supported. Default is 2.
prompt string optional Background prompt. Multiple languages are supported, but English works best. Maximum length is 1024 characters.
scene_type integer optional Background template ID. You can fetch the latest template IDs from the scene_type API. Use either prompt or scene_type.
negative_prompt string optional Negative prompt. Multiple languages are supported, but English works best.
Return Parameters
status number HTTP response status code. 200 means success, and non-200 means failure. See Status Code Definitions.
message string Response message. If the task fails, refer to this field or contact support.
data.task_id string Background generation task ID used for polling.
Query background generation result
/api/tasks/visual/background/{task_id} Path Parameters
task_id string required Task ID returned after creating a background generation 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 Response message. If the task fails, refer to this field or contact support.
data.task_id string Background generation 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_1 string URL or Base64 data of the first generated background image.
data.image_2 string URL or Base64 data of the second generated background image.
data.progress number Task processing progress.
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.return_type number Result return method.
data.state_detail string Detailed task status.
data.time_elapsed number Processing time in milliseconds.
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 background generation succeeded. Check data.state for the task result. See Status Code Definitions.
-
The input image must be a transparent PNG with only the foreground, with resolution from 256x256 to 4096x4096.
-
The output image resolution is up to 1024x1024 and keeps the source image aspect ratio.
-
Uploaded images must meet the following format, resolution, and file size limits.
Format Resolution Size png Up to 4096 x 4096 Up to 20MB
# Generate Background API
Generate AI backgrounds for a transparent foreground PNG. Provide either a prompt or a scene_type template, then poll the generated result images asynchronously.
> 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.
## Request modes
This endpoint currently uses asynchronous processing. The create request returns `data.task_id`, and you use that task ID to query the result endpoint.
Result images are retained for up to 1 hour after a successful request.
## Source image and background description
One source image is required, and `image_url` / `image_file` are mutually exclusive:
- `image_url` - source image URL. If this parameter is present, the other image source parameter must be empty.
- `image_file` - source image file uploaded as `multipart/form-data` binary data. If this parameter is present, the other image source parameter must be empty.
A background description is also required. Use either `prompt` or `scene_type`:
- `prompt` - background prompt. Multiple languages are supported, but English works best. Maximum length is 1024 characters.
- `scene_type` - background template ID. You can fetch the latest template IDs from [scene_type API](https://picwish.com/background-sceneid-api-doc).
## Endpoints
| Purpose | Method | Path |
| --- | --- | --- |
| Create a background generation task | POST | /api/tasks/visual/background |
| Query a task result | GET | /api/tasks/visual/background/{task_id} |
## Create a background generation task
`POST /api/tasks/visual/background`
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, image_file must be empty. |
| image_file | file | one of image_url / image_file | Source image file as binary data. If this parameter is present, image_url must be empty. |
| batch_size | integer | optional | Number of images generated in each batch. Currently only 1 or 2 is supported. Default is 2. |
| prompt | string | one of prompt / scene_type | Background prompt. Multiple languages are supported, but English works best. Maximum length is 1024 characters. |
| scene_type | integer | one of prompt / scene_type | Background template ID. Fetch the latest template IDs from the scene_type API. |
| negative_prompt | string | optional | Negative prompt. Multiple languages are supported, but English works best. |
### 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 used for polling. |
### Examples
Asynchronous, image URL and scene_type:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/background' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'scene_type=105' \
-F 'image_url=YOUR_IMAGE_URL'
```
Asynchronous, image file and scene_type:
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/background' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'scene_type=105' \
-F 'image_file=@/path/to/image.png'
```
Example async create response:
```json
{
"status": 200,
"message": "success",
"data": { "task_id": "TASK_ID" }
}
```
## Query background generation result
`GET /api/tasks/visual/background/{task_id}`
Use this to poll for the generated background images.
### Path parameters
| Name | Type | Required | Description |
| --- | --- | --- | --- |
| task_id | string | required | The task ID returned after creating a background generation task. |
### 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 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_1 | string | URL or Base64 data of the first generated background image. |
| data.image_2 | string | URL or Base64 data of the second generated background image. |
| data.progress | number | Task processing progress. |
| 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.return_type | number | Result return method. |
| data.state_detail | string | Detailed task status. |
| data.time_elapsed | number | Processing time in milliseconds. |
### Example
```bash
curl -k 'https://techhk.aoscdn.com/api/tasks/visual/background/{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_1": "https://.../image_1.jpg",
"image_2": "https://.../image_2.jpg",
"completed_at": "1634884056"
}
}
```
## Recommended asynchronous flow
1. POST to /api/tasks/visual/background with one source image and either `prompt` or `scene_type`.
2. Read `data.task_id` from the create response.
3. GET /api/tasks/visual/background/{task_id} every 1 second. The polling duration should not exceed 300 seconds.
4. Inspect `data.state`: 1 = done (read `data.image_1` / `data.image_2`); greater than 1 = keep polling; less than 0 = failed.
5. Download generated images within 1 hour.
## 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 background generation succeeded. Check data.state for the task result. See /states.
- The input image must be a transparent PNG with only the foreground, with resolution from 256x256 to 4096x4096.
- The output image resolution is up to 1024x1024 and keeps the source image aspect ratio.
- A successful call consumes 3 to 10 credits: 1 image = 3 credits, 2 images = 6 credits, 3 images = 8 credits, and 4 images = 10 credits.
- Uploaded images must meet the following format, resolution, and file size limits.
| Format | Resolution | File size |
| --- | --- | --- |
| png | 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. |