How do I vectorize images from a script, an API or an AI agent over MCP?

Updated on 6 October 2026

Create an API key in your Homotope account, send the image to POST /api/v1/jobs (or to the vectorize_image tool of the MCP server at https://homotope.app/mcp), poll the job until its state is done, then fetch the SVG, PDF, EPS or DXF: it is server processing, always paid (Pro quota, then credits).

JPG · 400 × 400 px

Engine SVG

400 × 400 px compressed JPEG logo and the SVG produced by the engine, Logo preset alone, 5 colours, untouched: the JPEG artefacts are gone, the ring stays a circle and the star keeps its straight edges.

×6 detail: the tip of the orange band against the white rim: JPEG halo and blocks, clean SVG edge. Drag the slider to compare; hover over the image or hold your finger on it to move the magnifier.

Try it with your image Open this example in the workshop

With the REST API

In the workshop, “My account” then “API keys”: create a key. It is shown only once; keep it in a secrets manager.
Send a PNG or JPEG: POST /api/v1/jobs answers straight away with 202 and the job’s identifier.
Poll GET /api/v1/jobs/ID every 2 to 5 seconds until done, then download the SVG, or …/result?format=dxf (pdf, eps, separations).

curl -sS https://homotope.app/api/v1/jobs \
        -H "Authorization: Bearer $HOMOTOPE_API_KEY" \
        -F [email protected] \
        -F 'options={"preset":"logo"}'

      curl -sS https://homotope.app/api/v1/jobs/ID \
        -H "Authorization: Bearer $HOMOTOPE_API_KEY"

      curl -sS -o logo.svg https://homotope.app/api/v1/jobs/ID/svg \
        -H "Authorization: Bearer $HOMOTOPE_API_KEY"

Everything is described in the API documentation and the OpenAPI 3.1 document.

With an AI agent (MCP)

The MCP server lives at https://homotope.app/mcp, over Streamable HTTP, with the Authorization: Bearer header and your key. Tools: vectorize_image, get_job, get_svg, get_result, check_cut (“ready to cut?”) and list_vectorizations. Same entitlements and limits as the API.

What differs from the workshop

The image is uploaded: the API processes on the server, unlike the workshop.
Always paid: each job uses the month’s Pro quota, then a credit; there is no free trial through the API (a failed job is given back). Prices are on the Pricing page.
No synchronous response: the client polls.

To vectorize without uploading anything, stay in the workshop: see vectorize without uploading. There, with no key, tracing is free. Production exports (DXF, EPS, PDF, separations): 2 free per month with an account, unlimited with Pro; without Pro, 1 credit each beyond those 2.

For a cutting DXF, see image to DXF and convert an image to DXF for a laser.

Frequently asked questions

Does the API have a free trial?

No: the month’s trial jobs are reserved for the workshop. A free account can create a key, but its uploads are refused without Pro quota or credits.

Which formats come back?

SVG, PDF, EPS and DXF, plus per-colour separations; a fixed palette can be set when sending.

Where does the key go?

In the Authorization: Bearer header only, never in a URL or a code repository.

Guides and conversions

Try it with your image