Rasterless

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.

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.

bash
export RASTERLESS_API_KEY='YOUR_API_KEY'
PowerShell
$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.

bash
curl -sS https://api.rasterless.com/v1/account \
  -H "Authorization: Bearer $RASTERLESS_API_KEY"
PowerShell
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.

bash
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
PowerShell
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:

Example response
{
  "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

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

Form fields of POST /v1/vectorize
ParameterValues DefaultDescription
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.

HTTPCodeMeaning
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

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

Terminal
claude mcp add --transport http rasterless https://api.rasterless.com/mcp \
  --header "Authorization: Bearer $RASTERLESS_API_KEY"
.mcp.json
{
  "mcpServers": {
    "rasterless": {
      "type": "http",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" }
    }
  }
}

Official setup documentation (Claude Code)

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.

Customize › Connectors › Add custom connector
URL             https://api.rasterless.com/mcp
Authentication  none (the request header carries the key)
Request header  authorization: Bearer rl_live_…

Official setup documentation (Claude Desktop)

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.

~/.cursor/mcp.json
{
  "mcpServers": {
    "rasterless": {
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${env:RASTERLESS_API_KEY}" }
    }
  }
}

Official setup documentation (Cursor)

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.

.mcp.json
{
  "mcpServers": {
    "rasterless": {
      "type": "http",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" },
      "tools": ["*"]
    }
  }
}
.vscode/mcp.json
{
  "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}" }
    }
  }
}

Official setup documentation (Visual Studio Code)

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.

.devin/mcp_config.local.json
{
  "mcpServers": {
    "rasterless": {
      "url": "https://api.rasterless.com/mcp",
      "transport": "http",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Official setup documentation (Windsurf)

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.

~/.codex/config.toml
[mcp_servers.rasterless]
url = "https://api.rasterless.com/mcp"
bearer_token_env_var = "RASTERLESS_API_KEY"

Official setup documentation (Codex CLI)

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.

~/.gemini/settings.json
{
  "mcpServers": {
    "rasterless": {
      "httpUrl": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Official setup documentation (Gemini CLI)

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.

settings.json
{
  "context_servers": {
    "rasterless": {
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Official setup documentation (Zed)

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.

cline_mcp_settings.json
{
  "mcpServers": {
    "rasterless": {
      "type": "streamableHttp",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Official setup documentation (Cline)

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

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.

Related pages