PerfectVector API for AI agents

This page is for AI coding agents and the people who use them. It puts what you need to write an integration in one place, and each section links to the guide with the details.

The PerfectVector API converts PNG, JPEG and WebP images into SVG files. You send an image with an API key, and you get the SVG back.

Using an AI assistant instead? See the MCP docs.

Before you start

• Base URL: https://api.perfectvector.com/v1
• An API key. Someone signed in to perfectvector.com creates it on the Developer API page of their account. An API key cannot manage keys.
• A server or a script. The API sends no CORS headers, so browsers block calls from web pages, and an API key in a web page would be public.

API keys

• Start with a test key. It runs the whole request at no cost: the key check, the file checks, the rate limits and the response shape work as they do in live mode.
• Send the key only in the Authorization header: Authorization: Bearer <key>. A key in the URL is ignored, and the request fails with 401 invalid_api_key.
• Keep the key out of your code. The examples read it from the PERFECTVECTOR_API_KEY environment variable.
• We show a key once, when it is created. An account can have up to 10 active keys, live and test together.
• GET /v1/account shows which key you are using, your API balance, prices and limits.

See Authentication and Test mode.

Endpoints

There is no endpoint that lists your conversions. Keep the id of each conversion you create.

• Requests: POST /v1/vectorizations takes multipart/form-data with the field image (required) and the field options (optional; leave it out in v1). No other fields. The other endpoints take no body.
• Responses: JSON, except the SVG itself. Errors are application/problem+json.
• IDs: vec_… for conversions, key_… for keys, req_… for requests. Times are RFC 3339 in UTC.
• Headers on every response: X-Request-ID and X-Credits-Charged.
• New fields: we may add fields to responses. Ignore fields you do not know.

A complete example

Convert logo.png with a test key. Send an Idempotency-Key with every POST, so a retry after a network error never converts or charges twice:

curl https://api.perfectvector.com/v1/vectorizations \
  -H "Authorization: Bearer $PERFECTVECTOR_API_KEY" \
  -H "Idempotency-Key: logo-0001" \
  -F image=@logo.png

When the conversion has finished, the answer is 201 Created:

HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/vectorizations/vec_6Jd2LpQ8sV1nX4cR7tY0aB
X-Credits-Charged: 0
X-Credits-Would-Charge: 1
X-Request-ID: req_4Tq8WmX2r9LcB0vZs7KpY1

{
  "id": "vec_6Jd2LpQ8sV1nX4cR7tY0aB",
  "object": "vectorization",
  "mode": "test",
  "status": "succeeded",
  "request_type": "single",
  "created_at": "2026-10-26T09:30:12Z",
  "completed_at": "2026-10-26T09:30:12Z",
  "input": { "filename": "logo.png", "width": 1024, "height": 1024, "bytes": 182311 },
  "results": [
    {
      "index": 0,
      "status": "succeeded",
      "options": {},
      "result": {
        "format": "svg",
        "url": "https://api.perfectvector.com/v1/vectorizations/vec_6Jd2LpQ8sV1nX4cR7tY0aB/results/0",
        "expires_at": "2026-10-27T09:30:12Z"
      },
      "error": null
    }
  ],
  "result_counts": { "total": 1, "succeeded": 1, "failed": 0, "pending": 0 },
  "credits_charged": 0,
  "deleted_at": null
}

Download the SVG with the same API key. -OJ saves it under the name the API gives it (logo.svg):

curl -OJ https://api.perfectvector.com/v1/vectorizations/vec_6Jd2LpQ8sV1nX4cR7tY0aB/result \
  -H "Authorization: Bearer $PERFECTVECTOR_API_KEY"

A test key returns a fixed sample SVG and charges nothing; X-Credits-Would-Charge shows what a live key would have paid. With a live key (pv_live_…) the same request converts your image and uses 1 API credit when it succeeds.

Handle every answer

• Waiting: POST /v1/vectorizations waits up to 120 seconds by default. Set your HTTP client's timeout above that, or send Prefer: wait=N (1 to 120 seconds) or Prefer: respond-async.
• The SVG in one call: send Accept: image/svg+xml. When the conversion succeeds within the wait, the 201 body is the SVG itself. Check the Content-Type header before you save the body.
• Retries: the same Idempotency-Key with the same image within 24 hours returns the same conversion, never charged twice. The same key with another image answers 409 idempotency_conflict. A key is 8 to 128 letters, digits, - and _.

Complete Python and Node.js programs that create, poll and save are in the Quickstart. See also Waiting and async, Idempotency and Results.

Prices

• A live request uses 1 API credit when its conversion succeeds. GET /v1/account shows the current price in pricing.credits_per_request.
• Free: failed and timed-out conversions; requests the API refuses, including 402, 429 and 503 answers; status checks, GET /v1/account and DELETE; downloading a result again while it is available; repeating a request with the same Idempotency-Key within 24 hours; every call with a test key.
• API credits are separate from the credits used on the website, and the two never convert into each other. They are bought as one-time packs on the Developer API page, with no subscription and no automatic top-up.
• There is no overdraft: when your available credits are lower than the price, POST /v1/vectorizations answers 402 insufficient_credits before any work starts.

The current API credit packs:

Lemon Squeezy, our Merchant of Record, may add tax at checkout. See Credits.

Limits

• Limits apply to the whole account, across all of its keys. Test keys have their own counters.
• One live conversion at a time. Send the next image when the first one has finished. Requests are not queued for you.
• On 429 and 503, wait the Retry-After seconds, then retry with the same Idempotency-Key.
• GET /v1/account returns your current limits in limits. If you need more, email contact@perfectvector.com.

See Limits.

Errors

Every error is RFC 9457 problem details, with Content-Type: application/problem+json. Branch on code, never on title or detail. Errors are never charged.

{
  "type": "https://perfectvector.com/docs/api/errors#insufficient_credits",
  "title": "Not enough API credits",
  "status": 402,
  "detail": "This request needs 1 API credit. Available: 0.",
  "code": "insufficient_credits",
  "request_id": "req_4Tq8WmX2r9LcB0vZs7KpY1",
  "credits_required": 1,
  "credits_available": 0
}

A failed conversion is not an error: it answers 201 or 200 with "status": "failed", and costs nothing.

A 403 or 429 whose body is not problem details comes from our network edge, not from the API. Slow down and retry later. See Errors for every code.

Privacy

From the API Privacy Notice: "Your images are never used to train AI models and never sold."

• Results stay available for 24 hours after the conversion completes. We delete images and results from storage within 48 hours.
• DELETE /v1/vectorizations/{id} deletes a conversion's image and SVG at once.
• With a test key, we check the image and then discard it.

Terms and support

• You accept the API Terms when you create your first key or buy credits for the first time.
• Questions: contact@perfectvector.com. Please include the request_id.