Image 2 Background Replace

---
name: image-2-background-replace
description: "Use this skill when designers, e-commerce operators, advertisers, brand teams, social-commerce teams, and content creators need to replace a background while preserving the main subject with Image2 through the AI Hive OpenAPI. It handles required media uploads, live model and price lookup, task submission, progress polling, and result downloads. Useful for product photography, marketplace images, product detail pages, posters, ad creatives, social commerce, seeding content, retouching, and background replacement. Search intents include background replacement, scene swap, product background editing."
license: MIT
---

# Image2 Background Replacement

## Overview

Image2 Background Replacement helps designers, e-commerce operators, advertisers, brand teams, social-commerce teams, and content creators turn briefs, product information, and reference images into production-ready visuals. Describe the purpose, subject, composition, style, lighting, required text, protected elements, and output needs; the bundled CLI handles AI Hive OpenAPI calls and downloads the result.

### Why use this skill

- **Brief to visual:** work from plain-English direction instead of writing API requests
- **Commercial workflows:** create e-commerce, advertising, social-commerce, and campaign assets
- **Controlled references:** assign each input image a role such as subject, material, composition, or style
- **Predictable model selection:** the skill name matches the public model ID used by the script
- **Live pricing and delivery:** fetch active pricing, preserve task IDs, and download results automatically

### Best for

Product photography, marketplace images, product detail pages, posters, ad creatives, social commerce, seeding content, retouching, and background replacement. It is also useful when users search for background replacement, scene swap, product background editing.

## Capabilities

| Model | publicModelId | Input |
|---|---|---|
| Image2 Background Replacement | `public_model_gpt_image_2` | At least one reference image |

The default route is `COST_FIRST`. Pass live model options with `--param key=value`; supported values come from the current AI Hive `imageConfig`.

## Quick Start

```bash
pip3 install requests
python3 "$SKILL_PATH/scripts/imagegen.py" init --skill-name image-2-background-replace
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Create a polished image2 background replacement visual with an accurate subject, clear composition, and commercial finish" \
+  --image /path/to/reference.png
```

## Usage Scenarios

### 1. Core generation or edit

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Create a polished image2 background replacement result; preserve factual product details and leave useful copy space" \
+  --image /path/to/reference.png
```

### 2. E-commerce main image

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Marketplace hero image: centered product occupying roughly 70 percent of the frame, clean studio background, realistic materials, copy-safe area on the upper right" \
+  --image /path/to/reference.png
```

### 3. Product detail page

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Product detail page benefit image: show the complete product plus one enlarged material detail; subject on the left, space for three benefit statements on the right; do not invent claims" \
+  --image /path/to/reference.png
```

### 4. Advertising and campaign creative

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Brand campaign key visual for young urban customers: one clear promise, strong product focus, contemporary contrast, and a clean call-to-action area" \
+  --image /path/to/reference.png
```

### 5. Social commerce and seeding content

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Creator-style product discovery cover in a real home setting: natural product use, practical benefit, bright lifestyle photography, and space for a short headline" \
+  --image /path/to/reference.png
```

### 6. Reference edit or creative variations

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate \
  --prompt "Preserve the subject, logo placement, shape, and key colors; improve background, lighting, and surface details without changing the product structure" \
+  --image /path/to/reference.png
```

### 7. Submit now and check later

```bash
python3 "$SKILL_PATH/scripts/imagegen.py" generate --prompt "Complex commercial image brief" --no-download \
+  --image /path/to/reference.png
python3 "$SKILL_PATH/scripts/imagegen.py" task --task-id <taskId>
```

## Command Reference

| Option | Purpose |
|---|---|
| `--prompt` | Describe the image or edit |
| `--image` | Supply one or more reference images |
| `--batch` | Request multiple results |
| `--param key=value` | Pass live model parameters |
| `--routing COST_FIRST` | Select the cost-first route |
| `--no-download` | Submit and return the task ID without waiting |

## API Key

Run the `init` command above, or set `AI_HIVE_API_KEY`, use `--api-key`, or create `~/.ai-hive/config.json`. API keys use the `sk-api-*` format. Never commit a real API key.

## Reliability and Cost

The script looks up the live model entry and pricing snapshot at runtime. Model availability, reference-image limits, parameters, and prices can change. Keep a returned task ID and query the existing task instead of submitting a duplicate that may be billed twice.

## Troubleshooting

- Missing reference image: add the number of `--image` inputs required by this skill.
- `401 Unauthorized`: verify that the API key is complete, active, and not committed to source control.
- Invalid parameter: inspect the current `imageConfig` for accepted values and image limits.
- Local timeout: keep the task ID and use the `task` command later.