# Instant Background
**Action ID:** `instant_background`
## Description
Instantly create stunning AI-generated scene backgrounds for your product images with one click, offering commercial-grade quality and a diverse style selection for every need.
## Connection
| Name | Description | Required | Category |
| ------------------ | ------------------------------------------- | :------: | -------- |
| PixelML Connection | The PixelML connection to call PixelML API. | ✓ | pixelml |
## Input Parameters
| Name | Type | Required | Default | Description |
| ------------------ | ------- | :------: | ------- | ----------------------------------------------------------------------- |
| image\_url | string | ✓ | - | The URL of the product image. Supported formats: PNG, JPEG, JPG, WebP |
| object | string | ✓ | - | Description of what should stay in the image (the main subject/product) |
| background\_prompt | string | ✓ | - | Description of the new background to generate |
| padding\_top | integer | ✓ | - | Padding space at the top in pixels. Range: 0-512 |
| padding\_bottom | integer | ✓ | - | Padding space at the bottom in pixels. Range: 0-512 |
| padding\_left | integer | ✓ | - | Padding space at the left in pixels. Range: 0-512 |
| padding\_right | integer | ✓ | - | Padding space at the right in pixels. Range: 0-512 |
View JSON Schema
```json
{
"description": "instant background action input.",
"properties": {
"image_url": {
"title": "Image url",
"type": "string"
},
"object": {
"title": "Object (What should stay in the image?) ",
"type": "string"
},
"background_prompt": {
"title": "Describe the new background you want to add to the image.",
"type": "string"
},
"padding_top": {
"anyOf": [
{
"maximum": 512,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Padding top"
},
"padding_bottom": {
"anyOf": [
{
"maximum": 512,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Padding bottom"
},
"padding_left": {
"anyOf": [
{
"maximum": 512,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Padding left"
},
"padding_right": {
"anyOf": [
{
"maximum": 512,
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"title": "Padding right"
}
},
"required": [
"image_url",
"object",
"background_prompt",
"padding_top",
"padding_bottom",
"padding_left",
"padding_right"
],
"title": "InstantbackgroundActionInput",
"type": "object"
}
```
## Output Parameters
| Name | Type | Description |
| ----- | ------ | ----------------------------------------------------- |
| image | string | The URL of the image with the AI-generated background |
View JSON Schema
```json
{
"description": "instant background action output.",
"properties": {
"image": {
"title": "Image output",
"type": "string"
}
},
"required": [
"image"
],
"title": "InstantbackgroundActionOutput",
"type": "object"
}
```
## How It Works
This node uses AI-powered image generation to create custom backgrounds for product images. It identifies the main subject based on your object description, removes or masks the existing background, generates a new background scene based on your prompt, and composites the subject onto the new background. The padding parameters control the canvas size and subject placement, allowing you to create professional product photography with custom scenes.
## Usage Examples
### Example 1: Product on Beach Scene
**Input:**
```
image_url: "https://example.com/sunglasses.jpg"
object: "sunglasses"
background_prompt: "sunny beach with palm trees and blue ocean"
padding_top: 100
padding_bottom: 100
padding_left: 100
padding_right: 100
```
**Output:**
```
image: "https://pixelml.com/output/sunglasses-beach-abc123.jpg"
```
### Example 2: Watch in Luxury Setting
**Input:**
```
image_url: "https://example.com/watch.png"
object: "luxury watch"
background_prompt: "elegant marble table with soft lighting and gold accents"
padding_top: 50
padding_bottom: 50
padding_left: 150
padding_right: 150
```
**Output:**
```
image: "https://pixelml.com/output/watch-luxury-def456.png"
```
### Example 3: Shoes in Urban Environment
**Input:**
```
image_url: "https://example.com/sneakers.jpg"
object: "white sneakers"
background_prompt: "modern city street with graffiti wall and urban atmosphere"
padding_top: 80
padding_bottom: 120
padding_left: 100
padding_right: 100
```
**Output:**
```
image: "https://pixelml.com/output/sneakers-urban-ghi789.jpg"
```
## Common Use Cases
* **E-commerce Product Photography**: Create lifestyle product images without expensive photo shoots
* **Marketing Materials**: Generate themed backgrounds for seasonal campaigns and promotions
* **Social Media Content**: Create eye-catching product posts with varied, engaging backgrounds
* **A/B Testing**: Generate multiple background variations to test which performs best
* **Catalog Standardization**: Place products in consistent branded environments
* **Virtual Staging**: Show products in realistic use-case scenarios and environments
* **Brand Storytelling**: Create narrative-driven product imagery that aligns with brand identity
## Error Handling
| Error Type | Cause | Solution |
| -------------------- | --------------------------------------- | ------------------------------------------------------------------ |
| Invalid Image URL | URL is malformed or inaccessible | Verify the image URL is valid and publicly accessible |
| Unsupported Format | Image format is not supported | Convert image to PNG, JPEG, JPG, or WebP format |
| Subject Not Detected | AI cannot identify the specified object | Use clearer object descriptions or ensure the subject is prominent |
| Padding Error | Padding values exceed allowed range | Ensure all padding values are between 0 and 512 pixels |
| Prompt Too Vague | Background prompt is too generic | Provide more specific, detailed descriptions for better results |
| Connection Error | Cannot connect to PixelML API | Check your PixelML connection settings and API key |
## Notes
* **Object Description**: Be specific about the object to ensure accurate subject detection and preservation.
* **Background Prompts**: Detailed prompts produce better results. Include elements like lighting, colors, mood, and specific objects.
* **Padding Balance**: Use padding to control composition. Asymmetric padding can create dynamic layouts.
* **Processing Time**: Generation typically takes 15-30 seconds depending on complexity.
* **Resolution**: The output resolution depends on input image size and padding. Higher input resolution produces better results.
* **Iterative Refinement**: Try different background prompts to find the perfect scene for your product.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.agenticflow.ai/reference/nodes/instant_background.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.