Version 4.0.8 API Documentation

Using this application programming interface (API) you can integrate our raster image to scalable vector graphics conversion service into your own service or software.

OpenAPI YAML Definition:

vectorizer-io-api-definition-openapi-v4.0.8.yaml

To view documentation or automatically create software client implementations for various programming languages visit and paste the above OpenAPI YAML definition file into the Swagger editor: https://editor.swagger.io/

! Important Information !
Pricing

The payment unit for API calls are credits. The price for one successful API call is one credit. To learn more on available credits packages see our pricing page or contact us for a custom quote.

Contact

Email: support+sales@vectorizer.io

API Security:
CreditsCodeAuth ( apiKey )
Successful calls to API endpoints are charged with one credit from the specified credits code. If an error occurs during an API call no credit will be charged. If you want to evaluate this service with 'free credits' then you do not have to specify this header. Contact britnex+vectorizerapisales@gmail.com if you have any questions.
Add the following HTTP header to authenticate using your credits code:

X-CREDITS-CODE:    YOUR_CREDITS_CODE_HERE
API Endpoints:
POST vectorize
POST paintbynumbers
POST vectorize

https://api.vectorizer.io/v4.0/vectorize

Main vectorization endpoint to covert raster images to scalable vector graphics. Upload input image, start vectorization process, keep connection alive until vectorization is completed and download generated output file in specified output file format. Completion time depends on input image size, number of colors and structure but should never exceed 59 seconds.
  • Web
  • cURL
  • PHP
  • Java
  • Python
  • Node.js
# cURL HTTP POST using multipart form upload: 
 			
<?php

    // this example requires GuzzleHttp Client. for more information visit: https://docs.guzzlephp.org/en/stable/overview.html#installation
    require 'vendor/autoload.php';
    $client = new GuzzleHttp\Client();
    $res = $client->post('https://api.vectorizer.io/v4.0/vectorize', [
	    'multipart' => [
PARAMS
        ],
        'headers' => [
           'X-CREDITS-CODE' => 'YOUR_CREDITS_CODE_HERE',
        ]
    ]);
    $fp = fopen('exampleimage.svg', 'wb');
    fwrite($fp, $res->getBody());
    fclose($fp);

?>
Coming soon.
Coming soon.
Coming soon.
Try it out:

( no credits available. sign in to enable this button )
Request Body ( multipart/form-data )
image
byte[] 		Upload File:
Input image binary. Use PNG file format for best compatibility. Try to avoid uploading files larger than 1MB (max. 10MB) to prevent timeouts.
format
string 		Enumeration:
Supported output file formats:
  • svg = Scalable Vector Graphics (default)
  • eps = Encapsulated Postscript
  • png = PNG (raster image)
Contact us if you need other output file formats.
colors
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 99 )

Maximum number of colors used to generated the output. A value of 0 is automatic mode.
model
string 		Enumeration:
algorithm
string 		Enumeration:
  • auto automatic algorithm detection
  • Filled Layers:
    • overlap, overlaplow, overlapmid, overlaphigh
    • nooverlap
    • single
  • Stroked Layers:
    • strokesingle
    • contour
    • centerline
    • border
details
string 		Enumeration:
Other values than auto reduce the detail level in the input image to cluster similar pixels to larger areas. (Only relevant for model: photo, sketch and clipart)
antialiasing
string 		Enumeration:
minarea
integer 		Value:   ( Default value: 5,  Minimum: 0,  Maximum: 1000000 )

Minimum area of output shapes in px^2.
colormergefactor
integer 		Value:   ( Default value: 5,  Minimum: 0,  Maximum: 100 )

Color merge factor in percent. Merges similar output colors to a color group.
unit
string 		Enumeration:
Unit for the width/height for the output file. (Only relevant for SVG output format)
width
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 1000000 )

A value of 0 is the default value. Other values define the width of the vectorized result in the specified unit. Height will be calculated by ratio of input image (or a specified height value is used).
height
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 1000000 )

A value of 0 is the default value. Other values define the height of the vectorized result in the specified unit. Width will be calculated by ratio of input image (or a specified width value is used).
transparency-threshold
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 255 )

(optional) For default behavior omit this parameter or set to value 0.
Transparency threshold value. All pixels with a transpareny level below this threshold will be threated as full transparent. If transparency-color is set to a RGB color code, then transparent pixels with be replaced with specified non-transparent color.
transparency-color
string
(optional) For default behavior omit this parameter or set to empty string.
  • transparent: keep transparent pixels transparent
  • 000000 replace transparent pixels using black color
  • FF0000 replace transparent pixels using red color
Responses

Use the HTTP status code of the response to implement your error handling. The HTTP body of the response is only for debugging purposes and can change without a version change.
For error status codes indicating a server problem (500, 504) it is highly recommended to implement a exponential backoff for retries in your software.

Status Code Description
200
Output format depends on format argument.

HTTP response headers:
X-CREDITS-AVAILABLE Number of available credits before starting the vectorization operation. This number does not include the one credit that will be charged for a successful download. [this header requires authentication using X-CREDITS-CODE header]
X-CREDITS-EXPIRE Credits valid until this date (RFC7231 format). [this header requires authentication using X-CREDITS-CODE header]
X-FREE-CREDITS-AVAILABLE Free credits available. [this header is only available if not authenticated using X-CREDITS-CODE header]
500
Error: Internal Server Error.
402
Error: Payment required.
413
Error: Payload too large. (max. 10MB)
429
Error: Too many requests (limited to max. 60 API calls per minute. For higher limit please contact us.)
504
Error: Gateway Timeout

https://api.vectorizer.io/v4.0/paintbynumbers

Vectorization endpoint for paint-by-number images. Completion time depends on input image size, number of colors and structure but should never exceed 59 seconds.
  • Web
  • cURL
  • PHP
  • Java
  • Python
  • Node.js
# cURL HTTP POST using multipart form upload: 
 			
<?php

    // this example requires GuzzleHttp Client. for more information visit: https://docs.guzzlephp.org/en/stable/overview.html#installation
    require 'vendor/autoload.php';
    $client = new GuzzleHttp\Client();
    $res = $client->post('https://api.vectorizer.io/v4.0/paintbynumbers', [
	    'multipart' => [
PARAMS
        ],
        'headers' => [
           'X-CREDITS-CODE' => 'YOUR_CREDITS_CODE_HERE',
        ]
    ]);
    $fp = fopen('exampleimage.svg', 'wb');
    fwrite($fp, $res->getBody());
    fclose($fp);

?>
Coming soon.
Coming soon.
Coming soon.
Try it out:

( no credits available. sign in to enable this button )
Request Body ( multipart/form-data )
image
byte[] 		Upload File:
Input image binary. Use PNG file format for best compatibility. Try to avoid uploading files larger than 1MB (max. 10MB) to prevent timeouts.
output
string 		Enumeration:
  • color: vectorization result with colors and numbers
  • contour: vectorization result with only the contour lines and numbers (default)
  • bundle: vectorization results in different file formats in ZIP file archive (same as interactive version of the website) (parameter 'format' is ignored for this option)
format
string 		Enumeration:
Supported output file formats:
  • svg = SVG (default)
  • png = PNG
. Contact us if you need other output file formats.
fontsize
integer 		Value:   ( Default value: 60,  Minimum: 0,  Maximum: 100 )

Maximum font size for the labels representing the color numbers. The default value of 60 might be too large for your use case, then use a smaller value like 12.
colors
number 		Value:   ( Default value: 32,  Minimum: 1,  Maximum: 99 )

Maximum number of colors used to generated the output. (Recommended: 24, 36, 50)
model
string 		Enumeration:
noisereduction
string 		Enumeration:
Noise reduction level to improve input image quality. (Use off for most use cases, because other values can add 10-30 seconds of processing time)
details
string 		Enumeration:
Other values than auto reduce the detail level in the input image to cluster similar pixels to larger areas. (Only relevant for model: photo, sketch and clipart)
minarea
integer 		Value:   ( Default value: 5,  Minimum: 0,  Maximum: 1000000 )

Minimum area of output shapes in px^2.
colormergefactor
integer 		Value:   ( Default value: 5,  Minimum: 0,  Maximum: 100 )

Color merge factor in percent. Merges similar output colors to a color group.
minradius
number 		Value:   ( Default value: 1.5,  Minimum: 0,  Maximum: 8.0 )

Minimum incircle radius in mm for output shapes. Too remove 'small' non-paintable areas select a higher value. (The radius is related to output width/height in mm)
unit
string 		Enumeration:
Unit for the width/height for the output file.
width
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 1000000 )

A value of 0 is the default value. Specify '500' for 50cm. Other values define the width of the vectorized result in the specified unit. Height will be calculated by ratio of input image (or a specified height value is used).
height
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 1000000 )

A value of 0 is the default value. Specify '400' for 40cm. Other values define the height of the vectorized result in the specified unit. Width will be calculated by ratio of input image (or a specified width value is used).
transparency-threshold
number 		Value:   ( Default value: 0,  Minimum: 0,  Maximum: 255 )

(optional) For default behavior omit this parameter or set to value 0.
Transparency threshold value. All pixels with a transpareny level below this threshold will be threated as full transparent. If transparency-color is set to a RGB color code, then transparent pixels with be replaced with specified non-transparent color.
transparency-color
string
(optional) For default behavior omit this parameter or set to empty string.
  • transparent: keep transparent pixels transparent
  • 000000 replace transparent pixels using black color
  • FF0000 replace transparent pixels using red color
facedetect
string 		Enumeration:
By default the position of faces are detected to improve the detail level of faces. This may produce color patches which are too small to paint, in this case a value of off disables face detection.
Responses

Use the HTTP status code of the response to implement your error handling. The HTTP body of the response is only for debugging purposes and can change without a version change.
For error status codes indicating a server problem (500, 504) it is highly recommended to implement a exponential backoff for retries in your software.

Status Code Description
200
Output format depends on format argument.

HTTP response headers:
X-CREDITS-AVAILABLE Number of available credits before starting the vectorization operation. This number does not include the one credit that will be charged for a successful download. [this header requires authentication using X-CREDITS-CODE header]
X-CREDITS-EXPIRE Credits valid until this date (RFC7231 format). [this header requires authentication using X-CREDITS-CODE header]
X-FREE-CREDITS-AVAILABLE Free credits available. [this header is only available if not authenticated using X-CREDITS-CODE header]
X-COLORCODES Hex RGB colors codes of vectorization result. First entry has the label '1' in the vector result. (Colors are SPACE separated values of [0-9A-F]{6}): example: '0000FF 00FF00 FF0000'
X-COLORAREAS Area used by each color in the vectorization result in percent 0 - 100. First entry has the label '1' in the vector result. (Areas are SPACE separated values of decimal percent values): example: '52 0.05 12.5'
500
Error: Internal Server Error.
402
Error: Payment required.
413
Error: Payload too large. (max. 10MB)
429
Error: Too many requests (limited to max. 60 API calls per minute. For higher limit please contact us.)
504
Error: Gateway Timeout

https://api.vectorizer.io/v4.0/vectorize

Advanced vectorization endpoint to covert raster images to scalable vector graphics. (Fragmentation part of url not required). Completion time depends on input image size, number of colors and structure but should never exceed 59 seconds.
  • Web
  • cURL
  • PHP
  • Java
  • Python
  • Node.js
# cURL HTTP POST using multipart form upload: 
 			
<?php

    // this example requires GuzzleHttp Client. for more information visit: https://docs.guzzlephp.org/en/stable/overview.html#installation
    require 'vendor/autoload.php';
    $client = new GuzzleHttp\Client();
    $res = $client->post('https://api.vectorizer.io/v4.0/vectorize', [
	    'multipart' => [
PARAMS
        ],
        'headers' => [
           'X-CREDITS-CODE' => 'YOUR_CREDITS_CODE_HERE',
        ]
    ]);
    $fp = fopen('exampleimage.svg', 'wb');
    fwrite($fp, $res->getBody());
    fclose($fp);

?>
Coming soon.
Coming soon.
Coming soon.
Try it out:

( no credits available. sign in to enable this button )
Request Body ( multipart/form-data )
image
byte[] 		Upload File:
Input image binary. Use PNG file format for best compatibility. Try to avoid uploading files larger than 1MB (max. 10MB) to prevent timeouts.
config
byte[] 		Upload File:
Advanced configuration in YAML format.
Example configuration: advanced-config-yaml-example-v4.0.7.yaml.
Responses

Use the HTTP status code of the response to implement your error handling. The HTTP body of the response is only for debugging purposes and can change without a version change.
For error status codes indicating a server problem (500, 504) it is highly recommended to implement a exponential backoff for retries in your software.

Status Code Description
200
Output format depends on format argument.

HTTP response headers:
X-CREDITS-AVAILABLE Number of available credits before starting the vectorization operation. This number does not include the one credit that will be charged for a successful download. [this header requires authentication using X-CREDITS-CODE header]
X-CREDITS-EXPIRE Credits valid until this date (RFC7231 format). [this header requires authentication using X-CREDITS-CODE header]
X-FREE-CREDITS-AVAILABLE Free credits available. [this header is only available if not authenticated using X-CREDITS-CODE header]
500
Error: Internal Server Error.
402
Error: Payment required.
413
Error: Payload too large. (max. 10MB)
429
Error: Too many requests (limited to max. 60 API calls per minute. For higher limit please contact us.)
504
Error: Gateway Timeout