Developer documentation

SVG AI API & MCP Server

Use SVG AI from your own code or from AI assistants. Two capabilities: generate designs a new SVG from a text brief, an image, or both; vectorize traces an existing image into SVG paths.

Three ways to use it

Pick whichever matches how you work. REST uses an API key; MCP supports OAuth or an API key. Both use your SVG AI account and credit balance.

The console has a Copy setup message button: paste that one message into your assistant and follow its connection steps. Checking your balance confirms authentication without generating an image. You can also use the manual commands below.

Generate vs. vectorize

Use vectorize to trace the shapes and colors in an existing image. Use generate for a new design or a reinterpretation of a reference. Inspect traced edges, small details and colors before using the result.

Classic is fast and great for icons and simpler designs. Ultra renders more detail and handles text-heavy logos and complex briefs better. Generations made through the API also appear in your SVG AI dashboard.

Authentication

There are two ways to authenticate: OAuth 2.1 for MCP clients (recommended — no key handling at all) and API keys for the REST API or any client where you prefer a header.

OAuth 2.1 (MCP clients)

Add https://www.svgai.org/api/mcp to Claude, ChatGPT, or any MCP client without credentials. The client discovers the flow automatically, your browser opens SVG AI's sign-in and consent screen, and tokens are issued behind the scenes — you never see or paste a secret. The server implements the current MCP authorization spec:

• Protected-resource metadata (RFC 9728) at /.well-known/oauth-protected-resource; authorization-server metadata (RFC 8414) at /.well-known/oauth-authorization-server. Unauthenticated calls to /api/mcp return 401 with a WWW-Authenticate: Bearer resource_metadata="…" challenge.
• Authorization-code flow with PKCE (S256 only) and dynamic client registration (RFC 7591) at POST /api/oauth/register.
• Access tokens are audience-bound (RFC 8707) and last 1 hour; refresh tokens last 60 days and rotate on every use — a replayed refresh token revokes the whole session.
• Connected apps are listed in the console and can be disconnected instantly.

API keys (REST, or manual MCP setup)

Create a key in the API & MCP console (Dashboard → API & MCP). The full key is shown once, at creation. Send it on every request:

Authorization: Bearer sk_svgai_...        # preferred
x-api-key: sk_svgai_...                   # alternative header

Keys can be revoked any time from the console. Rate limits: 20 generations and 30 vectorizations per minute per account.

POST /api/v1/generate

Create one or more SVGs from a prompt, an image, or both.

curl -X POST https://www.svgai.org/api/v1/generate \
  -H "Authorization: Bearer sk_svgai_..." \
  -H "Content-Type: application/json" \
  -d '{"prompt": "minimal fox logo, orange and white", "model": "classic"}'

Complete response example

Example response with sample identifiers, credit balances and a simple square SVG.

{
  "object": "svg.generation",
  "id": "6dce86db-468b-4bc9-b877-379a9c0894a1",
  "status": "completed",
  "model": "classic",
  "credits_used": 2,
  "credits_remaining": 18,
  "svgs": [
    {
      "design_id": "8acc61ce-59b4-4562-b67c-9e4a1ca55115",
      "status": "completed",
      "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\"><path fill=\"#ea580c\" d=\"M12 12h40v40H12z\"/></svg>"
    }
  ]
}

A failed generation refunds its credits automatically. If the request outlives the wait window, you receive HTTP 202 with status: "processing", a poll_url, and a matching Location response header. Polling still requires your API key. Use the existing generation's polling URL before retrying a request that may already have been accepted: creating a generation again can spend credits again.

GET /api/v1/generations/:id

Fetch the state and results of an earlier generation by its id, using the same account's API key. The response contains object, id, status, and svgs; it omits model, credit fields, and polling URL. Keep polling while the status is processing.

POST /api/v1/vectorize

Trace an existing image into SVG paths. Send image (base64) or image_url; images should be at least 256×256 pixels.

Backgrounds are not removed automatically — an opaque background becomes filled paths in the SVG. Pass remove_background: true to isolate the main subject on a transparent background before tracing (no extra credits). Inspect the returned SVG on your intended background. If background removal fails, the original image is traced instead and the response reports background_removed: false.

curl -X POST https://www.svgai.org/api/v1/vectorize \
  -H "Authorization: Bearer sk_svgai_..." \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/logo.png", "remove_background": true}'

Illustrative response

{
  "object": "svg.vectorization",
  "status": "completed",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\"><path fill=\"#ea580c\" d=\"M12 12h40v40H12z\"/></svg>",
  "background_removed": false,
  "credits_used": 1,
  "credits_remaining": 17
}

GET /api/v1/credits

Check this endpoint for current operation costs and api_access before generating or vectorizing. Website starter credits alone do not unlock API use. The example below uses sample account values.

{
  "object": "credit.balance",
  "credits_remaining": 148,
  "subscription_active": true,
  "api_access": true,
  "costs": { "generate_classic": 2, "generate_ultra": 4, "vectorize": 1 },
  "topup_url": "https://svgai.org/pricing"
}

Errors

REST handler errors contain { "error": { "type", "message" } } with a matching HTTP status. A failed generation can also include its generation fields alongside the error. MCP uses its own JSON-RPC error and tool-result formats.

Check authentication without spending credits

A request without an API key returns HTTP 401:

curl -i https://www.svgai.org/api/v1/credits

{
  "error": {
    "type": "authentication_error",
    "message": "Missing API key. Pass it as \"Authorization: Bearer sk_svgai_...\" (create keys at https://svgai.org/dashboard/api)."
  }
}

Request rate limits

Authenticated REST responses can include RateLimit-Policy and RateLimit. These describe the account's request limit, shared across its API keys; they count requests, not credits. The policy identifies its quota and window, while the observation gives remaining requests and a window hint in seconds.

Headers are omitted when no valid, unexpired limiter observation is available, including before authentication, during a limiter outage, or after a long generation outlives the observation. Concurrent requests can change availability. Follow Retry-After when a rate-limit error includes it. Retrying an accepted generation can create another charged request; use its polling URL to retrieve the result. The header syntax follows the IETF HTTPAPI RateLimit draft.

MCP server (for AI assistants)

The MCP server at https://www.svgai.org/api/mcp exposes three tools — generate_svg, vectorize_image, and get_credits — over streamable HTTP. Authenticate with OAuth (just add the URL — the sign-in happens in your browser) or with an API key header. Every setup below is one-click in the console.

The public server metadata describes the endpoint and its connection details in MCP Registry format. OAuth discovery is available at protected-resource metadata and authorization-server metadata. Tool calls remain authenticated, and generation and vectorization require paid access.

Claude Code

claude mcp add --transport http svgai https://www.svgai.org/api/mcp \
  --header "Authorization: Bearer sk_svgai_..."

Claude (claude.ai)

Settings → Connectors → Add custom connector → URL https://www.svgai.org/api/mcp — no key needed: Claude walks you through SVG AI's sign-in and consent screen (OAuth). Prefer a key? Add an Authorization header with value Bearer sk_svgai_… instead.

ChatGPT (developer mode)

Settings → Apps & Connectors → enable Developer mode → Create connector with the same URL — OAuth sign-in works here too, or use the Authorization header.

Cursor, Windsurf, VS Code & other MCP clients

{
  "mcpServers": {
    "svgai": {
      "url": "https://www.svgai.org/api/mcp",
      "headers": { "Authorization": "Bearer sk_svgai_..." }
    }
  }
}