Web Development

Convert Images to SVG with cURL: API Quickstart

ToSVG Team
10 min read

To convert an image to SVG with cURL, send a POST request with the file as a multipart field named image to the ToSVG endpoint, then read the SVG markup from the JSON response. This quickstart takes you from an API key to a saved .svg file, and covers the conversion options, authentication choices and the errors you are most likely to hit. If you need an image to SVG API for a script, a build step or a backend job, this is the shortest path.

  • Endpoint: POST https://tosvg.com/api/v1/convert/image-to-svg with the multipart field image.
  • Authenticate with an X-API-Key header, or with Authorization: Bearer.
  • The response is JSON: the SVG text is in data.svg, so extract it with jq rather than saving the raw response.
  • Limits depend on your plan, and a quota error returns HTTP 429 with a Retry-After header.

Get Your API Key and Send Your First Request

Get your ToSVG API key

You create API keys in your ToSVG dashboard, and every request to the conversion endpoint needs one. Sign in, open the API keys section, create a key and copy it somewhere safe.

Treat the key like a password. Put it in an environment variable instead of pasting it into commands, scripts or shared notes:

export TOSVG_API_KEY="YOUR_API_KEY"

Every example below reads $TOSVG_API_KEY, so you never type the key itself. If a key leaks, revoke it in the dashboard and create a new one. The guide to API key management best practices covers rotation and storage in more detail.

Your first request: convert an image to SVG with cURL

The first request needs only the key and a file. The -F flag makes cURL build a multipart form, and the @ prefix tells it to upload the file contents.

curl -sS -X POST https://tosvg.com/api/v1/convert/image-to-svg \
  -H "X-API-Key: $TOSVG_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]"

The accepted input formats are PNG, JPG/JPEG, WebP, GIF, BMP and TIFF, up to 10 MB per file. The API also reports a maximum dimension of 4096 x 4096 pixels, and the converter scales larger images down before tracing. You can read the format list yourself from the authenticated GET /api/v1/convert/supported-formats endpoint.

The -sS flags hide the progress meter but still print errors, which keeps the output readable. Sending Accept: application/json makes sure you get JSON back even when something fails.

Read the JSON Response and Save the SVG to a File

What the response contains

A successful conversion returns HTTP 200 and a JSON object with the SVG as a string. The shape looks like this, with the SVG shortened:

{
  "success": true,
  "data": {
    "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" ...>...</svg>",
    "file_size": 18234,
    "conversion_time": 1.42
  }
}

file_size is the length of the SVG string in bytes, and conversion_time is the processing time in seconds. The part you care about is data.svg. Failed requests return "success": false plus a message or an error object, which the error handling section below describes.

Save the SVG with jq

Because the SVG sits inside JSON, you must extract it before opening it in a browser or editor. Redirecting the raw response to logo.svg would give you a JSON document, not an image. The reliable approach is to save the response first and then pull out the field with jq:

curl -sS -X POST https://tosvg.com/api/v1/convert/image-to-svg \
  -H "X-API-Key: $TOSVG_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]" \
  -o response.json

jq -r '.data.svg' response.json > logo.svg

The -r flag prints the raw string, so escaped quotes and newlines become real characters. Open logo.svg in a browser to check it. Our guide on how to open SVG files lists other viewers and editors.

A safer script version

Saving the response first is deliberate. If you pipe straight into jq and the request failed, jq prints null and you overwrite your file with the word "null". This version captures the HTTP status and only writes the SVG on success:

status=$(curl -sS -o response.json -w "%{http_code}" \
  -X POST https://tosvg.com/api/v1/convert/image-to-svg \
  -H "X-API-Key: $TOSVG_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]")

if [ "$status" = "200" ]; then
  jq -r '.data.svg' response.json > logo.svg
  echo "Saved logo.svg"
else
  echo "Request failed with HTTP $status" >&2
  jq . response.json >&2
fi

If jq is not installed, your package manager almost certainly has it. Without it, you can pass the JSON to any language with a JSON parser, such as python3 -c with the json module.

Conversion Options and Authentication Header Alternatives

Color, curves and noise options

You tune the result by sending optional form fields named options[...], and each one has a validated range. Leave them out and the converter uses its defaults.

FieldAllowed valuesWhat it does
options[color_mode]color or bwFull-color or black-and-white output
options[mode]polygon or splineStraight segments or smooth curves
options[filter_speckle]Integer 0-20Drops specks smaller than this size
options[corner_threshold]Integer 0-180Angle at which a point counts as a corner
options[color_precision]Integer 1-10Fewer or more colors in the result

Here is a request for a clean logo: curves, a moderate speckle filter and a limited palette. Quote the field names so your shell does not treat the square brackets as a glob pattern.

curl -sS -X POST https://tosvg.com/api/v1/convert/image-to-svg \
  -H "X-API-Key: $TOSVG_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]" \
  -F "options[color_mode]=color" \
  -F "options[mode]=spline" \
  -F "options[filter_speckle]=4" \
  -F "options[corner_threshold]=60" \
  -F "options[color_precision]=6" \
  -o response.json

For a black-and-white signature or line drawing, use options[color_mode]=bw and raise filter_speckle to remove paper texture. For pixel art or geometric icons, options[mode]=polygon keeps hard edges. The troubleshooting article on conversion options helps when a setting seems to have no effect.

Not sure which values suit your image? Try them on the online PNG to SVG converter first, which offers the same controls with a live preview. For photos specifically, our guide to converting a photo to SVG explains what to expect.

Authentication header alternatives

The API accepts your key in the X-API-Key header or as a Bearer token in the Authorization header. X-API-Key is checked first, so it wins if you send both.

curl -sS -X POST https://tosvg.com/api/v1/convert/image-to-svg \
  -H "Authorization: Bearer $TOSVG_API_KEY" \
  -H "Accept: application/json" \
  -F "[email protected]" \
  -o response.json

The Bearer form is handy when your HTTP client or gateway already has a place for bearer tokens. The code also accepts an api_key query parameter, but avoid it: URLs end up in shell history, proxy logs and server logs. Stick with a header. The learn article on API authentication methods has the details.

Error Handling and Rate Limits

Error handling basics

Check the HTTP status code first, because each failure class has its own status and a JSON body that explains it. These are the ones the API code returns for this endpoint:

StatusMeaningWhat to do
401Missing, invalid, expired or inactive API keyCheck the header and the key in your dashboard
403The request IP is not allowed, or a key limit was reachedReview the key's IP restrictions and your account
422Validation failed, such as no file, an unsupported type or an option out of rangeRead the errors object and fix the request
400The image could not be processedRead the message and try another file
429Plan limit exceededWait for the Retry-After seconds, or upgrade
500Conversion failed on the serverRetry once; if it persists, try a different image

Authentication errors return an error object with a machine-readable code such as MISSING_API_KEY, INVALID_API_KEY, EXPIRED_API_KEY or INACTIVE_API_KEY. Validation errors return "message": "Validation failed" together with an errors object keyed by field, for example options.color_precision.

Do not retry 401, 403 or 422 responses automatically, because the same request will fail the same way. Retry 429 only after the wait time has passed. For a fuller list, see the article on common API errors and the API error codes reference.

Rate limits depend on your plan

Your request allowance depends on your plan, and the API enforces it per account. Check the ToSVG pricing page for what each plan includes instead of relying on numbers you saw elsewhere.

Successful responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, so you can watch your remaining quota. Add -i to a cURL command to print the response headers while you experiment. When you run out, the 429 response includes Retry-After and a retry_after value in the JSON, both in seconds. Our article on how rate limits work and are managed goes deeper.

When to Use the API vs the Web Converter

Use the web converter for one-off images and the API when the conversion has to happen without you clicking. Both produce SVGs from the same set of options, so the choice is about workflow, not quality.

  • Web converter: a single logo, trying settings with a preview, cropping or rotating first with the built-in editor. No signup is needed.
  • API with cURL: shell scripts, cron jobs, CI steps, quick tests of your key, or checking behavior before you write a client in another language.
  • Full application code: once you outgrow a shell script, move to a proper client with retries and concurrency control.

Complete endpoint references, including background removal and image resizing, live in the ToSVG API documentation. If the output files are heavier than you want, the SVG optimizer can shrink them afterward.

Frequently Asked Questions

How do I convert an image to SVG with cURL?

Send a multipart POST to https://tosvg.com/api/v1/convert/image-to-svg with your key in the X-API-Key header and the file in the image field. Then extract data.svg from the JSON response with jq and write it to a .svg file.

Why does my saved SVG file look like JSON?

You redirected the whole response to the file. The API wraps the SVG in JSON, so run jq -r '.data.svg' on the response to get the actual SVG markup.

Is the ToSVG API free?

Access and limits depend on your plan, so check the pricing page for the current options. The web converter, which needs no signup, is the quickest way to try the conversion itself.

What file types and sizes can I upload?

PNG, JPG/JPEG, WebP, GIF, BMP and TIFF files up to 10 MB each. Images larger than 4096 pixels on a side are scaled down by the converter, so downscale huge scans yourself if you want control over the result.

Can I convert several images in one request?

No. The endpoint takes one image per request. To convert a folder, loop over the files in a shell script or use a client library with a concurrency limit.

Ready to try it? Create a key in your dashboard and follow the ToSVG API documentation for every endpoint and option.