Background Replace

The Background Replace endpoint allows you to isolate a subject from an image and generate a completely new, realistic background based on a text prompt.

Model Name: background-replace

Lifecycle: stable

Processing Time: ~5s–15s

Output Format: Auto (JPEG or PNG)

Delivery Methods: URL

Credits: 1 to 5 per generation (depends on quality)

Request

Submit your background replacement configuration to the universal /v1/run endpoint:

POSThttps://fititon.app/api/v1/run

Request Examples

curl -X POST https://fititon.app/api/v1/run \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{
           "model_name": "background-replace",
           "inputs": {
             "subjectImage": "https://example.com/product.jpg",
             "scenePrompt": "Product sitting on a sandy beach during golden hour",
             "quality": "2k"
           }
         }'

Response

Returns a 201 Created status with the initial tracking object. The generation runs asynchronously.

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "starting",
  "created_at": "2026-07-18T17:30:00.000Z",
  "error": null,
  "output": null
}

Once the status changes to "succeeded" (via polling the GET endpoint), the output field will contain an array with the URL pointing to your generated background:

{
  "id": "123a87r9-4129-4bb3-be18-9c9fb5bd7fc1",
  "status": "succeeded",
  "created_at": "2026-07-18T17:30:00.000Z",
  "error": null,
  "output": [
    "https://cdn.fititon.app/users/123/results/bg-replace-123.png"
  ]
}

Request Parameters

Required Parameters

subjectImageRequiredstring

The image containing the subject you want to isolate. Can be a publicly accessible URL or a Base64-encoded image string. Max size: 25MB.

Pro Tip: Subjects with clear, sharp edges against a contrasting background get the cleanest cutouts. Avoid images where the subject blends into the background (e.g. white shirt on white wall). High-contrast lighting helps the AI rely on edge detection to separate the subject perfectly.

Formatting Requirement When submitting a Base64 string, it must include the standard data URI prefix (e.g., data:image/jpeg;base64,...).

scenePromptRequiredstring

A textual description of the new background scene you want to generate behind the subject.

Optional Parameters

quality'1k' | '2k' | '4k'

Output resolution tier. Defines the resolution of the final generated image. Default: 1k

Runtime Errors

Runtime errors for this feature use the shared set documented in Error Handling. If an error occurs during processing, the status will update to "error" and the error field will contain the specific failure reason.

Credit Cost

For Developer API requests, the cost depends entirely on the chosen output quality tier.

Formula: Cost = QualityCredits

Quality Tier	Credits per Image
1k (Default)	1
2k	3
4k	5