AI Background Changer

Illustrative artwork; not a sample Actor result.

Change a photo background with a text description. Upload your photos, describe the scene you want, and receive edited PNG images with a result table ready for your workflow.

Use it for profile photo concepts, product scene mockups, social media images and consistent backgrounds across a photo batch. No separate image-service account or API key is required.

Photo-background concepts for content and design teams

Use this AI background changer to explore a new scene around an existing photograph you are allowed to edit. It can support a portrait concept, an early product-scene mockup or a small creative review queue. The edited PNG is a generated interpretation; it is not evidence that a person visited a location or that a product was photographed in a real studio.

Workflow	Useful input	Review before using
Explore a studio portrait concept	One portrait and a plain background prompt	Face, hair, clothing and shoulder changes
Prepare a product-scene mockup	An authorized product photo and a scene description	Product shape, labels, scale and color
Compare two scene ideas	Separate runs with one prompt each	Framing can vary; no fixed-seed comparison is promised
Review a small creative batch	Multiple photos and one shared prompt	Each image needs visual acceptance
Hand an edited asset to a designer	Delivered PNG and dimensions	Signed-link access and storage retention

Start with a simple prompt and one representative photo. A delivery flag establishes that a PNG was saved, not that the original foreground was preserved exactly. The existing illustrative cover above is not an Actor output or an accuracy benchmark.

Start with one photo

1. Choose Uploaded files only in Photo input mode.
2. Add your photo under Upload photos from your computer.
3. Describe the replacement background. For example: a light blue studio background with soft lighting.
4. Start the Actor, then open Delivered images to find your result.
5. Open the signed result link to download the PNG, then review it before use.

For a batch, add more photos and choose how many to process at once. Every photo in a run uses the same background description.

Background ideas

Goal	Example description
Profile photo concept	A clean light blue studio background with soft lighting
Product scene mockup	A plain white studio background with a subtle floor shadow
Office setting	A bright modern office, softly blurred behind the subject
Social media creative	A tropical beach at sunset with warm evening light
Minimal scene	A plain dark gray background with soft studio lighting

These are prompt suggestions, not guarantees of a particular result. The profile icon is illustrative artwork.

Uploads, URLs and API input

Field	Accepted input
imageFiles	Photos uploaded through the Console file picker
imageUrl	One direct image URL
imageUrls	A list of direct image URLs or image data URIs
imageBase64	A list of base64 images, with or without a data URI prefix
storageImages	Apify photo records: {"storeId":"STORE_ID","key":"PHOTO.png"}

Use workflow to choose uploads, urls, base64 or storage. The default auto mode and combined mode combine the supplied photo sources. Upload local files through the picker; a local filesystem path cannot be read by a cloud run.

For protected source storage, the run must have access to the image record. storageImages also accepts an optional record signature for signed access. Keep access links and photo payloads private.

Example for URL input:

{
  "workflow": "urls",
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "backgroundPrompt": "a light blue studio background with soft lighting",
  "maxConcurrency": 3,
  "timeout": 300,
  "maxRetries": 2
}

Batch limits and settings

Setting	Supported values
Photos per run	Up to 100 unique input references
Photo size	Up to 20 MB decoded and 25 megapixels
backgroundPrompt	Up to 1,500 characters
maxConcurrency	1–8 photos processed at once; default 3
timeout	60–1,800 seconds per photo; default 300
maxRetries	0–3 retries for temporary errors; default 2

Six simultaneous photos have been verified in a cloud run. Sustained processing at the 100-photo and eight-worker limits has not been verified. Start small and increase the batch after reviewing your results. Use at least 1,024 MB memory for larger batches or high-resolution photos. Allow enough run time for processing and delivery; no fixed completion time is promised.

Optional proxyConfiguration controls the processing connection. The default uses residential Apify Proxy; proxy usage may add to the run cost.

Results and incomplete batches

Each delivered image has a Dataset row containing its inputIndex, sourceType, source reference, requested prompt, resultUrl and dimensions. The output is a PNG. resultUrl is a signed download link that opens without adding an API token. Anyone with that link can access that photo, so keep private-photo links private. File retention follows your storage settings.

Open Run summary for delivered, failed and pending counts. complete is true only when all normalized inputs were delivered; collectionStatus=partial means some inputs remain even if the run says SUCCEEDED. qualityVerified=false means delivery is not a visual quality certification. Failed input indexes and error codes identifies photos that could not be completed. Failed photos do not appear as successful result rows.

RETRY_INPUT in the run's storage contains incomplete inputs for another run. It preserves the photo sources, prompt, limits and selected proxy configuration in combined mode. It may include private photos, proxy access settings or access links. If delivery was uncertain, check the existing results before retrying to avoid duplicating a result.

API and MCP with AI agents

Permanent Actor ID: zR4XPhvEedoTPzrHN. Store name: apivault_labs/aI-background-changer (preserve the capital I when addressing it by name).

curl -X POST "https://api.apify.com/v2/acts/zR4XPhvEedoTPzrHN/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" -H "Content-Type: application/json" \
  -d '{"workflow":"urls","imageUrls":["https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"],"backgroundPrompt":"a light blue studio background","maxConcurrency":1}'

Creation is asynchronous. Poll the run ID, then use defaultDatasetId for delivered rows and defaultKeyValueStoreId for SUMMARY, ERRORS and RETRY_INPUT. Download signed resultUrl links and review the actual images before use. Actor API.

In hosted Apify MCP, discover the Actor tool by permanent ID or Store name. Example agent request: “Edit this public photo with a light blue studio background, one worker. Wait for completion, read Dataset, SUMMARY and ERRORS with get-dataset-items/get-key-value-store-record. Report delivered/pending counts, link the signed output and explain that foreground details may change.” API and MCP require Apify authentication. Never include private photo links, inline payloads or RETRY_INPUT in a public agent report.

Schedules and integrations can connect repeated batches to your workflow. Every photo uses the same prompt; per-photo prompts, fixed output dimensions, alternate file formats and exact subject preservation are not supported. Do not use empty API input as a paid example: it fails validation without an image result.

Quality and pricing

This is generative editing. Faces, hair, clothing, pose, framing and product details can change along with the background. Exact preservation of the original person or product is not guaranteed. Review results before using them for identity-sensitive portraits or accurate product listings.

The price is $0.007 per delivered photo — $7 per 1,000 photos, plus Apify platform usage. Users pay platform resource costs separately, including compute, storage and proxy usage. Failed photos do not create paid image results, but resource costs still apply to unsuccessful runs and inputs. The Actor start fee is $0.00005 per GB of allocated memory, with a minimum of one event per run. Check the Pricing tab for current charges. Availability and completion time can vary.

Updates

0.1 — Collection reports and recovery: explicit complete/partial status, unverified quality flag, validation errors, preserved proxy settings in retry input and API/MCP examples.

0.1.14 — README cover: added an illustrative photo background editing cover. Photo processing is unchanged.

0.1.12 — Documentation update: clearer upload instructions, background ideas, result access and recovery guidance. Public descriptions now focus on user-facing behavior. Photo processing is unchanged.

0.1 — Batch and input improvements: added file uploads, URL/base64 and Apify storage inputs, adjustable parallel processing, per-photo error reporting and recovery for incomplete batches.

Support

For a failed image, report the run ID and a non-sensitive example in the Actor's Issues tab. Keep private image links and credentials out of public reports.

Small background-editing inputs

Every input in a run receives the same backgroundPrompt. Choose a direct accessible photo URL or the Console upload control; a local filesystem path cannot be downloaded by a cloud worker. These examples use a public portrait sample. Replace it with an authorized photo and keep private-photo links out of shared inputs and reports.

One portrait with a simple studio concept

{
  "workflow": "urls",
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "backgroundPrompt": "a light blue studio background with soft lighting",
  "maxConcurrency": 1,
  "timeout": 300,
  "maxRetries": 0
}

Use a simple first scene and inspect the actual delivered PNG. The subject can be regenerated or altered along with the background. No retries are requested in this example; default residential processing traffic still has separate usage costs.

Use the single-image URL input

{
  "workflow": "urls",
  "imageUrl": "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400",
  "backgroundPrompt": "a plain dark gray studio background with soft even lighting",
  "maxConcurrency": 1,
  "timeout": 300,
  "maxRetries": 0
}

imageUrl is an alternative convenience input. Clear any old imageUrls or uploads in the Console when you intend to process only this photo. Auto/combined modes can include more supplied sources than expected.

Prepare an explicit combined-source request

{
  "workflow": "combined",
  "imageFiles": [],
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "backgroundPrompt": "a bright softly blurred office background",
  "maxConcurrency": 1,
  "timeout": 300,
  "maxRetries": 0
}

This copyable instance uses a URL with an empty upload list. Add files through the upload editor if needed. The combined unique-reference cap does not prove identical image bytes on different URLs will be deduplicated.

Allow a longer single-photo processing window

{
  "workflow": "urls",
  "imageUrls": [
    "https://images.unsplash.com/photo-1507003211169-0a1dd7228f2d?w=400"
  ],
  "backgroundPrompt": "a plain white studio background with soft lighting",
  "maxConcurrency": 1,
  "timeout": 600,
  "maxRetries": 0
}

A longer allowance is not a completion or quality guarantee. The platform run timeout also applies. Do not resubmit a photo whose delivery status is uncertain until you reconcile the original run and its stored results.

Review an edited image as a generated asset

Download the signed resultUrl and view it at a practical display size. Compare the original face/product outline, clothing or labels, crop and lighting. A changed background with an altered foreground can be acceptable as a concept and unsuitable as a faithful product image. qualityVerified remains false because the Actor does not independently certify these visual requirements.

Keep the original photo, requested prompt and delivered dimensions in a private review record. Do not claim pixel-preserving compositing, fixed output dimensions, stable random seeds or an exact background match; those controls are not exposed in this contract. For two candidate scenes, use separate runs and compare the actual outputs, rather than treating the prompt as a deterministic template.

The Dataset/CSV contains result links and metadata. Download approved images into storage you control before the run's retention period ends. Anyone who has a signed result link can access that image without your API token. Restrict where those links are shared, especially for customer photographs. RETRY_INPUT can contain original image payloads, signed references and proxy configuration; it belongs in private recovery handling.

For a partial batch, read delivered/pending counts and ERRORS before using RETRY_INPUT. A successful run can deliver only part of the normalized inputs. Retrying already successful photos creates additional processing and possible image-result events. Recovery does not guarantee exactly-once behavior across an uncertain storage write or a lost client response.

Background changer API questions

Can I specify a different prompt per photo? No. One backgroundPrompt applies to the entire run. Group photos by the desired prompt or submit separate bounded jobs.

Does it preserve a real person's face or a product label? Exact preservation is not guaranteed. Faces, hair, clothing, pose, scale and fine details can change. Review the original and output before using a generated concept where identity or product accuracy matters.

What is one paid result? One edited photo successfully delivered to the default Dataset, at $0.007. At 512 MB the start fee has its one-event minimum of $0.00005, so one delivered photo creates $0.00705 in event fees before separate compute/proxy/storage usage. At memory above 1 GB the startup event count increases. Failed photos do not create image-result fees, but source attempts and startup can still cost money.

Can I use private Apify image records? Use the supported storageImages references or file upload control and ensure the run has legitimate access. Keep signatures/payloads private. Do not place API tokens inside the photo input or publish recovery records.

Does eight-worker input support prove bulk throughput? No. The documented input bounds and the previously recorded six-photo check do not establish sustained 100-photo throughput, a completion-time SLA or identical visual quality across a batch.

Can n8n or an AI agent approve the image automatically? They can manage run IDs, storage and delivery metadata, but a successful row alone does not establish visual fidelity. Use the existing integration links below and retain a meaningful visual review step for the intended use.

n8n and developer integrations

Use this Actor in your automation or application with the existing community integrations below. An Apify account and API token are required; Actor and platform charges follow the current pricing.

• n8n community node: n8n-nodes-apivault-ai-background-changer. Install package name n8n-nodes-apivault-ai-background-changer in a self-hosted n8n instance that permits community packages.
• Python client and examples: GitHub.
• n8n source and usage: GitHub.

These are community packages. Publication on npm does not establish n8n verification or availability in n8n Cloud. Review the linked package README for supported inputs and setup.