Developers: the Rasterless API and MCP server
Call the same converter from a script or an agent with one bearer key.
Works with your favourite agents
Everything the converter on this site does is available over HTTP: one image in, the formats you ask for out, with the same options and the same limits. An agent that speaks the Model Context Protocol can call it as a tool through the remote MCP server, with the same key.
The tables on this page are generated from the code that answers the requests, so an option name or a limit cannot drift from what the server accepts. Values that are not settled yet are marked as such instead of being guessed.
Quickstart
First, sign in with Google and create an API key in the panel that follows. Keys start with rl_live_ and are shown once. Keep the key out of source control; the examples read it from an environment variable called RASTERLESS_API_KEY.
Your API keys
Sign in with Google on this page to create and manage your API keys. The panel needs JavaScript.
Copy this key now. It is shown only once: we keep only a keyed hash of it, plus its first four and last four characters so you can recognise it in the list.
Up to 2 active keys per account.
| Key | Created | Last used | This hour | Today | Action |
|---|
Your first call
1. Put the key in an environment variable. Replace the placeholder with your key. The variable holds until you close that terminal window.
export RASTERLESS_API_KEY='YOUR_API_KEY'
$env:RASTERLESS_API_KEY = 'YOUR_API_KEY'
2. Check the key. GET /v1/account answers with the key and its remaining quota, and does not count as a conversion. A 401 api_key_invalid usually means part of the key was lost when copying it.
curl -sS https://api.rasterless.com/v1/account \
-H "Authorization: Bearer $RASTERLESS_API_KEY"
curl.exe -sS https://api.rasterless.com/v1/account `
-H "Authorization: Bearer $env:RASTERLESS_API_KEY"
3. Convert a file from your computer. The part after @ is the path of the image; ./logo.png is a file called logo.png in the folder the terminal is in. In PowerShell, type curl.exe: in Windows PowerShell, curl on its own starts a different command. curl.exe comes with Windows 10 from build 17063.
curl -X POST https://api.rasterless.com/v1/vectorize \
-H "Authorization: Bearer $RASTERLESS_API_KEY" \
-F image=@./logo.png \
-F formats=svg,dxf \
-F colors=auto
curl.exe -X POST https://api.rasterless.com/v1/vectorize `
-H "Authorization: Bearer $env:RASTERLESS_API_KEY" `
-F "image=@./logo.png" `
-F "formats=svg,dxf" `
-F "colors=auto"
4. Read the answer. This example has the fields and types of a real response; the values come from a test conversion and the download links are illustrative:
{
"id": "d23ed01b4e504118855e620297706bbb",
"colors_used": 4,
"seconds": 2.61,
"outputs": {
"svg": "https://storage.googleapis.com/…/output.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&…",
"dxf": "https://storage.googleapis.com/…/output.dxf?X-Goog-Algorithm=GOOG4-RSA-SHA256&…"
},
"expires_in": 3600,
"preview_url": "https://storage.googleapis.com/…/output_preview.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&…",
"colors_auto": {
"detected": true,
"regime": "A",
"margin": 11590.0
},
"shapes": 5
}
The answer is JSON: outputs holds a signed download link for each format you asked for, and colors_used the colour count the engine used. Links expire after 1 hour, so fetch the files when the response arrives rather than storing the links. Ask for a single format and add ?return=file to the address to receive the file itself instead of JSON.
id names the job and seconds is how long the conversion took. shapes counts the shapes in the result, preview_url is a PNG preview with the same lifetime as the links, and colors_auto.detected says whether colors=auto found the count in the image or used the default.
Authentication
Every request carries the key in an Authorization: Bearer header over HTTPS. The API sets no cookie and shows no browser check: the key is the whole identity, so treat it like a password and keep calls on your server. A key in browser code or in a mobile app is a key anyone can read. A request without a key returns 401 api_key_missing, a wrong key 401 api_key_invalid, and a revoked key 401 api_key_revoked. Revoking takes effect on the next request, and each account can hold a limited number of active keys at a time.
If we suspend or revoke one of your keys under the terms of service, it shows as revoked in your key list, and we write to the email address of your Google account.
Endpoints and parameters
| Endpoint | Description |
|---|---|
POST /v1/vectorize |
Converts one image and returns a signed link per format. |
GET /v1/options |
Lists the accepted value of every option. |
GET /v1/account |
Shows the key's quota and how much of it is left. |
POST /v1/vectorize takes multipart/form-data: the image in a field called image and the options as ordinary form fields. The values are the axes that GET /v1/options returns, and the table is built from the same constants, so it cannot disagree with the server.
| Parameter | Values | Default | Description |
|---|---|---|---|
image required |
PNG, JPEG, WEBP, BMP, GIF, AVIF | — | The image, as a multipart file field. Its first bytes decide the type, not the file name. |
formats |
svg, pdf, eps, dxf, png | svg | One or more, separated by commas; the answer holds one link per format. |
colors |
2–64, auto | auto | Palette size; 2 gives a black-and-white trace. auto reads the count from a flat-colour graphic and falls back to 26. |
svg_version |
svg_1_0, svg_1_1, svg_tiny_1_2 | svg_1_1 | The version written on the SVG root element. |
draw_style |
fill_shapes, stroke_shapes, stroke_edges | fill_shapes | Filled shapes, outlined shapes or edges only. In a DXF the first two give the same closed outlines; edges only gives open paths. |
shape_stacking |
cutouts, stacked | cutouts | Cut-outs punch holes in the shapes underneath; stacked paints them over each other. |
group_by |
none, color, parent, layer | none | SVG grouping only: none, by colour, by parent shape or by layer. |
size_mm |
WxH, 1–5000 mm | — | Physical size such as 150x150. Applies to SVG, PDF, EPS and DXF; leave it empty to keep pixel units. |
denoise |
0–50 | 0 | Strength of an edge-preserving pre-filter; 0 turns it off. Not available in the MCP tool. |
group_by changes only how an SVG groups its paths. In a DXF, fill_shapes and stroke_shapes write the same closed outlines (LWPOLYLINE and degree-3 SPLINE) on one FILL_ layer per colour; stroke_edges writes the edge network instead, each boundary once as an open path, on EDGE_ layers. The DXF is written as R2010 (AC1024) with millimetre units.
Errors
An error returns JSON under error: a code, a type that groups codes into families (bad_input, auth, quota, too_complex, timeout, busy, not_found, server), the values behind it in params and a fallback message in English. Branch on type, log code, and never parse the message text. A typical body is {"error": {"code": "file_too_large", "type": "bad_input", "params": {"max_mb": 25}}} with the message next to it.
A change to /v1 that would break a request that works today is announced on this page at least 30 days before it takes effect. Additions that leave working requests as they are, such as a new optional field, can appear without notice.
| HTTP | Code | Meaning |
|---|---|---|
| 400 | image_missing |
No file in the image field. |
| 400 | multipart_invalid |
The body could not be read as multipart/form-data. |
| 400 | unsupported_input |
The file extension is not an accepted input. |
| 400 | not_an_image |
The first bytes of the file are not an accepted raster image. |
| 400 | invalid_option |
An option has a value outside its list; params names it. |
| 400 | size_mm_format |
size_mm is not written as WxH, for example 150x150. |
| 400 | size_mm_range |
A side of size_mm is outside the accepted range. |
| 400 | return_needs_one_format |
?return=file was asked for with more than one format. |
| 401 | api_key_missing |
No key in the Authorization header. |
| 401 | api_key_invalid |
The key is not valid. |
| 401 | api_key_revoked |
The key was revoked; create a new one. |
| 403 | key_suspended |
A key on the account is suspended, so no new key can be created. |
| 409 | key_limit |
The account already has its maximum number of active keys. |
| 413 | file_too_large |
The upload is over the file size limit. |
| 413 | image_too_large |
The decoded image is over the pixel limit. |
| 422 | too_complex |
The job did not start: its estimate is over the time budget, or (image_bound false) the server had too little time left for this request. A lower colour count is suggested if one passes. |
| 422 | timeout |
The conversion ran past its time budget; fewer colours would not help, a smaller image can. |
| 429 | busy |
Every worker is busy; retry after the Retry-After header. |
| 429 | quota_hourly |
The key has used its hourly quota. |
| 429 | quota_daily |
The key has used its daily quota. |
| 429 | quota_url_fetch |
The key has used its hourly image_url fetches (MCP tool). |
| 429 | quota_requests |
The key has sent its hourly number of conversion requests, whatever their outcome; retry after the Retry-After header. |
| 429 | key_create_limit |
The account has used its new-key allowance for the last 24 hours; retry after the Retry-After header. |
On 429 busy, wait for the time in the Retry-After header and send the request again.
On 422 too_complex, the conversion did not start, and error.image_bound says why. When it is true, the image is over the limit on its own. If error.suggested_n_colors is then a number, it is a lower colour count whose estimate we checked against the limits a new request faces, usually the largest that passes, so a retry with that count passes this check. It is an estimate, not a promise: the retry can still end in timeout. If it is null and fewer_colors_help is false, the estimate stays over the limit even at 2 colours; fewer colours will not help, but a smaller image might. If both are null, no suggestion could be worked out.
When image_bound is false, the server ran short of time for this request, not because of the image: suggested_n_colors and fewer_colors_help are both null, and the same request can be sent again in a moment.
On 422 timeout, the conversion started and ran past its time budget. The colour count barely changes how long a conversion takes, so the body suggests no colour count: suggested_n_colors is null and fewer_colors_help is false. A smaller image helps only below 1.5 megapixels, because larger images are traced at that size anyway; try about half that (e.g. 1000 × 750 px), or reduce noise and texture. image_bound appears only with too_complex.
A timeout gives the conversion back to the key's quota (quota_refunded: true) once per image per hour, and at most 2 times per key in each clock hour; past that, the body says quota_refunded: false.
Rarely, a conversion overruns its budget and the connection closes at about 100 seconds with HTTP 524 and no JSON body; treat it like a timeout.
Limits and quota
| Limit | Value |
|---|---|
| Conversions per key, per hour | 20 |
| Conversions per key, per day | 100 |
| Active keys per account | 2 |
| New keys per account per 24 hours, after the first 2 | 1 |
| MCP image_url fetches per key, per hour | 120 |
| Conversion requests per key, per hour (API and MCP) | 200 |
| File size | 25 MB |
| Decoded image size | 40 MP |
| Time budget per conversion | 90 s |
| Download link lifetime | 1 h |
| size_mm, per side | 1–5000 mm |
The fetch row counts each time the MCP tool vectorize_image downloads an image_url. The count is taken before the download starts, so a download that fails or returns something other than an image counts too. It is separate from the conversion quota.
Images above 1.5 megapixels are downscaled before tracing, so the pixel size of the output follows the downscaled copy; set size_mm when you need physical dimensions. One image per request.
Pricing
API keys, and the conversions you run with them within the quota above, are free during the beta. Nothing will be charged without your clear agreement first (terms of service, section 4).
MCP server
The MCP server lets an agent call the converter as a tool. It speaks Streamable HTTP at https://api.rasterless.com/mcp and takes the same bearer key in the same header. It offers two tools: vectorize_image converts one image, given either as image_url (a public https address) or as image_base64, with the options in the parameter table; get_options returns the accepted values and the key's remaining quota so the agent can choose. Pick your client for the setup:
Claude Code
The command stores the key in your user settings. The .mcp.json form reads it from the environment, so the file can be committed. A long conversion can outlast the default tool timeout; MCP_TOOL_TIMEOUT=120000 raises it.
claude mcp add --transport http rasterless https://api.rasterless.com/mcp \
--header "Authorization: Bearer $RASTERLESS_API_KEY"
{
"mcpServers": {
"rasterless": {
"type": "http",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" }
}
}
}
Claude Desktopnot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Request headers on custom connectors are in beta and only some organisations have them. If the Request headers section is missing, this client cannot send the key yet. The connector is shared by everyone in the organisation, with one key.
URL https://api.rasterless.com/mcp
Authentication none (the request header carries the key)
Request header authorization: Bearer rl_live_…
Cursornot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Cursor reads the key from the environment variable, so the file holds no secret.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${env:RASTERLESS_API_KEY}" }
}
}
}
Visual Studio Codenot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
The first file is the current format. The older .vscode/mcp.json asks for the key and keeps it out of the file; it still works but is being retired.
{
"mcpServers": {
"rasterless": {
"type": "http",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" },
"tools": ["*"]
}
}
}
{
"inputs": [
{ "type": "promptString", "id": "rasterless-key",
"description": "API key", "password": true }
],
"servers": {
"rasterless": {
"type": "http",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${input:rasterless-key}" }
}
}
}
Windsurfnot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Windsurf's agent settings now live under Devin Desktop. The .local.json file is kept out of version control.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"transport": "http",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Codex CLInot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Codex sends the variable's value as the bearer token; the file itself holds no secret.
[mcp_servers.rasterless]
url = "https://api.rasterless.com/mcp"
bearer_token_env_var = "RASTERLESS_API_KEY"
Gemini CLInot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Use httpUrl: in this file, url means the older SSE transport.
{
"mcpServers": {
"rasterless": {
"httpUrl": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Zednot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Without an Authorization header Zed starts a sign-in flow instead, so keep the header in place.
{
"context_servers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Clinenot tested yet
We have not yet tried this setup against the live server with a real key; it follows the client's own documentation.
Keep type set to streamableHttp; without it Cline falls back to the older SSE transport.
{
"mcpServers": {
"rasterless": {
"type": "streamableHttp",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
A configuration file holds the key in plain text unless the client can read it from an environment variable. Where a client documents that, the snippet uses it; otherwise keep the file out of version control.
The MCP tool cannot open a file on your computer: it takes a public https address or the file's bytes as base64. To convert a file on your disk from a script, use the curl command from the quickstart.
What the API does not do
- One image per request. There is no endpoint that takes a folder or an archive of images.
- No webhooks and no job queue: the request returns when the conversion is done or has run out of its time budget, which is 90 seconds here and 300 seconds on the site, so heavier images are better converted on the site.
- No SDK. Any HTTP client that can send
multipart/form-dataworks. - Inputs are PNG, JPEG, WEBP, BMP, GIF or AVIF. SVG, PDF, TIFF and HEIC files are not accepted, and the outputs are SVG, PDF, EPS, DXF and PNG.
- No editing after the trace: the API returns files, not an editable drawing.
Questions
Is the output the same as on the website?
Yes. The API runs the same engine with the same options as the converter on this site, so the same image with the same settings gives the same files. Only the time budget differs: 90 seconds per API or MCP conversion against 300 seconds on the site, because the API returns a single response at the end; heavier images are better converted on the site.
Can I call the API from a web page?
Keep the calls on your server. A key placed in browser code can be read by anyone who opens the page, and every conversion made with it counts against your quota.
Which agents can use the MCP server?
Any MCP client that can connect to a remote server over Streamable HTTP and send an Authorization header. The setup section lists the clients we checked against their own documentation, with the configuration each one expects.
What happens to the images I send?
The same as on the site: download links expire after 1 hour, and uploaded images and generated files are removed by an automatic 1-day deletion rule. They are not used for anything else.
What if a conversion is too heavy?
It does not run past its time budget. You get a 422 instead of a file. When the body suggests a lower colour count, send the request again with that count. When image_bound is false, the server was short of time rather than the image too heavy: send the same request again in a moment. Otherwise, try a smaller image.