Skip to main content

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 upscale is consumed.

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 -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

Responses​

The result image, e.g. 
Example result of an upscaled image

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 & 12k.
  • a required target_height is the height in pixels of the upscaled result. Must be between 1 & 12k.
  • 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.

{
  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)
}

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​

For the smooth strategy, pricing is 1 credit per successful call.

For the detailed strategy, pricing is per output MegaPixel, 1 credit / MP e.g.

  • upscaling to 1k by 1k pixel will produce a ~1Mp image and will consume 1 credits
  • upscaling to 2k by 2k 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.

Support​

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