# Shapesoda

> Shapesoda turns raster images (PNG, JPEG, WebP, BMP, GIF, TIFF) into clean vectors: SVG, PDF, EPS, DXF or a re-rendered PNG. One credit per image covers every format requested in that call. Three ways in: an MCP server for AI agents, the `shapesoda` CLI for files and folders, and a REST API. Presets tune the result for web, print, vinyl cutting, laser and embroidery.

Base URL: `https://shapesoda.com`. REST: `POST /v1/vectorize`. MCP: `POST https://shapesoda.com/mcp` (Streamable HTTP, stateless, JSON responses).

## Which interface to use

- **MCP**: you are an agent or a chat (ChatGPT, Claude, Cursor, Claude Code) with the Shapesoda MCP server connected and need one or a few images. Tools: `vectorize` (`image` = a file attached to the ChatGPT message, `upload_id` or `image_base64` up to 2 MB), `create_upload` (one-time upload link, 10 min), `open_editor` (opens the Shapesoda window where the user picks the file: Claude does not pass attachments to apps), `get_usage`, `vectorize_url` (public image URL; listed only when enabled). `revectorize` is used only by the Shapesoda window: other settings for the same image, free for 24 hours. Results come back as links valid for 24 hours.
- **CLI**: you have a shell and local files, especially a folder. `npx shapesoda ./in ./out --preset cut --format svg,dxf` keeps subfolders, skips up-to-date files, runs 4 requests in parallel and retries `429`/`503` using `Retry-After`. `shapesoda account` shows credits. Node 18+, no dependencies; single binaries also exist.
- **Python SDK**: `pip install shapesoda` → `Shapesoda(key).vectorize_file("logo.png", formats=["svg","pdf"], preset="print")`; `preview_file()` / `upgrade()`; retries built in. **JavaScript/TypeScript SDK**: `npm install @shapesoda/sdk` → `new Shapesoda(key).vectorizeFile("logo.png", { formats: ["svg","pdf"] })`; `previewFile()` / `upgrade()`. Other languages: generated clients in the repository (`clients/sdk`), registry publishing in progress.
- **REST**: you are writing application code. Send image bytes as the body (options in the query) or `multipart/form-data` with field `image`. One format returns the file itself; several formats or `Accept: application/json` return JSON with links.

## Auth

- API key `ssk_…`: sign in at https://shapesoda.com, account menu, API keys, New key. Shown once.
- Header `Authorization: Bearer <key>` for REST (`/v1/vectorize`, `/v1/account`) and MCP. Result downloads (`/v1/results/{id}`) use the result token instead: send `Authorization: Bearer <result_token>`; `?token=` also works but can leak into access logs, browser history and analytics. `GET /v1/plans` (prices) is public. The CLI reads `SHAPESODA_API_KEY` (or `--api-key`).
- Never print, log or commit the key, and never call the API from a browser or mobile app with it. Result links contain a secret token: treat them as private.
- MCP also accepts a Shapesoda account connected through OAuth 2.1 (sign-in with Google or an email code, then Allow): ChatGPT, Claude, Cursor and Claude Code offer it themselves when the server is added without a key. The API key header still works for agents and scripts.

## Connect MCP

Server URL: `https://shapesoda.com/mcp` (Streamable HTTP).

- **ChatGPT**: Settings → Apps → find Shapesoda (or add the server URL as a custom connector in developer mode). Attach an image and write `@Shapesoda` or "make it SVG": ChatGPT asks to share the file, then the Shapesoda window shows the result.
- **Claude** (claude.ai, Desktop): Settings → Connectors → Shapesoda (or "Add custom connector" with the server URL). Ask to vectorize an image: the Shapesoda window opens and the user picks the file there.
- **Cursor**: install the Shapesoda plugin from the marketplace, or add `{"mcpServers":{"shapesoda":{"url":"https://shapesoda.com/mcp"}}}` to `.cursor/mcp.json`.
- **Claude Code**: `claude mcp add --transport http shapesoda https://shapesoda.com/mcp`, then `/mcp` → shapesoda → Authenticate to connect the account. With a key instead: `claude mcp add --transport http shapesoda https://shapesoda.com/mcp --header "Authorization: Bearer $SHAPESODA_API_KEY"`.

## Presets

Explicit options always win over the preset. Default is `web`.

| preset | default format | what it does | use for |
|---|---|---|---|
| `web` | svg | automatic colors, shapes stacked | websites, apps, Figma, logos |
| `print` | pdf | shapes cut out of each other, no overlaps | print shops, posters, documents |
| `cut` | svg | 8 colors, cut out and grouped by color | vinyl cutters, stickers, Cricut, Silhouette |
| `laser` | svg | 2 colors, outlines only (`draw=stroke`) | laser cutting and engraving; add `dxf` for CAD |
| `embroidery` | svg | 12 colors, cut out, tiny specks dropped | embroidery digitizing |

Other options: `colors` (`auto`, `unlimited`, 2–32), `max_colors` (2–256), `palette` (2–256 `#rrggbb`, not with `colors`), `draw` (`fill`, `stroke`, `stroke_edges`), `layers` (`stacked`, `cutouts`, `cutouts_grouped`), `image_type` (`auto`, `artwork`, `artwork_sharp`, `photo`), `quality` (`auto`, `high`, `medium`, `low`), `detail` (`auto`, `low`, `medium`, `high`), `width` or `height` with `unit` (`px`, `pt`, `mm`, `cm`, `in`; up to 10 m).

Fine-tuning knobs exist beyond the presets; a preset only sets defaults and every explicit option wins: processing (`palette_tolerance`, `min_area`, `max_pixels`, `curve_tolerance`, `smoothness`, `corners`, `denoise`), grouping and curves (`group_by`, `curves`), stroke (`stroke_width`, `stroke_color`, `stroke_scaling`), gap filler (`gap_filler`, `gap_filler_width`), size (`aspect`, `align_x`, `align_y`, `scale`, `dpi`) and format-specific output (`svg_version`, `svg_fixed_size`, `adobe_compat`, `dxf_curves`, `png_antialias`). Full table with ranges and combination rules: https://shapesoda.com/api#parameters

## Formats

- `svg`: web, Figma, Illustrator, Cricut Design Space.
- `pdf`: print, documents (page size from width/height).
- `eps`: print RIPs, CorelDRAW.
- `dxf`: CAD, laser and CNC (curves become polylines, units in `$INSUNITS`).
- `png`: clean re-render at any size (mm/in at 300 DPI, max 4.2 MP).
- Several at once: `format=svg,pdf,dxf` (REST, CLI) or `format: ["svg","pdf"]` (MCP). Still 1 credit.

## Test mode

- `mode=test` (REST, MCP) or `--test` (CLI): free, no credits needed, same response shape, result is watermarked.
- 100 test calls per key and 100 per account per UTC day, then `429 test_limit`.
- Not available in test mode: `retention_days` and `image_url` / `vectorize_url` (`400 bad_request`). A stored test result (several formats, `retain=true`) lives 1 hour. Use it while building or debugging, then switch to live.

## Preview mode

- `mode=preview` (REST, MCP): free, no credits needed. Returns a PNG up to 1 MP without vectors (only `format=png`), plus a result link valid 24 hours. 200 previews per account per UTC day, then `429 preview_limit`.
- To get the vectors, open the same result link with `format=svg` (or `pdf`, `eps`, `dxf`) instead of `format=png`: `GET /v1/results/{id}?format=svg` with the result token. That costs 1 credit once (`format=png&upgrade=true` for the full-size PNG); afterwards every format of the result is free. Not available with `image_url` / `vectorize_url`.

## Free MCP vectorizations

- MCP only (not REST, not the website): the first 10 live vectorizations per account per UTC day are free, before credits (`credits_charged: 0`, `free_remaining_today` in the result and in `get_usage`). Then 1 credit each. The account can be connected through OAuth or an API key.
- Without an account the MCP server still works: 3 free vectorizations per person per UTC day (ChatGPT: per `openai/subject`; Claude: per MCP session; other clients: per IP), all formats, results kept 24 hours. Test mode, preview, `retention_days` and `vectorize_url` need an account. When the 3 are used, the chat offers to connect a Shapesoda account (free) and the result links to https://shapesoda.com/pricing.
- A personal plan (the website subscription) is unlimited in chats when the account is connected through OAuth, with the same hidden daily cap against scripts as on the website. With an API key, MCP calls use credits as before.
- Changing settings of the same image in the Shapesoda window (`revectorize`) is free for 24 hours after the first vectorization, up to 30 changes a day: one image is charged once.
- No payments happen inside chats; prices and checkout are on the website.

## Free repeats

- Exactly the same request (same bytes, same parameters) within 24 hours: free, safe to retry.
- The same image with other options or formats within 30 days after it was paid: free, up to 20 per image per day.
- Free responses carry `X-Credits-Charged: 0` (REST) or `credits_charged: 0` (MCP, JSON). A resized or re-saved file is a new image.
- Without `format`, a result link returns the first format of the request, in the order of your `format` list (the preset's format if none was given). To get another format of a stored result, use `GET /v1/results/{id}?format=…` with the result token (free) or `shapesoda result get <id> --format png`. `DELETE /v1/results/{id}` with the token removes it early.

## Result links (24 hours, up to 30 days)

- `retention_days=N` (1–30, live mode only, free) keeps the result N days instead of 24 hours and stores it even for a single format (CLI: `--retention-days N`).
- Stored only when needed: several formats, JSON response, `retain=true`, `retention_days`, `mode=preview`, and every MCP call (an SVG-only MCP call may come back without a link when storage is full: `result_id` and `download_url` are then empty). A single-format REST call stores nothing.
- Stored encrypted for 24 hours with a key derived from the result token; anyone with the link and token can download. `DELETE /v1/results/{id}` removes it earlier.

## Limits

- Input: 10 MB (`413 too_large`), PNG/JPEG/WebP/BMP/GIF (first frame)/TIFF (first page) (`415 unsupported_format`), up to 40 MP (`422 too_many_pixels`); larger than 4.2 MP or 4096 px is downscaled automatically (`X-Input-Scale`). About 2000 px on the long side is enough.
- Rate: 60 requests per minute per key, bursts of 10; at most 5 concurrent requests per account (more → 429 rate_limited, Retry-After: 2, not charged — send up to 5 in parallel); 5,000 images per key per day; 100 test calls per day; 200 previews per account per day.
- MCP uploads: one file, 10 minutes. Inline `image_base64`: 2 MB.

## Errors worth branching on

Body: `{"error": {"code", "message", "request_id"}}`.

- `400 bad_request`: fix the parameters, don't retry as is.
- `401 unauthorized`: missing or revoked key.
- `402 no_credits` / `402 spend_limit`: stop, tell the user to buy credits or raise the spending limit. Don't retry.
- `413 too_large`, `415 unsupported_format`, `422 invalid_image` / `too_many_pixels`: fix or convert the input, don't retry.
- `429 rate_limited`: wait `Retry-After` seconds (always whole seconds), retry; a rejected request does not use up a rate-limit token. `429 daily_limit` / `test_limit` / `preview_limit`: wait until 00:00 UTC (`Retry-After`), or use live mode for `test_limit`.
- `503 busy` / `timeout` / `storage_full`: retry after `Retry-After`. Failed requests are never charged.

## Docs

- [API reference](https://shapesoda.com/api): parameters, responses, errors, code samples in several languages, MCP setup.
- [OpenAPI 3.1 spec](https://shapesoda.com/openapi.json): machine-readable, for generating clients.
- [Agent skill](https://shapesoda.com/skill/SKILL.md): Claude Code skill with recipes; install with `npx shapesoda install-skill`.
- [MCP endpoint](https://shapesoda.com/mcp): a connected account (OAuth) or `Authorization: Bearer <key>`; optional: 3 free a day without either.

## Optional

- [Pricing](https://shapesoda.com/#pricing): monthly credits, shared with the website; unused credits roll over up to 5 months’ worth while the plan is active.
- [Privacy](https://shapesoda.com/privacy)