# Image Background Generation Submit API Reference

### Image Background Generation Submit API 

<mark style="color:green;">`POST`</mark> `/ai/image/background/generation/scenario`

{% tabs %}
{% tab title="Description" %}
Based on the provided scene ID, this API automatically extracts the main object from the input image and generate high-quality images in various scene styles. Background image generation is performed asynchronously. This API is used to submit the generation task; to obtain the results, please call the result query API.
{% endtab %}
{% endtabs %}

### Request Parameters

<table><thead><tr><th width="193">Parameter</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>requestParams</code></td><td>Object[]</td><td>Yes</td><td>Request params.</td></tr><tr><td><code>imageFileUrl</code></td><td>String</td><td>No</td><td><p>The product image URL.</p><p>Both imageUrl and imageBase64 cannot be empty at the same time. If both imageUrl and imageBase64 are present, Base64 is preferred.</p><p>Input image size larger than 512×512 pixels, but smaller than 3000×3000 pixels.</p></td></tr><tr><td><code>imgBase64</code></td><td>String</td><td>No</td><td><p>The Base64 encoding of the product image.</p><p>Both imageUrl and imageBase64 cannot be empty at the same time. If both imageUrl and imageBase64 are present, Base64 is preferred.</p><p>Input image size larger than 512×512 pixels, but smaller than 3000×3000 pixels.</p></td></tr><tr><td><code>modelNum</code></td><td>String</td><td>Yes</td><td>The scene ID that needs to be generated. To query the scene ID, please use the "AI Scene Recommendation &#x26; Query" interface.</td></tr><tr><td><code>needLayout</code></td><td>Boolean</td><td>No</td><td><p>Whether to rearrange the layout of the product. The range of values:</p><p>true: Rearrange the position of the product.</p><p>false: Use the product position from the input image, and do not rearrange.</p><p><code>Sample: true</code></p></td></tr><tr><td><code>productTitle</code></td><td>String</td><td>No</td><td><p>Product title. It is not necessary to input if automatic layout is not required.</p><p>Only product titles in Chinese or English are supported.</p></td></tr><tr><td><code>width</code></td><td>Number</td><td>Yes</td><td><p>The desired width of the generated image. Unit: pixels.</p><p>Currently, only 1:1 (width 800 * height 800) and 3:4 (width 750 * height 1000) sizes are supported for generation.</p><p><code>Sample: 800</code></p></td></tr><tr><td><code>height</code></td><td>Number</td><td>Yes</td><td><p>The desired height of the generated image. Unit: pixels. </p><p>Currently, only sizes of 1:1 (width 800 * height 800) and 3:4 (width 750 * height 1000) are supported for generation.</p><p><code>Sample: 800</code></p></td></tr><tr><td><code>imageNum</code></td><td>Number</td><td>Yes</td><td><p>The desired number of images to be generated. A single task can generate a minimum of 2 images and a maximum of 10 images. If not set, the default is to generate 4 images.</p><p>Value range: 2-10</p><p>Sample: 4</p></td></tr></tbody></table>

### Sample Request

* The following are the corresponding image input limitations:
* Image format: JPEG、JPG、PNG、BMP、WEBP
* Image size: No more than 4 MB
* Image resolution: The size of input image should be more than 512×512 pixels and less than 3000×3000 pixels.

{% tabs %}
{% tab title="Java" %}

```javascript
IopClient client = new IopClientImp(url, appkey, appSecret);
IopRequest request = new IopRequest();
request.setApiName("/ai/image/background/generation/scenario");
request.addApiParameter("requestParams", "[{\"productTitle\":\"hello\",\"imgBase64\":\"\u56FE\u7247base64\u683C\u5F0F\",\"needLayout\":\"true\",\"modelNum\":\"mod001\",\"width\":\"800\",\"imageNum\":\"2\",\"imageFileUrl\":\"https://ae01.alicdn.com/kf/S2d0d88e656384da894b7cfe9c59b0c0du.jpg\",\"height\":\"800\"}]");
IopResponse response = client.execute(request);
System.out.println(response.getBody());
Thread.sleep(10);
```

{% endtab %}
{% endtabs %}

### Response Paramaters

| Parameter    | Parameter | Type    | Description                                                                                                           |
| ------------ | --------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `resCode`    |           | Number  | The returned result code, where 200 indicates success. For detailed error codes, please refer to the error code list. |
| `requestId`  |           | String  | A unique request ID used for troubleshooting.                                                                         |
| `success`    |           | Boolean | The status of the returned request, indicating whether the request was successful.                                    |
| `resMessage` |           | String  | The returned request information.                                                                                     |
| `data`       |           | Object  | The returned JSON result data.                                                                                        |
| `result`     |           | Object  | The returned result data.                                                                                             |
|              | `taskId`  | String  | A unique task ID. It is used for subsequent result query requests.                                                    |

### Sample Response

{% tabs %}
{% tab title="Java" %}

```javascript
{
  "data": {
    "result": {
      "taskId": "713f0cb3-f22f-490b-b3b7-3684f73bf2d6"
    }
  },
  "requestId": "21410cde17193034854038265ecd92",
  "success": true,
  "resCode": 200,
  "resMessage": "success",
  "code": "0",
  "request_id": "212a664f17193034854051990",
  "_trace_id_": "21410cde17193034854038265ecd92"
}
```

{% endtab %}
{% endtabs %}

### Errors

| Error Code | Error Message                                      | Description                                                                                                                                                                      |
| ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 500        | system error                                       | System error.                                                                                                                                                                    |
| 501        | rate limit exceed                                  | The current interface has reached the current limit. Please contact us via navigation bar or email us (<aidge_support@service.alibaba.com>) to increase the current limit value. |
| 700        | invalid input                                      | The format of the input parameters does not meet the requirements, and resMessage will return detailed fields that do not meet the requirements.                                 |
| 801        | model failed                                       | Internal call exception, please contact us via navigation bar or email us (<aidge_support@service.alibaba.com>) for troubleshooting.                                             |
| 1000       | content has sensitive data, please try other input | Content has sensitive data and cannot be handled now. Please try other input.                                                                                                    |
| 1001       | content control failed, please retry               | Content risk failed, please try other input. If an error persists,please contact us via navigation bar or email us (<aidge_support@service.alibaba.com>) for troubleshooting.    |
| 1002       | content risk filter failed, please contact us      | Content risk failed, please contact us via navigation bar or email us (<aidge_support@service.alibaba.com>).                                                                     |