Replace background

Replace background API

To replace the background of your picture and teleport the foreground of the image in a new setting, the replace background API is available at https://clipdrop-api.co/replace-background/v1.

The request must be an https POST and its body must be a multipart/form-data with the following fields:

a required image_file file field with your image.
- The input image should be a PNG, a JPG or a WEBP file, with a maximum width and height of 2048 pixels and a max file size of 20 Mb.
a required prompt text field describing the scene you want to teleport your item to. The value of this field can be an empty string, in which case we will generate a scene based on your item.

In case of success:

the response mime-type will be either image/png, image/webp or image/jpeg (see Formats section), and the response body will be an image in the corresponding format, with the same dimensions as the input image.
the response headers will include a x-remaining-credits property to tell you how many credits you have left and a x-credits-consumed property to tell you how many credits were consumed by your request.

In case of an error:

the response mime-type is application/json, error type is indicated by the response status code and details are in the json body, ie

{ "error": "No api key provided" }

Authentication

Requests are authenticated with an API key. If you need one, please contact us at contact@clipdrop.co.

If your key has leaked, you can revoke it and request a new one in your account page.

Formats

Our API follows the accept header convention. For example, if you want a webp output rather than a JPEG (default), you can add a accept: image/webp header to your request and you will receive a response with content-type: image/webp and a webp binary image.

As of today, the API supports image/png, image/webp and image/jpg formats.

Credits

1 successful replace background API call = 1 credit.

Once logged in, you can claim 100 free Clipdrop APIs credits that you can use for development and debugging purposes. Once the 100 images have been consumed, further calls will be rejected.

If you need more credits, you can purchase more credits via the following link.

Quota / Rate limiting

By default, each API key has a limit of 60 requests per minute for the replace background API. Please let us know if you'd like higher values.

Examples

CURL
JavaScript
Python
Swift
Kotlin

curl -X POST https://clipdrop-api.co/replace-background/v1 \
     -H 'x-api-key: YOUR_API_KEY' \
     -F 'image_file=@wine_bottle.jpg' \
     -F 'prompt=a cozy marble kitchen with wine glasses'
     -o result.png

const form = new FormData()
form.append('image_file', photo)
form.append('prompt', 'a cozy marble kitchen with wine glasses')

fetch('https://clipdrop-api.co/replace-background/v1', {
  method: 'POST',
  headers: {
    'x-api-key': YOUR_API_KEY,
  },
  body: form,
})
  .then(response => response.arrayBuffer())
  .then(buffer => {
    // buffer here is a binary representation of the returned image
  })

import requests

r = requests.post('https://clipdrop-api.co/replace-background/v1',
  files = {
    'image_file': ('car.jpg', image_file_object, 'image/jpeg'),
    },
  data = { 'prompt': 'a cozy marble kitchen with wine glasses' },
  headers = { 'x-api-key': 'YOUR_API_KEY'}
)
if (r.ok):
  # r.content contains the bytes of the returned image
else:
  r.raise_for_status()

import Alamofire;

let imageData = try Data(contentsOf: inputPath)

let headers: HTTPHeaders = [
    "x-api-key": "YOUR_API_KEY"
]

AF.upload(
    multipartFormData: { multipartFormData in
      multipartFormData.append(
        imageData,
        withName: "image_file",
        fileName: "car.jpg",
        mimeType: "image/jpeg"
      )
      multipartFormData.append(
        "a cozy marble kitchen with wine glasses",
        withName: "prompt"
      )
    },
    to: "https://clipdrop-api.co/replace-background/v1",
    headers: headers
  )
  .responseData(queue: .global()) { response in
    switch response.result {
        case .success: do {
          // response.data here is an in memory byte buffer of the returned image
        }
        case let .failure(error): print(error)
    }

// this example uses the OkHttp library
// https://square.github.io/okhttp/
val client = OkHttpClient()

val requestBody =
    MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart(
            "image_file",
            "car.jpg",
            File("docs/images/car.jpg").asRequestBody("image/jpeg".toMediaType())
        )
        .addFormDataPart("prompt", "a cozy marble kitchen with wine glasses")
        .build()

val request =
    Request.Builder()
        .header("x-api-key", "YOUR_API_KEY")
        .url("https://clipdrop-api.co/replace-background/v1")
        .post(requestBody)
        .build()

client.newCall(request).execute().use { response ->
    if (!response.isSuccessful) throw IOException("Unexpected code $response")
    // response.body().bytes() here is a byte array of the returned image
}

Responses

The result image, e.g.

  Request is malformed or incomplete, non exhaustive causes can be:
    - Missing image_file in request
    - Input image format is not valid
    - Image resolution is too big

Missing api key.

Your account has no remaining credits, you can buy more in your account page.

Invalid or revocated api key.

Accept header not acceptable.

Too many requests, blocked by the rate limiter.
You should space out your requests in time or contact us to increase your quota.

This may be a bug on our side.
Please contact us at contact@clipdrop.co so that we can investigate.

Examples of input and outputs

image_file

prompt

a cozy marble kitchen with wine glasses

result

Support

Any question ? Contact us at contact@clipdrop.co or join the Slack community.

Replace background