Text Inpainting

Text Inpainting API

To replace an object in your pictures, you can use the API available at https://clipdrop-api.co/text-inpainting/v1.

The request must be an http POST and its body must be a multipart/form-data that has two images files:

• a required image_file is the original image to process.
  • The original image should be a JPG or a PNG, with a maximum resolution of 10 megapixels and a max file size of 30 Mb.
• a required mask_file is the mask image, defining the areas that need to be removed.
  • The mask image should be a PNG, and should have the same resolution as the original image and a max file size of 30 Mb.
  • The mask should be black and white with no grey pixels (e.g. values of only 0 or 255), the value of 0 indicating a pixel to keep as is and 255 a pixel to 'replace'
• a required text_prompt text field describing what you want to put in the image.

note

If you want to remove an object from your picture, you can use the Cleanup API.

In case of success:

• the response mime-type is image/jpeg and the response image is a JPEG image with the same dimensions as the image_file.
• 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.

Credits

1 successful text inpainting 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 30 requests per minute for the text inpainting API. Please let us know if you'd like higher values.

Examples

CURL

curl -X POST https://clipdrop-api.co/text-inpainting/v1 \
     -H 'x-api-key: YOUR_API_KEY' \
     -F 'image_file=@image.jpg' \
     -F 'mask_file=@mask.png' \
     -F 'text_prompt="A woman with a red scarf"' \
     -o result.png

JavaScript

const form = new FormData()
form.append('image_file', photo)
form.append('mask_file', mask)
form.append('text_prompt', 'A woman with a red scarf')

fetch('https://clipdrop-api.co/text-inpainting/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
  })

Python

import requests

r = requests.post('https://clipdrop-api.co/text-inpainting/v1',
  files = {
    'image_file': ('image.jpg', image_file_object, 'image/jpeg'),
    'mask_file': ('mask.png', mask_file_object, 'image/png')
    },
  data = { 'text_prompt': 'A woman with a red scarf' },
  headers = { 'x-api-key': 'YOUR_API_KEY'}
)
if (r.ok):
  # r.content contains the bytes of the returned image
else:
  r.raise_for_status()

Swift

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: "image.jpg",
        mimeType: "image/jpeg"
      )
      multipartFormData.append(
        maskData,
        withName: "mask_file",
        fileName: "mask.png",
        mimeType: "image/png"
      )
      multipartFormData.append(
        "A woman with a red scarf",
        withName: "text_prompt"
      )
    },
    to: "https://clipdrop-api.co/text-inpainting/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)
    }

Kotlin

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

val requestBody =
    MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart(
            "image_file",
            "image.jpg",
            File("docs/images/image.jpg").asRequestBody("image/jpeg".toMediaType())
        )
        .addFormDataPart(
            "mask_file",
            "mask.png",
            File("docs/images/mask.png").asRequestBody("image/png".toMediaType())
        )
        .addFormDataPart("text_prompt", "A woman with a red scarf")
        .build()

val request =
    Request.Builder()
        .header("x-api-key", "YOUR_API_KEY")
        .url("https://clipdrop-api.co/text-inpainting/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

200

The result image, e.g. 

400

  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

401

Missing api key.

402

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

403

Invalid or revocated api key.

422

Input image is not acceptable.

429

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

500

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

mask_file

result

Support

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