# Picsart Change Background

> Swap the background of a photo using a text prompt for the new scene.

## Overview

- **Model ID**: `picsart-change-bg`
- **Workflow**: `v4/smart-background`
- **Provider**: Picsart
- **Category**: Image → Image (image)
- **Output**: One or more image URLs.
- **Tags**: background replace, image required
- **Unified endpoint**: `POST https://api.picsart.com/workflows/v1/models/execute` (model id in the body)
- **Compatibility endpoint**: `POST https://api.picsart.com/workflows/v4/smart-background/execute` (vendor's own parameters)
- **Execution**: sync (`/execute`) returns the result in one call; async is also available
- **Model page**: https://picsart.com/api-platform/models/picsart-change-bg

## Pricing

Live pricing for this model is not published yet. See https://picsart.com/pricing/ or the Pricing tab of the model page (https://picsart.com/api-platform/models/picsart-change-bg/pricing).

## Authentication

The SDK and the REST API authenticate with a Picsart API key sent as a bearer token. Create a key in the console at https://picsart.com/api-platform/dashboard/api-keys, keep it in a server-side environment variable, and never ship it in browser code or commit it.

```bash
export PICSART_API_KEY="YOUR_KEY"
```

```http
Authorization: Bearer $PICSART_API_KEY
```

The CLI and the MCP server do not use an API key: `gen-ai login` signs in through the browser once per machine and stores a token locally.

## Interfaces

- **SDK** — `@picsart/ai-sdk` (TypeScript, Node 20+, ESM). Type-safe `ai.generate()` / `ai.generateText()` with per-model parameter types; polls long jobs for you.
- **REST** — the API gateway at `https://api.picsart.com`. Sync `/execute`, or async `/submit` + `/{taskId}/result`.
- **CLI** — `@picsart/gen-ai` (`gen-ai`). Generate from a terminal, quote cost before spending, emit JSON for pipelines.
- **MCP** — the same models inside Claude Code, Cursor, Windsurf and other MCP hosts. Setup: https://picsart.com/gen-ai-mcp/

```bash
npm install @picsart/ai-sdk      # SDK
npm install -g @picsart/gen-ai   # CLI (also drives the MCP server)
```

## Unified API (recommended)

One parameter set, used by the SDK and by REST alike: the names below are what `ai.generate('picsart-change-bg', …)` takes, and what goes inside the inner `params` of a REST call. Over REST the model id travels in the body, not the path — one workflow, `v1/models`, fronts the whole catalogue.

### Execution modes

- **Sync** — `POST /workflows/v1/models/execute` returns the result in one call. Only for jobs that finish within ~20 seconds; otherwise it times out.
- **Async** — `POST /workflows/v1/models/submit` returns a task id; poll `GET /workflows/v1/models/{taskId}/result` until `response.status` is `COMPLETED` or `FAILED`. Task statuses: `ACCEPTED` · `IN_PROGRESS` · `COMPLETED` · `FAILED`.
- **SDK** — `ai.generate()` always awaits the finished result; polling is hidden.

### Input parameters

- **`imageUrls`** (`list<string>`, _required_): Source Image
  - Accepts: image URLs (max 1)
- **`prompt`** (`string`, _required_): Prompt
  - Max length: 460 characters

### Input JSON Schema

The inner `params` object. Over REST it is wrapped as `{ "params": { "model": "<id>", "params": <this> } }`; the SDK takes it directly.

```json
{
  "type": "object",
  "required": [
    "imageUrls",
    "prompt"
  ],
  "properties": {
    "imageUrls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "description": "image URL"
      },
      "maxItems": 1,
      "description": "Source Image"
    },
    "prompt": {
      "type": "string",
      "maxLength": 460,
      "description": "Prompt"
    }
  },
  "additionalProperties": false
}
```

### Required parameters example

The required parameters plus the defaults that shape the output, as a REST body:

```json
{
  "params": {
    "model": "picsart-change-bg",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ],
      "prompt": "A serene mountain lake at golden hour, ultra detailed"
    }
  }
}
```

### Response

The body is the gateway's status envelope: the output is at `response.result`, next to the task id, its status and the credits charged. Asset models return `url` plus an `items` array of results.

```json
{
  "status": "success",
  "response": {
    "id": "task_abc123",
    "status": "COMPLETED",
    "result": {
      "url": "https://cdn.picsart.com/…/result",
      "items": [
        {
          "url": "https://cdn.picsart.com/…/result"
        }
      ],
      "model": "picsart-change-bg"
    }
  }
}
```

What `ai.generate()` / `ai.generateText()` resolve to (the envelope already unwrapped):

```json
{
  "items": [
    {
      "url": "https://cdn.picsart.com/…/result"
    }
  ],
  "model": "picsart-change-bg"
}
```

### Usage examples

#### TypeScript (SDK)

```typescript
import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

const result = await ai.generate('picsart-change-bg', {
  imageUrls: [
    "https://cdn.example.com/input.jpg"
  ],
  prompt: "A serene mountain lake at golden hour, ultra detailed"
});

console.log(result.url); // image URL
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v1/models/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "model": "picsart-change-bg",
    "params": {
      "imageUrls": [
        "https://cdn.example.com/input.jpg"
      ],
      "prompt": "A serene mountain lake at golden hour, ultra detailed"
    }
  }
}'
```

#### CLI

```bash
gen-ai login  # once per machine
gen-ai models info picsart-change-bg  # this model's parameters
gen-ai pricing picsart-change-bg  # quote before spending credits
gen-ai generate -m picsart-change-bg \
  -p "A serene mountain lake at golden hour" \
  -i ./input.jpg
```

## Compatibility API (vendor parameters)

Alongside the unified API, the `v4/smart-background` workflow takes Picsart's own parameters exactly as the vendor defines them — nothing renamed or reshaped. It is the shortest path onto Picsart for request bodies already written against the vendor; the trade is that a request is written for one vendor, and the result comes back in the vendor's own shape. Same authentication.

- **Endpoint**: `POST https://api.picsart.com/workflows/v4/smart-background/execute` (sync) · `POST …/submit` + `GET …/{taskId}/result` (async)
- **SDK**: `ai.apis.run('v4/smart-background', params, { mode })` — params forwarded verbatim

### Vendor parameters

| Parameter | Type | Required | Default | Details |
| --- | --- | --- | --- | --- |
| `imageUrl` | `string` | no | — | The original image with background. Provide this OR bgRemovedImageUrl · e.g. `https://example.com/image.jpg` |
| `bgRemovedImageUrl` | `string` | no | — | Image with background already removed. Provide this OR imageUrl · e.g. `https://example.com/bg-removed.jpg` |
| `maskUrl` | `string` | no | — | Optional mask URL for precise background control · e.g. `https://example.com/mask.png` |
| `maskedImageUrl` | `string` | no | — | Optional masked image URL. Required for models/configs that need client-provided masked image · e.g. `https://example.com/masked-image.png` |
| `prompt` | `string` | no | — | Custom prompt for background generation. If not provided, smart prompts will be generated · e.g. `modern office environment with soft lighting` |
| `preview` | `boolean` | no | `false` | When true, the background generation is charged credits — but only when an input prompt is also provided. Defaults to false for backward compatibility, in which case no credits are charged. · e.g. `false` |
| `model` | `string` | no | — | AI model to use for background generation · Options: `stable-diffusion-inpaint`, `stable-diffusion-inpaint-pcp`, `ideogram-v2-turbo`, `flux-inpainter`, `flux-v2`, `gemini-3.1-flash-image`, `qwen-image-2-edit`, `seedream`, `grok-image-edit`, `flux-2-klein-4b` |
| `count` | `number` | no | — | Number of background variations to generate · 1–10 · e.g. `3` |
| `promptInfo` | `object` | no | — | Enhanced prompt information for better generation control |
| └ `objectDescription` | `string` | no | — | Pre-generated description of the main object in the image · e.g. `A red sports car with chrome details` |
| └ `stylePreference` | `string` | no | — | Preferred style or theme for background generation · e.g. `minimalist, professional, outdoor` |
| └ `colorPreference` | `string` | no | — | Color palette preferences (comma-separated) · e.g. `warm tones, earth colors, blue accents` |
| `processingOptions` | `object` | no | — | Processing preferences and optimizations |
| └ `enableProgressiveResults` | `boolean` | no | `true` | Enable progressive result publishing for real-time updates |
| └ `skipContentSafety` | `boolean` | no | `false` | Skip content safety checks (use with caution) |
| └ `inputMode` | `string` | no | `full_pipeline` | Preferred input processing mode · Options: `full_pipeline`, `bg_removed`, `with_mask` |
| `version` | `string` | no | — | Model version to use for background generation (e.g., v1.5.0) · e.g. `v1.5.0` |
| `width` | `number` | no | — | Width of the input image in pixels. Used by models that require explicit dimensions (e.g., Flux V2) · e.g. `1024` |
| `height` | `number` | no | — | Height of the input image in pixels. Used by models that require explicit dimensions (e.g., Flux V2) · e.g. `768` |
| `options` | `object` | no | — | Options controlling safety checks and drive integration |
| └ `safety_checks` | `object` | no | — | Safety check settings |
| └   `enabled` | `boolean` | no | — | Whether to run content moderation. Defaults to true. |
| └ `drive` | `object` | no | — | Save result to Picsart Drive |
| └   `name` | `string` | yes | — | File name in Picsart Drive |
| └   `attributes` | `object` | no | — | Custom attributes to attach to the file |
| └   `folder` | `object` | no | — | Target folder in Picsart Drive |
| └ `inputs_transformation` | `object` | no | — | Input transformation settings |
| └   `downscale_oversized_images` | `boolean` | no | — | Whether to downscale oversized input images. Defaults to false. |

### Example request body

```json
{
  "params": {
    "prompt": "modern office environment with soft lighting"
  }
}
```

### Usage examples

#### TypeScript (`ai.apis.run`)

```typescript
import { createClient, ApiRunMode } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
});

// Calls the 'v4/smart-background' workflow directly — params are sent as-is.
const { result, usage } = await ai.apis.run('v4/smart-background', {
  prompt: "modern office environment with soft lighting"
}, {
  mode: ApiRunMode.SYNC,
});

console.log(result); // workflow-specific output
console.log(usage?.credits); // amount charged, in $
```

#### cURL (sync)

```bash
curl -X POST 'https://api.picsart.com/workflows/v4/smart-background/execute' \
  -H 'Authorization: Bearer $PICSART_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "params": {
    "prompt": "modern office environment with soft lighting"
  }
}'
```

### Response

Over HTTP the vendor-shaped result arrives inside the gateway envelope at `response.result`:

```json
{
  "status": "success",
  "response": {
    "id": "wf_abc123",
    "status": "COMPLETED",
    "result": {
      "originalImageUrl": "…",
      "bgRemovedImageUrl": "…",
      "maskUrl": "…",
      "promptInfo": {
        "objectDescription": "…",
        "stylePreference": "…",
        "colorPreference": "…"
      },
      "images": [
        {
          "id": "wf_abc123",
          "url": "https://cdn.picsart.com/…/result.jpg",
          "prompt": "…",
          "model": "stable-diffusion-inpaint"
        }
      ],
      "metadata": {
        "modelUsed": "stable-diffusion-inpaint",
        "stagesCompleted": [
          "completed"
        ],
        "totalProcessingTime": 0,
        "performance": {}
      }
    }
  }
}
```

`ai.apis.run()` unwraps that envelope and resolves to `{ result, usage }`:

```json
{
  "result": {
    "originalImageUrl": "…",
    "bgRemovedImageUrl": "…",
    "maskUrl": "…",
    "promptInfo": {
      "objectDescription": "…",
      "stylePreference": "…",
      "colorPreference": "…"
    },
    "images": [
      {
        "id": "wf_abc123",
        "url": "https://cdn.picsart.com/…/result.jpg",
        "prompt": "…",
        "model": "stable-diffusion-inpaint"
      }
    ],
    "metadata": {
      "modelUsed": "stable-diffusion-inpaint",
      "stagesCompleted": [
        "completed"
      ],
      "totalProcessingTime": 0,
      "performance": {}
    }
  }
}
```

## Additional resources

- Model page: https://picsart.com/api-platform/models/picsart-change-bg
- Try it: https://picsart.com/api-platform/models/picsart-change-bg/playground
- SDK: https://picsart.com/api-platform/models/picsart-change-bg/sdk
- REST API (unified): https://picsart.com/api-platform/models/picsart-change-bg/api
- Compatibility API (vendor parameters): https://picsart.com/api-platform/models/picsart-change-bg/advanced
- Pricing: https://picsart.com/api-platform/models/picsart-change-bg/pricing
- This document: https://picsart.com/api-platform/models/picsart-change-bg/llms.txt
- All models: https://picsart.com/api-platform/models
- Docs — quickstart https://picsart.com/api-platform/docs/quickstart, authentication https://picsart.com/api-platform/docs/authentication, SDK https://picsart.com/api-platform/docs/sdk, REST https://picsart.com/api-platform/docs/api-reference, CLI https://picsart.com/api-platform/docs/cli, MCP https://picsart.com/api-platform/docs/mcp
- CLI reference: https://picsart.github.io/picsart-mcp-cli-docs/guide/introduction