Sketch to image

Sketch to image API

The sketch to image API endpoint allows you to generate an image corresponding to a sketch and a prompt describing what you expect.

Request and response

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

• a required sketch_file is the sketch you wish to use to guide the generation.
  • The sketch should be white sketch lines on a black background in a PNG, JPEG or WebP file, with a maximum width and height of 1024 pixels. For now, only square images are supported.
• a required prompt text field describing the content to generate.
  • Maximum length of 5000 characters.

In case of success:

• the response body will contain the generated image in jpeg format.
• response mime type will be image/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

To generate an image will consume 1 credit per call.

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/sketch-to-image/v1/sketch-to-image \
     -H 'x-api-key: YOUR_API_KEY' \
     -F sketch_file=@owl-sketch.jpg \
     -F 'prompt=an owl on a branch, cinematic' \
     -o result.jpg

JavaScript

const form = new FormData()
form.append('sketch_file', photo)
form.append('prompt', 'an owl on a branch, cinematic')

fetch('https://clipdrop-api.co/sketch-to-image/v1/sketch-to-image', {
  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/sketch-to-image/v1/sketch-to-image',
  files = {
    'sketch_file': ('owl-sketch.jpg', sketch_file_object, 'image/jpeg'),
    },
  data = { 'prompt': 'an owl on a branch, cinematic' },
  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: "sketch_file",
        fileName: "owl-sketch.jpg",
        mimeType: "image/jpeg"
      )
      multipartFormData.append(
        "own on a branch, cinematic",
        withName: "prompt"
      )
    },
    to: "https://clipdrop-api.co/sketch-to-image/v1/sketch-to-image",
    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(
            "sketch_file",
            "owl-sketch.jpg",
            File("docs/images/owl-sketch.jpg").asRequestBody("image/jpeg".toMediaType())
        )
        .addFormDataPart("prompt", "owl on a branch, cinematic")
        .build()

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

All possible responses

200

The result image, e.g. 

400

  Request is malformed or incomplete, non exhaustive causes can be:
    - Missing sketch_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

The request contained unprocessable content, check the body of the response for details.

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.

Support

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