Image Editing

Edit existing images with a variety of operations including inpainting, outpainting, background removal, upscaling, and more.

Try it Now

Test the Image Editing API directly in your browser:

Endpoint

POST /images/edits
POST /images/edits?async=true

Required scope: image

Use async=true for long-running operations. This returns a job ID that you can poll for completion.

Request Body

{
  "image": "https://example.com/image.png",
  "operation": "inpainting",
  "mask": "https://example.com/mask.png",
  "prompt": "A red sports car",
  "strength": 0.95,
  "model": "fal-ai/flux-kontext-lora/inpaint"
}

Common Parameters

Parameter	Type	Required	Default	Description
`image`	string	Yes	-	Image URL or base64 data
`operation`	string	Yes	-	Operation type (see below)
`model`	string	No	varies	Model to use for the operation
`strength`	number	No	`0.95`	Edit strength (0-1)
`model_inputs`	object	No	-	Additional model-specific parameters

Operations

Inpainting

Fill a masked region with new content based on a prompt.

{
  "image": "https://example.com/photo.jpg",
  "operation": "inpainting",
  "mask": "https://example.com/mask.png",
  "prompt": "A fluffy cat sitting on the couch"
}

Parameter	Required	Description
`mask`	Yes	Mask image (white = edit area, black = preserve)
`prompt`	Yes	What to generate in the masked area

Outpainting

Extend an image beyond its original boundaries.

{
  "image": "https://example.com/photo.jpg",
  "operation": "outpainting",
  "direction": "right",
  "expand_pixels": 512,
  "prompt": "Continue the forest landscape"
}

Parameter	Required	Default	Description
`direction`	Yes	-	`left`, `right`, `top`, `bottom`, or `all`
`expand_pixels`	No	`256`	Pixels to expand
`prompt`	No	-	Guidance for new content

Background Removal

Remove the background from an image, returning a PNG with transparency.

{
  "image": "https://example.com/photo.jpg",
  "operation": "backgroundRemoval"
}

No additional parameters required. Returns a PNG with transparent background.

Background Replace

Remove and replace the background with a new one.

{
  "image": "https://example.com/portrait.jpg",
  "operation": "backgroundReplace",
  "new_background": "A tropical beach at sunset"
}

Parameter	Required	Description
`new_background`	Yes	Description of new background (prompt)

Object Removal

Remove an object from the image and fill the area naturally.

{
  "image": "https://example.com/photo.jpg",
  "operation": "objectRemoval",
  "mask": "https://example.com/mask.png"
}

Parameter	Required	Description
`mask`	Yes	Mask covering the object to remove

Super Resolution (Upscaling)

Increase image resolution with AI upscaling.

{
  "image": "https://example.com/small.jpg",
  "operation": "superResolution",
  "scale": 4
}

Parameter	Required	Default	Description
`scale`	No	`2`	Scale factor: `2` or `4`

Face Enhancement

Enhance and restore faces in images.

{
  "image": "https://example.com/portrait.jpg",
  "operation": "faceEnhancement"
}

Automatically detects and enhances all faces in the image.

Colorization

Colorize black and white images.

{
  "image": "https://example.com/vintage.jpg",
  "operation": "colorization"
}

Style Transfer

Apply artistic styles to images.

{
  "image": "https://example.com/photo.jpg",
  "operation": "styleTransfer",
  "prompt": "in the style of Van Gogh's Starry Night"
}

Parameter	Required	Description
`prompt`	Yes	Style description to apply

Available Models

Each operation has a default model, but you can override with any compatible model:

Operation	Default Model	Notes
`inpainting`	`fal-ai/flux-kontext-lora/inpaint`	Fill masked regions
`outpainting`	`fal-ai/creative-outpainting`	Extend image borders
`backgroundRemoval`	`fal-ai/bria/background/remove`	Remove background
`superResolution`	`fal-ai/topaz/upscale/image`	AI upscaling
`faceEnhancement`	`fal-ai/face-enhance`	Restore faces
`styleTransfer`	`fal-ai/z-image/turbo/image-to-image`	Apply styles
`colorization`	`fal-ai/z-image/turbo/image-to-image`	Colorize B&W

Alternative Models

Model	Use Case
`fal-ai/z-image/turbo/inpaint`	Fast inpainting
`fal-ai/flux/dev/image-to-image`	High quality image-to-image
`fal-ai/aura-sr`	Fast upscaling
`fal-ai/clarity-upscaler`	High quality upscaling

Response

{
  "created": 1703123456,
  "data": [
    {
      "url": "https://fal.media/files/edited123.png",
      "width": 1024,
      "height": 1024
    }
  ],
  "model": "fal-ai/flux-kontext-lora/inpaint",
  "model_tier": "standard",
  "usage": {
    "edits_used": 1,
    "quota_multiplier": 1.25,
    "edits_remaining": 74
  }
}

Quota & Pricing

Image edits use the image_edits quota bucket:

Plan	Image Edits/Month
Free	-
Pro	75
Business	300

Model tier multipliers apply:

Tier	Multiplier	Example Operations
Fast	1x	Background removal
Standard	1.25x	Inpainting, outpainting
Premium	1.5x	High-quality upscaling

Examples

curl -X POST https://www.novakit.ai/api/v1/images/edits \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/product.jpg",
    "operation": "backgroundRemoval"
  }'

import requests

response = requests.post(
    "https://www.novakit.ai/api/v1/images/edits",
    headers={
        "Authorization": "Bearer sk_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "image": "https://example.com/room.jpg",
        "operation": "inpainting",
        "mask": "https://example.com/couch-mask.png",
        "prompt": "A modern blue velvet sofa"
    }
)

print(response.json()["data"][0]["url"])

const response = await fetch(
  "https://www.novakit.ai/api/v1/images/edits",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      image: "https://example.com/small-image.jpg",
      operation: "superResolution",
      scale: 4,
    }),
  }
);

const data = await response.json();
console.log(`Upscaled to: ${data.data[0].width}x${data.data[0].height}`);

Mask Format

Masks should match the input image dimensions. Use white (#FFFFFF) for areas to edit and black (#000000) for areas to preserve.

You can provide masks as:

URL to a PNG image
Base64-encoded image data

Creating Masks Programmatically

from PIL import Image, ImageDraw
import base64
import io

# Create a mask
mask = Image.new('L', (1024, 1024), 0)  # Black background
draw = ImageDraw.Draw(mask)

# Draw white region for editing (e.g., a rectangle)
draw.rectangle([200, 200, 800, 800], fill=255)

# Save or convert to base64
mask.save('mask.png')

# Or convert to base64 for API
buffer = io.BytesIO()
mask.save(buffer, format='PNG')
base64_mask = base64.b64encode(buffer.getvalue()).decode()

Async Mode

For long-running operations, use async mode:

import requests
import time

# Start async job
response = requests.post(
    "https://www.novakit.ai/api/v1/images/edits?async=true",
    headers={"Authorization": "Bearer sk_your_api_key"},
    json={
        "image": "https://example.com/photo.jpg",
        "operation": "superResolution",
        "scale": 4
    }
)

job_id = response.json()["id"]

# Poll for completion
while True:
    status = requests.get(
        f"https://www.novakit.ai/api/v1/jobs/{job_id}?poll=true",
        headers={"Authorization": "Bearer sk_your_api_key"}
    ).json()

    if status["status"] == "completed":
        print(f"Result: {status['outputData']['images'][0]['url']}")
        break
    elif status["status"] == "failed":
        print(f"Failed: {status.get('errorMessage')}")
        break

    time.sleep(3)

Error Handling

Status	Error	Solution
400	`image is required`	Provide image URL or base64
400	`Invalid operation`	Use a valid operation type
400	`mask is required for inpainting`	Provide mask for inpainting/object removal
402	`Image edit limit exceeded`	Upgrade plan or wait for reset
403	`Model tier not allowed`	Upgrade plan for premium operations

Supported Image Formats

Input:

JPEG / JPG
PNG
WebP

Output:

PNG (for transparency operations)
JPEG (for others)

Image Editing

On this page