Convert Images to SVG with cURL: API Quickstart
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-svgwith the multipart fieldimage. - Authenticate with an
X-API-Keyheader, or withAuthorization: Bearer. - The response is JSON: the SVG text is in
data.svg, so extract it withjqrather than saving the raw response. - Limits depend on your plan, and a quota error returns HTTP 429 with a
Retry-Afterheader.
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.
| Field | Allowed values | What it does |
|---|---|---|
options[color_mode] | color or bw | Full-color or black-and-white output |
options[mode] | polygon or spline | Straight segments or smooth curves |
options[filter_speckle] | Integer 0-20 | Drops specks smaller than this size |
options[corner_threshold] | Integer 0-180 | Angle at which a point counts as a corner |
options[color_precision] | Integer 1-10 | Fewer 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:
| Status | Meaning | What to do |
|---|---|---|
| 401 | Missing, invalid, expired or inactive API key | Check the header and the key in your dashboard |
| 403 | The request IP is not allowed, or a key limit was reached | Review the key's IP restrictions and your account |
| 422 | Validation failed, such as no file, an unsupported type or an option out of range | Read the errors object and fix the request |
| 400 | The image could not be processed | Read the message and try another file |
| 429 | Plan limit exceeded | Wait for the Retry-After seconds, or upgrade |
| 500 | Conversion failed on the server | Retry 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.