Image upscaling

Synchronous image upscaling

The synchronous image upscaling endpoint allows you to enhance and upscale your images with a simple http request.

Request and response

The request to be made is https POST to https://clipdrop-api.co/image-upscaling/v1/upscale and its body must be a multipart/form-data with the following fields:

• a required image_file is the original image to process.
  • The original image should be a PNG, JPEG or WebP file, with a maximum resolution of 16 megapixels and a max file size of 30 Mb.
• a required target_width text field which is the desired width in pixels, a valid value is an integer between 1 & 4096.
• a required target_height text field which is the desired height in pixels, a valid value is an integer between 1 & 4096.

In case of success:

• the response body will contain the upscaled image in webp format if the original image contains transparency, as a jpeg if it does not.
• response mime type will be image/[webp/jpeg].
• 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, the 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 do not have one, you can get one here.

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

Credits

1 credit per output megapixel is consumed. e.g. for a 512x512 image: upscale x2 will produce a ~1Mp image and will consume 1 credits upscale x4 will produce a ~4Mp image and will consume 4 credits.

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. Please let us know if you'd like higher values.

Examples

CURL

curl -X POST https://clipdrop-api.co/image-upscaling/v1/upscale \
     -H 'x-api-key: YOUR_API_KEY' \
     -F image_file=@car.jpg \
     -F target_width=2048 \
     -F target_height=2048 \
     -o result.jpg

JavaScript

const form = new FormData()
form.append('image_file', photo)
form.append('target_width', 2048)
form.append('target_height', 2048)

fetch('https://clipdrop-api.co/image-upscaling/v1/upscale', {
  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/image-upscaling/v1/upscale',
  files = {
    'image_file': ('car.jpg', image_file_object, 'image/jpeg'),
    },
  data = { 'target_width': 2048, 'target_height': 2048 },
  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: "car.jpg",
        mimeType: "image/jpeg"
      )
      multipartFormData.append(
        2048,
        withName: "target_width"
      )
      multipartFormData.append(
        2048,
        withName: "target_height"
      )
    },
    to: "https://clipdrop-api.co/image-upscaling/v1/upscale",
    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",
            "car.jpg",
            File("docs/images/car.jpg").asRequestBody("image/jpeg".toMediaType())
        )
        .addFormDataPart("target_width", 2048)
        .addFormDataPart("target_height", 2048)
        .build()

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

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.

Asynchronous image upscaling

If you want to upscale large images with more flexibility and a maximum output size of 16k by 16k pixels, you can use our asynchronous image upscaling API.

Registering your image upscaling request

To register your request, an HTTP POST request needs to be made at https://clipdrop-api.co/image-upscaling/v1/async-upscale. The body of the request must be a multipart/form-data with the following fields:

• a required image_file is the original image to process.
  • The original image should be a PNG or a JPEG file, with maximum dimensions of 8k pixels and a max file size of 30 Mb.
• a required target_width is the width in pixels of the upscaled result. Must be between 1 & 16384.
• a required target_height is the height in pixels of the upscaled result. Must be between 1 & 16384.
• a required strategy is the upscaling strategy that should be used. Possible values are smooth & detailed. You can try them on clipdrop.co/image-upscaler.

In case of success:

• the response body will be a json with the task id that can be used in the other endpoints {"taskId": "the task id"}.
• 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, the error type is indicated by the response status code and details are in the json body, ie

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

Checking on the status of your task

To follow the progression of your task, you can poll the following url https://clipdrop-api.co/async-tasks/v1/task-status/<taskId>, replacing taskId with the value received in the previous endpoint. The request should be an http GET with an empty body.

The responses will always have JSON bodies.

Task is queued

{
  status: queued,
  position: position in the queue,
  eta: epoch in milliseconds of the eta (estimates are still a WIP, so should be used with caution)
}

Task is completed

{
  status: completed,
}

Task has failed

{
  status: failed,
}

The recommended client behavior is to poll this endpoint every 5 seconds or so, and move on to the next step when the status has changed to completed.

Getting the upscaled image

Once the status of your task has switched to completed, you can generate a signed url of your image that will be valid for one hour. To do so, you can send an http GET request to https://clipdrop-api.co/async-tasks/v1/result/<taskId>, replacing the placeholder with your task id.

The response will have the following JSON body {'downloadUrl': 'the url to download your image, valid one hour'}.

Authentication

Requests are authenticated with an API key which should be passed as a x-api-key header. If you do not have one, you can get one here.

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

Pricing & credits

Pricing is per output MegaPixel, 1 credit / MP e.g. with the smooth strategy:

• upscaling to 1k by 1k pixel will produce a ~1Mp image and will consume 0.2 credits
• upscaling to 2k by 2k will produce a ~4Mp image and will consume 0.8 credits.

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. Please let us know if you'd like higher values.

Support

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