Replace and generate background

Replace background finds the background of an image and redraws it from a prompt. Generate background does the same for an area you mark with a mask.

$0.04 / $0.08

per image, raster / vector

Image + prompt → image

up to 10 MB, 16 MP

POST /v1/images/replaceBackground

endpoint, mask variant below

Try it

Get an API token on your profile page (it needs a positive API units balance) and set it once per terminal session:

export RECRAFT_API_TOKEN=your_token

Then run. The request replaces the background of a public sample illustration:

curl https://external.api.recraft.ai/v1/images/replaceBackground \
  -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png",
    "prompt": "a desert highway at sunset",
    "model": "recraftv3"
  }'

# pip install requests
import os

import requests

response = requests.post(
    'https://external.api.recraft.ai/v1/images/replaceBackground',
    headers={'Authorization': f"Bearer {os.environ['RECRAFT_API_TOKEN']}"},
    json={
        'image_url': 'https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png',
        'prompt': 'a desert highway at sunset',
        'model': 'recraftv3',
    },
)
if not response.ok:
    raise SystemExit(f'{response.status_code}: {response.text}')
print(response.json()['data'][0]['url'])

// Node.js 18+, run as an ES module (file.mjs)
const response = await fetch('https://external.api.recraft.ai/v1/images/replaceBackground', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RECRAFT_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image_url: 'https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png',
    prompt: 'a desert highway at sunset',
    model: 'recraftv3',
  }),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result.data[0].url);

# pip install openai
import os

from openai import OpenAI

client = OpenAI(
    base_url='https://external.api.recraft.ai/v1',
    api_key=os.environ['RECRAFT_API_TOKEN'],
)

response = client.post(
    path='/images/replaceBackground',
    cast_to=object,
    body={
        'image_url': 'https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png',
        'prompt': 'a desert highway at sunset',
        'model': 'recraftv3',
    },
)
print(response['data'][0]['url'])

Response

Both operations return the same result.

{
  "created": 1759140000,
  "credits": 40,
  "data": [
    {
      "image_id": "0e6a1b8c-5b1f-4a8e-9f3a-2c7d4e8b9a10",
      "url": "https://..."
    }
  ]
}

data has one entry per image (n). Download each image from its url. With recraftv3_vector, each url points to an SVG file.
Image URLs are temporary: files are kept for about 24 hours, so download them. See Limits and sizes.
credits is the number of API units charged for the request.

Parameters

Parameters of POST /v1/images/replaceBackground:

Parameter	Type, default	Description
`image_url`	string, required in JSON	URL or data URL of the input image.
`image`	file, required in multipart	The input image, uploaded instead of `image_url`.
`prompt`	string, required	What the new background looks like. Up to 1,000 characters.
`model`	string, `recraftv3`	`recraftv3` (raster) or `recraftv3_vector` (SVG). Other models don’t support background operations.
`style`	string	A curated style for the new background. V3 styles only.
`n`	integer, `1`	Number of images, 1 to 6.
`negative_prompt`	string	What the new background must not contain.
`response_format`	string, `url`	`url`, `b64_json`, or `multipart`. See Image inputs and results.
`image_format`	string, `webp`	`webp` (lossless) or `png`. See Image format.

More parameters

Parameter	Type, default	Description
`style_id`	UUID	Use a custom style as a visual reference. V3 styles only.
`style_match`	string	Only `regular` for V3.
`text_layout`	array of objects	Words and their positions in the image. See Text layout.
`controls`	object	Extra generation settings: `colors`, `background_color`, `artistic_level`, `no_text`. See Controls.

The input image must be PNG, JPG, WEBP, or SVG, under 10 MB, up to 16 MP, with sides between 256 and 4096 px. See Input images.

Generate background

POST /v1/images/generateBackground works like replace background, but you mark the background with a mask instead of letting the model find it. Use it when you want to control exactly which area is regenerated. The request below uses the sample image and a sample mask that is white over the background and black over the motorcycle and rider, so only the background is generated.

curl https://external.api.recraft.ai/v1/images/generateBackground \
  -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png",
    "mask_url": "https://www.recraft.ai/docs/images/samples/motorcycle-background-mask.png",
    "prompt": "a desert highway at sunset",
    "model": "recraftv3"
  }'

# pip install requests
import os

import requests

response = requests.post(
    'https://external.api.recraft.ai/v1/images/generateBackground',
    headers={'Authorization': f"Bearer {os.environ['RECRAFT_API_TOKEN']}"},
    json={
        'image_url': 'https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png',
        'mask_url': 'https://www.recraft.ai/docs/images/samples/motorcycle-background-mask.png',
        'prompt': 'a desert highway at sunset',
        'model': 'recraftv3',
    },
)
if not response.ok:
    raise SystemExit(f'{response.status_code}: {response.text}')
print(response.json()['data'][0]['url'])

// Node.js 18+, run as an ES module (file.mjs)
const response = await fetch('https://external.api.recraft.ai/v1/images/generateBackground', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RECRAFT_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    image_url: 'https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png',
    mask_url: 'https://www.recraft.ai/docs/images/samples/motorcycle-background-mask.png',
    prompt: 'a desert highway at sunset',
    model: 'recraftv3',
  }),
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result.data[0].url);

# pip install openai
import os

from openai import OpenAI

client = OpenAI(
    base_url='https://external.api.recraft.ai/v1',
    api_key=os.environ['RECRAFT_API_TOKEN'],
)

response = client.post(
    path='/images/generateBackground',
    cast_to=object,
    body={
        'image_url': 'https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png',
        'mask_url': 'https://www.recraft.ai/docs/images/samples/motorcycle-background-mask.png',
        'prompt': 'a desert highway at sunset',
        'model': 'recraftv3',
    },
)
print(response['data'][0]['url'])

Request parameters

Parameter	Type, default	Description
`image_url`	string, required in JSON	URL or data URL of the input image.
`image`	file, required in multipart	The input image, uploaded instead of `image_url`.
`mask_url`	string, required in JSON	URL or data URL of the mask.
`mask`	file, required in multipart	The mask, uploaded instead of `mask_url`.
`prompt`	string, required	What the new background looks like. Up to 1,000 characters.

The mask is a grayscale image (PNG, JPG, or WEBP) of exactly the same size as the image. Pure white pixels (255) are regenerated and pure black pixels (0) stay unchanged. Every pixel must be one of the two. model, n, style, style_id, style_match, negative_prompt, text_layout, controls, response_format, and image_format work as in the table above. The image limits are the same.

Examples

Upload a local file

curl https://external.api.recraft.ai/v1/images/replaceBackground \
  -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
  -F "image=@image.png" \
  -F "prompt=a desert highway at sunset" \
  -F "model=recraftv3"

import os

import requests

with open('image.png', 'rb') as image:
    response = requests.post(
        'https://external.api.recraft.ai/v1/images/replaceBackground',
        headers={'Authorization': f"Bearer {os.environ['RECRAFT_API_TOKEN']}"},
        data={
            'prompt': 'a desert highway at sunset',
            'model': 'recraftv3',
        },
        files={'image': image},
    )
if not response.ok:
    raise SystemExit(f'{response.status_code}: {response.text}')
print(response.json()['data'][0]['url'])

Upload a local image and mask

For generate background, upload the mask next to the image.

curl https://external.api.recraft.ai/v1/images/generateBackground \
  -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
  -F "image=@image.png" \
  -F "mask=@mask.png" \
  -F "prompt=a desert highway at sunset" \
  -F "model=recraftv3"

import os

import requests

with open('image.png', 'rb') as image, open('mask.png', 'rb') as mask:
    response = requests.post(
        'https://external.api.recraft.ai/v1/images/generateBackground',
        headers={'Authorization': f"Bearer {os.environ['RECRAFT_API_TOKEN']}"},
        data={
            'prompt': 'a desert highway at sunset',
            'model': 'recraftv3',
        },
        files={'image': image, 'mask': mask},
    )
if not response.ok:
    raise SystemExit(f'{response.status_code}: {response.text}')
print(response.json()['data'][0]['url'])

Get an SVG result

recraftv3_vector returns SVG instead of a raster image. It costs $0.08 per image, for both operations.

curl https://external.api.recraft.ai/v1/images/replaceBackground \
  -H "Authorization: Bearer $RECRAFT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://cdn.prod.website-files.com/655727fe69827d9a402de12c/679b82f54ef9617939df9d8e_motorcycle--going-fast.png",
    "prompt": "a desert highway at sunset",
    "model": "recraftv3_vector"
  }'

Inpainting

Regenerate any masked area, not only the background.

Outpainting

Extend an image beyond its borders.

Recraft V3

The model line behind background operations.

Pricing

Prices of every model and tool.

Get started

Models

Tools

Reference

Replace and generate background

$0.04 / $0.08

Image + prompt → image

POST /v1/images/replaceBackground

Try it

Response

Parameters

Generate background

Request parameters

Examples

Inpainting

Outpainting

Recraft V3

Pricing

$0.04 / $0.08

Image + prompt → image

POST /v1/images/replaceBackground

​Try it

​Response

​Parameters

​Generate background

​Request parameters

​Examples

​Related

Inpainting

Outpainting

Recraft V3

Pricing

Try it

Response

Parameters

Generate background

Request parameters

Examples

Related