API векторизации изображений

Быстрый старт#

Три шага до первого SVG. Базовый адрес — https://shapesoda.com, все запросы идут по HTTPS.

1. Получите ключ API

   Откройте в аккаунте страницу Ключи API (если попросит, войдите по почте или через Google) и выберите Новый ключ. Ключ начинается с ssk_ и показывается только один раз — сразу сохраните его в хранилище секретов. Новым аккаунтам дарим бесплатный кредит, чтобы попробовать.

   ТерминалКопировать

   export SHAPESODA_KEY="ssk_your_key_here"

2. Отправьте картинку

   Передайте байты изображения телом запроса, а параметры — в строке запроса:

   Тело запросаКопировать

   curl -sS "https://shapesoda.com/v1/vectorize?colors=auto" \
     -H "Authorization: Bearer $SHAPESODA_KEY" \
     --data-binary @logo.png \
     -D - -o logo.svg

   Или отправьте форму multipart/form-data: файл в поле image, параметры — обычными полями:

   MultipartКопировать

   curl -sS https://shapesoda.com/v1/vectorize \
     -H "Authorization: Bearer $SHAPESODA_KEY" \
     -F [email protected] \
     -F colors=8 \
     -F image_type=artwork \
     -D - -o logo.svg

3. Прочитайте ответ

   При успехе приходит 200, в теле — SVG (image/svg+xml). Ключ -D - выводит заголовки — по ним видно, сколько стоил запрос:

   Заголовки ответа

   HTTP/1.1 200 OK
   Content-Type: image/svg+xml; charset=utf-8
   Content-Disposition: inline; filename="vector.svg"
   X-Credits-Charged: 1
   X-Mode: live
   X-Credits-Remaining: 99
   X-Request-Id: req_4f1c2a9e0b7d4c3a8e21

   Заголовок	Значение
   X-Credits-Charged	Сколько кредитов списал запрос: 1 за успешную векторизацию (сколько бы ни было форматов), 0 в тестовом режиме и за бесплатные повторы. Неудачные запросы не списываются.
   X-Mode	live или test в тестовом режиме.
   X-Credits-Remaining	Сколько картинок можно обработать прямо сейчас (баланс плюс включённые кредиты, с учётом вашего лимита расходов).
   X-Request-Id	Уникальный номер запроса. Возвращается и при ошибках — укажите его, если пишете в поддержку.

Авторизация#

Запросы к аккаунту и векторизации (POST /v1/vectorize, GET /v1/account, /mcp) передают ключ API в заголовке:

Authorization: Bearer ssk_…

• Создавайте, просматривайте и отзывайте ключи на странице Ключи API в аккаунте (до 10 действующих ключей на аккаунт). Отзыв срабатывает сразу.
• Без ключа, с неверным или отозванным ключом приходит 401 unauthorized. Частые неудачные попытки с одного IP-адреса ограничиваются.
• Храните ключ в секрете и только на сервере. API не отдаёт заголовков CORS и не предназначен для вызова со страницы в браузере: никогда не вызывайте API из браузера или мобильного приложения с секретным ключом, не встраивайте его во фронтенд-код и не коммитьте. Если ключ утёк, отзовите его.
• Сохранённые результаты используют другой секрет. GET и DELETE /v1/results/{id} принимают токен результата, а не ключ API. Передавайте его как Authorization: Bearer <result_token> (рекомендуется). ?token= в адресе тоже принимается, но токен в URL может попасть в журналы доступа, историю браузера и аналитику — не используйте его там, где адреса логируются или пересылаются. См. Хранение результата.
• Одноразовые ссылки загрузки MCP несут собственный секрет и другой авторизации не требуют. GET /v1/plans открыт для всех.
• Все ключи аккаунта расходуют один баланс кредитов — тот же, что и на сайте.

Примеры кода#

Короткие примеры почти без зависимостей: превратить logo.png в logo.svg, получить несколько форматов с пресетом, показать ошибку API и вывести остаток кредитов. Выбранный язык запоминается для всей страницы.

Векторизация картинки#

# --fail-with-body: exit non-zero on HTTP errors (the JSON error is written to logo.svg)
curl -sS --fail-with-body "https://shapesoda.com/v1/vectorize?colors=auto&image_type=artwork" \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  --data-binary @logo.png \
  -D headers.txt -o logo.svg

grep -i x-credits-remaining headers.txt

// vectorize.mjs — Node.js 18+ (built-in fetch), no dependencies
import { readFile, writeFile } from "node:fs/promises";

const res = await fetch("https://shapesoda.com/v1/vectorize?colors=auto", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SHAPESODA_KEY}` },
  body: await readFile("logo.png"),
});

if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message} (${error.request_id})`);
}

await writeFile("logo.svg", await res.text());
console.log("Credits left:", res.headers.get("X-Credits-Remaining"));

# vectorize.py — pip install requests
import os
import requests

with open("logo.png", "rb") as f:
    r = requests.post(
        "https://shapesoda.com/v1/vectorize",
        headers={"Authorization": f"Bearer {os.environ['SHAPESODA_KEY']}"},
        files={"image": f},
        data={"colors": "auto"},
        timeout=120,
    )

if r.status_code != 200:
    e = r.json()["error"]
    raise SystemExit(f"{r.status_code} {e['code']}: {e['message']} ({e['request_id']})")

with open("logo.svg", "w", encoding="utf-8") as out:
    out.write(r.text)
print("Credits left:", r.headers["X-Credits-Remaining"])

<?php
// vectorize.php — PHP 8 with the curl extension
$remaining = null;
$ch = curl_init("https://shapesoda.com/v1/vectorize");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SHAPESODA_KEY")],
    CURLOPT_POSTFIELDS => ["image" => new CURLFile("logo.png"), "colors" => "auto"],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 120,
    CURLOPT_HEADERFUNCTION => function ($ch, $line) use (&$remaining) {
        if (stripos($line, "X-Credits-Remaining:") === 0) $remaining = trim(substr($line, 20));
        return strlen($line);
    },
]);
$body = curl_exec($ch);
if ($body === false) {
    fwrite(STDERR, "Network error: " . curl_error($ch) . PHP_EOL);
    exit(1);
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);

if ($status !== 200) {
    $e = json_decode($body, true)["error"];
    fwrite(STDERR, "$status {$e['code']}: {$e['message']} ({$e['request_id']})" . PHP_EOL);
    exit(1);
}

file_put_contents("logo.svg", $body);
echo "Credits left: $remaining", PHP_EOL;

// main.go — standard library only: go run main.go
package main

import (
	"bytes"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"time"
)

func main() {
	img, err := os.ReadFile("logo.png")
	if err != nil {
		log.Fatal(err)
	}
	req, err := http.NewRequest("POST", "https://shapesoda.com/v1/vectorize?colors=auto", bytes.NewReader(img))
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SHAPESODA_KEY"))

	client := &http.Client{Timeout: 120 * time.Second}
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("%d: %s", resp.StatusCode, body) // {"error":{"code","message","request_id"}}
	}
	if err := os.WriteFile("logo.svg", body, 0o644); err != nil {
		log.Fatal(err)
	}
	fmt.Println("Credits left:", resp.Header.Get("X-Credits-Remaining"))
}

Векторизация с пресетом#

Пресет print: PDF и SVG шириной 210 мм за один вызов и 1 кредит. Несколько форматов приходят в JSON, каждый файл скачивается по своей ссылке с токеном результата.

# preset=print, two formats in one call (1 credit) → JSON with a link per format (needs jq)
curl -sS --fail-with-body "https://shapesoda.com/v1/vectorize?preset=print&format=pdf,svg&width=210&unit=mm" \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  --data-binary @logo.png -o result.json

# download each file with the result token (not the API key)
TOKEN=$(jq -r .result_token result.json)
for f in pdf svg; do
  curl -sS --fail-with-body "$(jq -r .files.$f result.json)" \
    -H "Authorization: Bearer $TOKEN" -o "logo.$f"
done

// preset.mjs — Node.js 18+ (built-in fetch), no dependencies
import { readFile, writeFile } from "node:fs/promises";

const url = "https://shapesoda.com/v1/vectorize?preset=print&format=pdf,svg&width=210&unit=mm";
const res = await fetch(url, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SHAPESODA_KEY}` },
  body: await readFile("logo.png"),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${res.status} ${error.code}: ${error.message} (${error.request_id})`);
}

// several formats → JSON with a link per format, stored for 24 hours
const result = await res.json();
for (const [format, link] of Object.entries(result.files)) {
  const file = await fetch(link, { headers: { Authorization: `Bearer ${result.result_token}` } });
  if (!file.ok) throw new Error(`download ${format}: ${file.status}`);
  await writeFile(`logo.${format}`, Buffer.from(await file.arrayBuffer()));
}
console.log("Credits left:", result.credits_remaining);

# preset.py — pip install requests
import os
import requests

with open("logo.png", "rb") as f:
    r = requests.post(
        "https://shapesoda.com/v1/vectorize",
        headers={"Authorization": f"Bearer {os.environ['SHAPESODA_KEY']}"},
        files={"image": f},
        data={"preset": "print", "format": "pdf,svg", "width": "210", "unit": "mm"},
        timeout=120,
    )

if r.status_code != 200:
    e = r.json()["error"]
    raise SystemExit(f"{r.status_code} {e['code']}: {e['message']} ({e['request_id']})")

# several formats → JSON with a link per format, stored for 24 hours
result = r.json()
for fmt, link in result["files"].items():
    file = requests.get(link, headers={"Authorization": f"Bearer {result['result_token']}"}, timeout=120)
    file.raise_for_status()
    with open(f"logo.{fmt}", "wb") as out:
        out.write(file.content)
print("Credits left:", result["credits_remaining"])

<?php
// preset.php — PHP 8 with the curl extension
function http(string $url, array $opts): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, $opts + [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 120]);
    $body = curl_exec($ch);
    if ($body === false) throw new RuntimeException(curl_error($ch));
    return [curl_getinfo($ch, CURLINFO_RESPONSE_CODE), $body];
}

[$status, $body] = http("https://shapesoda.com/v1/vectorize", [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SHAPESODA_KEY")],
    CURLOPT_POSTFIELDS => ["image" => new CURLFile("logo.png"), "preset" => "print", "format" => "pdf,svg", "width" => "210", "unit" => "mm"],
]);
if ($status !== 200) {
    $e = json_decode($body, true)["error"];
    fwrite(STDERR, "$status {$e['code']}: {$e['message']} ({$e['request_id']})" . PHP_EOL);
    exit(1);
}

// several formats → JSON with a link per format, stored for 24 hours
$result = json_decode($body, true);
foreach ($result["files"] as $format => $link) {
    [$status, $file] = http($link, [CURLOPT_HTTPHEADER => ["Authorization: Bearer " . $result["result_token"]]]);
    if ($status !== 200) exit("download $format: $status" . PHP_EOL);
    file_put_contents("logo.$format", $file);
}
echo "Credits left: {$result['credits_remaining']}", PHP_EOL;

// main.go — standard library only: go run main.go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"time"
)

var client = &http.Client{Timeout: 120 * time.Second}

// do sends the request with a bearer token and returns the body of a 200 response.
func do(req *http.Request, token string) []byte {
	req.Header.Set("Authorization", "Bearer "+token)
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("%d: %s", resp.StatusCode, body) // {"error":{"code","message","request_id"}}
	}
	return body
}

func main() {
	img, err := os.ReadFile("logo.png")
	if err != nil {
		log.Fatal(err)
	}
	url := "https://shapesoda.com/v1/vectorize?preset=print&format=pdf,svg&width=210&unit=mm"
	req, err := http.NewRequest("POST", url, bytes.NewReader(img))
	if err != nil {
		log.Fatal(err)
	}

	// several formats → JSON with a link per format, stored for 24 hours
	var result struct {
		Token            string            `json:"result_token"`
		Files            map[string]string `json:"files"`
		CreditsRemaining int               `json:"credits_remaining"`
	}
	if err := json.Unmarshal(do(req, os.Getenv("SHAPESODA_KEY")), &result); err != nil {
		log.Fatal(err)
	}
	for format, link := range result.Files {
		get, err := http.NewRequest("GET", link, nil)
		if err != nil {
			log.Fatal(err)
		}
		if err := os.WriteFile("logo."+format, do(get, result.Token), 0o644); err != nil {
			log.Fatal(err)
		}
	}
	fmt.Println("Credits left:", result.CreditsRemaining)
}

Проверка баланса#

curl -sS https://shapesoda.com/v1/account \
  -H "Authorization: Bearer $SHAPESODA_KEY"

const res = await fetch("https://shapesoda.com/v1/account", {
  headers: { Authorization: `Bearer ${process.env.SHAPESODA_KEY}` },
});
const { credits } = await res.json();
console.log(`${credits.available} images available`);

import os
import requests

r = requests.get(
    "https://shapesoda.com/v1/account",
    headers={"Authorization": f"Bearer {os.environ['SHAPESODA_KEY']}"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["credits"]["available"], "images available")

<?php
$ch = curl_init("https://shapesoda.com/v1/account");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("SHAPESODA_KEY")],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
echo $data["credits"]["available"], " images available", PHP_EOL;

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://shapesoda.com/v1/account", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SHAPESODA_KEY"))
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	var out struct {
		Credits struct {
			Available int `json:"available"`
		} `json:"credits"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
		log.Fatal(err)
	}
	fmt.Println(out.Credits.Available, "images available")
}

Векторизация#

Превращает одно растровое изображение в SVG, PDF, EPS, DXF или PNG — один формат или несколько за 1 кредит. Запрос синхронный: ответ приходит, когда вектор готов, — обычно за несколько секунд (для самых больших картинок — до минуты).

Тело запроса#

Картинку можно передать тремя способами:

• Байтами — сам файл и есть тело запроса, параметры — в строке запроса. Заголовок Content-Type не учитывается.
• Формой — Content-Type: multipart/form-data, файл в поле image; параметры — полями формы или в строке запроса (поля формы важнее). Файл в любом другом поле отклоняется.
• Ссылкой — image_url с пустым телом (включаем постепенно).

Формат определяется по содержимому файла (сигнатуре), а не по имени или Content-Type.

Параметры#

Все параметры необязательны. Регистр важен; неизвестный параметр или значение и несовместимые параметры (см. Сочетания) — 400 bad_request с указанием причины.

Параметры проверяются друг с другом; конфликт — 400 bad_request:

• palette не сочетается с colors и max_colors, а max_colors — с colors. palette_tolerance требует palette.
• stroke_width, stroke_color, stroke_scaling требуют draw=stroke или stroke_edges (в том числе если так задано пресетом, например laser). gap_filler=on требует draw=fill; gap_filler_width — gap_filler=on.
• unit требует width или height. scale не сочетается с width/height. aspect, align_x, align_y требуют и width, и height (выравнивание при aspect=stretch ни на что не влияет). dpi требует размер в pt, mm, cm или in.
• retention_days работает только с mode=live и не сочетается с retain=false. mode=preview отдаёт только png.

Ограничения входа#

Уменьшение не меняет физический размер, заданный в width/height. Большое разрешение не делает вектор лучше: быстрее всего обрабатываются картинки около 2000 px по длинной стороне.

Ответ#

Что придёт, зависит от запрошенных форматов:

• Один формат (по умолчанию) — 200 OK, в теле сам файл с Content-Type формата (см. Форматы результата). SVG отдаётся inline, остальные форматы — вложением vector.<формат>. Ничего не хранится, если не передан retain=true или retention_days.
• Несколько форматов или Accept: application/json — JSON со ссылкой на каждый формат; результат хранится 24 часа. См. Хранение результата.

При любой ошибке в теле — JSON, см. Ошибки.

Пресеты#

Пресет — готовый набор настроек под задачу. Передайте preset и при необходимости уточните его явными параметрами: они всегда важнее пресета. Без preset действует web — ровно тот SVG, что API отдавал всегда.

API="https://shapesoda.com/v1/vectorize"
AUTH="Authorization: Bearer $SHAPESODA_KEY"

# web (default): SVG for sites and apps, stacked shapes — the classic result
curl -sS "$API?preset=web" -H "$AUTH" --data-binary @logo.png -o logo.svg

# print: PDF, shapes cut out of each other; here 210 mm wide (A4)
curl -sS "$API?preset=print&width=210&unit=mm" -H "$AUTH" --data-binary @poster.png -o poster.pdf

# cut: SVG, 8 colors cut out and grouped by color — vinyl, stickers, Cricut
curl -sS "$API?preset=cut&width=4&unit=in" -H "$AUTH" --data-binary @sticker.png -o sticker.svg

# laser: 2-color outlines; DXF 100 mm wide for the laser software
curl -sS "$API?preset=laser&format=dxf&width=100&unit=mm" -H "$AUTH" --data-binary @sign.png -o sign.dxf

# embroidery: 12 colors, no tiny shapes; a fixed thread palette instead of 12 colors
curl -sS "$API?preset=embroidery&palette=%23000000,%23ffffff,%23d62828,%23003049" \
  -H "$AUTH" --data-binary @patch.png -o patch.svg

Настройки print, cut, laser и embroidery могут уточняться; web не меняется. Тот же вызов на пяти языках — в примере Векторизация с пресетом.

Форматы результата#

Формат выбирается параметром format. Одно значение — в ответе сам файл; список через запятую (svg,pdf,png) — JSON со ссылкой на каждый формат, все вместе за 1 кредит.

API="https://shapesoda.com/v1/vectorize"
AUTH="Authorization: Bearer $SHAPESODA_KEY"

curl -sS "$API?format=svg" -H "$AUTH" --data-binary @logo.png -o logo.svg   # image/svg+xml
curl -sS "$API?format=pdf" -H "$AUTH" --data-binary @logo.png -o logo.pdf   # application/pdf
curl -sS "$API?format=eps" -H "$AUTH" --data-binary @logo.png -o logo.eps   # application/postscript
curl -sS "$API?format=dxf" -H "$AUTH" --data-binary @logo.png -o logo.dxf   # application/dxf
curl -sS "$API?format=png&width=2000" -H "$AUTH" --data-binary @logo.png -o logo.png   # image/png

# several at once for 1 credit → JSON with links (see Result storage)
curl -sS "$API?format=svg,pdf,eps,dxf,png" -H "$AUTH" --data-binary @logo.png

Физический размер: задайте width или height и unit — px (по умолчанию), pt, mm, cm или in. С одной стороной вторая идёт по пропорциям; с обеими получится лист ровно такого размера, а aspect (fit, fill, stretch) и align_x/align_y решают, как рисунок лежит на нём. Максимум 10 м. Без размера результат в пикселях исходника (после уменьшения, если оно было), умноженных на scale, если он задан. PNG получает пиксели: физические единицы — по dpi (по умолчанию 300).

Тестовый режим#

Собирайте и проверяйте интеграцию бесплатно с mode=test. Ответ того же формата, с теми же заголовками и структурой, что в боевом режиме, но на результате водяной знак: плотный узор, вплетённый в сами фигуры, — удалением слоя его не убрать.

• Не нужны ни кредиты, ни подписка: X-Credits-Charged: 0 и X-Mode: test.
• Пресеты, форматы и параметры работают как в боевом режиме, с двумя исключениями: retention_days и image_url отклоняются с 400 bad_request (тестируйте с файлом и без retention_days).
• Тестовые результаты можно сохранять (несколько форматов, retain=true или Accept: application/json), но только на 1 час вместо 24, и в любом формате они остаются с водяным знаком. Они занимают место в хранилище аккаунта и вытесняются первыми, когда место кончается.
• Лимит: 100 тестовых вызовов на ключ и 100 на аккаунт за сутки (UTC), дальше — 429 test_limit с Retry-After до 00:00 UTC. Тестовые вызовы не входят в суточный лимит картинок.

curl -sS "https://shapesoda.com/v1/vectorize?mode=test&preset=cut" \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  --data-binary @logo.png \
  -D - -o test.svg

HTTP/1.1 200 OK
Content-Type: image/svg+xml; charset=utf-8
X-Credits-Charged: 0
X-Mode: test
X-Credits-Remaining: 99
X-Request-Id: req_4f1c2a9e0b7d4c3a8e21

Предпросмотр#

Покажите пользователю результат до оплаты. mode=preview бесплатен и возвращает растровый PNG до 1 мегапикселя (крупнее — уменьшается), без векторов. Когда результат устроил, откройте векторы по той же ссылке за 1 кредит, не загружая картинку заново.

• Бесплатно, без водяного знака: X-Credits-Charged: 0 и X-Mode: preview. Только format=png; не сочетается с retention_days и image_url. Остальные параметры действуют, поэтому предпросмотр показывает настоящие цвета и фигуры.
• Лимит: 200 предпросмотров на аккаунт за сутки (UTC), дальше — 429 preview_limit с Retry-After до 00:00 UTC. Предпросмотры не входят ни в суточный лимит картинок, ни в тестовый лимит.
• Предпросмотр всегда хранится 24 часа. Ссылка приходит в заголовках X-Result-* (или в JSON с Accept: application/json).
• Открыть векторы: GET /v1/results/{id}?format=svg (или pdf, eps, dxf) с токеном результата. Списывает 1 кредит один раз (0, если эту картинку оплатили за последние 30 дней, см. Бесплатные повторы). Полноразмерный PNG вместо предпросмотра в 1 Мп — с upgrade=true: ?format=png&upgrade=true. Просто ?format=png снова отдаёт бесплатный предпросмотр.
• После этого результат — обычный live (X-Mode: live): все остальные форматы бесплатны, действуют правила хранения результата. Если сборка не удалась, кредит возвращается и результат остаётся предпросмотром. Без кредитов — 402 no_credits.

# 1. бесплатный предпросмотр: PNG в теле, ссылка на результат — в заголовках
curl -sS "https://shapesoda.com/v1/vectorize?mode=preview&preset=cut" \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  --data-binary @logo.png -D headers.txt -o preview.png
RES=$(grep -i '^x-result-url:' headers.txt | cut -d' ' -f2 | tr -d '\r')
TOKEN=$(grep -i '^x-result-token:' headers.txt | cut -d' ' -f2 | tr -d '\r')

# 2. пользователя устроило: открыть SVG за 1 кредит (токен результата, не ключ API)
curl -sS "$RES?format=svg" -H "Authorization: Bearer $TOKEN" -o logo.svg

# 3. дальше все остальные форматы бесплатны
curl -sS "$RES?format=pdf" -H "Authorization: Bearer $TOKEN" -o logo.pdf
curl -sS "$RES?format=png&upgrade=true" -H "Authorization: Bearer $TOKEN" -o logo-full.png

HTTP/1.1 200 OK
Content-Type: image/png
X-Credits-Charged: 0
X-Mode: preview
X-Result-Id: res_9b2e41c07f3a58d61e0c4b7a
X-Result-Url: https://shapesoda.com/v1/results/res_9b2e41c07f3a58d61e0c4b7a
X-Result-Token: q3v6X0cQ1l2mYp8rT4wZkH9sNfB7aJdE5uGiLoVxCyA
X-Result-Expires: 2026-09-30T12:00:00.000Z

Бесплатные повторы#

За картинку вы платите один раз. Повтор бесплатен в двух случаях, и в ответе будет X-Credits-Charged: 0:

• Картинка узнаётся по хешу SHA-256 её байтов — тому же, что на сайте: картинку, оплаченную кредитом на shapesoda.com, можно бесплатно повторить через API, и наоборот. Уменьшенный или пересохранённый файл — уже другая картинка.
• Повторы с другими параметрами входят в суточный лимит картинок ключа.
• Тестовые вызовы и картинки, сделанные по безлимитной подписке сайта, 30-дневное окно не открывают.
• Предпросмотры (mode=preview) бесплатны и 30-дневное окно не открывают; открытие векторов из предпросмотра — обычный платный вызов (1 кредит или бесплатный повтор, если картинку оплатили за последние 30 дней).

Хранение результата#

По умолчанию ничего не хранится: запрос на один формат возвращает файл и забывает картинку. Результат хранится 24 часа, только когда он понадобится позже:

• вы просите несколько форматов или шлёте Accept: application/json — ровно это значение; клиенты с application/json, */* по-прежнему получают файл;
• вы передаёте retain=true или retention_days — файл приходит как обычно, а ссылка — в заголовках X-Result-*;
• вы используете mode=preview (хранится всегда, см. Предпросмотр);
• вызов пришёл через MCP.

# several formats → JSON (or add -H "Accept: application/json" for a single format)
curl -sS "https://shapesoda.com/v1/vectorize?format=svg,pdf" \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  --data-binary @logo.png

{
  "result_id": "res_9b2e41c07f3a58d61e0c4b7a",
  "result_url": "https://shapesoda.com/v1/results/res_9b2e41c07f3a58d61e0c4b7a",
  "result_token": "q3v6X0cQ1l2mYp8rT4wZkH9sNfB7aJdE5uGiLoVxCyA",
  "width": 1200,
  "height": 800,
  "input_scale": 1,
  "credits_charged": 1,
  "credits_remaining": 99,
  "mode": "live",
  "expires_at": "2026-09-30T12:00:00.000Z",
  "files": {
    "svg": "https://shapesoda.com/v1/results/res_9b2e41c07f3a58d61e0c4b7a?format=svg",
    "pdf": "https://shapesoda.com/v1/results/res_9b2e41c07f3a58d61e0c4b7a?format=pdf"
  }
}

Скачивайте с токеном результата, а не с ключом API: Authorization: Bearer <result_token> (рекомендуется). ?token=<result_token> тоже принимается, но токен в адресе может попасть в журналы доступа, историю браузера и аналитику. Скачать результат может любой, у кого есть токен, поэтому обращайтесь со ссылкой как с самим файлом. Без format придёт первый формат исходного запроса: первый в вашем списке format, в том порядке, как вы его записали (повторы отбрасываются), а если format не передавали — формат пресета. Объект files в JSON-ответе перечисляет форматы в том же порядке. Формат, который вы не просили, собирается один раз из сохранённого исходника строго с теми же пресетом, параметрами и режимом — бесплатно и без новой загрузки. Сборку ограничивает частота запросов аккаунта-владельца результата (60 в минуту, 429 rate_limited с Retry-After); уже сохранённые форматы — нет.

RES="https://shapesoda.com/v1/results/res_9b2e41c07f3a58d61e0c4b7a"
TOKEN="q3v6X0cQ1l2mYp8rT4wZkH9sNfB7aJdE5uGiLoVxCyA"   # result_token, not the API key

curl -sS "$RES?format=pdf" -H "Authorization: Bearer $TOKEN" -o logo.pdf
# a format you did not ask for is built from the stored source, free of charge
curl -sS "$RES?format=dxf" -H "Authorization: Bearer $TOKEN" -o logo.dxf
# the same with the token in the link (less safe: URLs end up in logs)
curl -sS "$RES?format=eps&token=$TOKEN" -o logo.eps
# delete now instead of waiting 24 hours
curl -sS -X DELETE "$RES" -H "Authorization: Bearer $TOKEN"

С retain=true (или retention_days) и одним форматом файл приходит как обычно, плюс ссылка:

HTTP/1.1 200 OK
Content-Type: image/svg+xml; charset=utf-8
X-Credits-Charged: 1
X-Mode: live
X-Result-Id: res_9b2e41c07f3a58d61e0c4b7a
X-Result-Url: https://shapesoda.com/v1/results/res_9b2e41c07f3a58d61e0c4b7a
X-Result-Token: q3v6X0cQ1l2mYp8rT4wZkH9sNfB7aJdE5uGiLoVxCyA
X-Result-Expires: 2026-09-30T12:00:00.000Z

• Зашифровано. Исходник и каждый формат шифруются AES-256-GCM ключом, выведенным из токена. Мы храним только хеш токена, поэтому без ссылки сохранённый результат не прочитать.
• Удаляется через 24 часа (предпросмотр тоже), тестовый — через 1 час, результат с retention_days — через столько дней (см. expires_at). DELETE удаляет сразу и возвращает 204.
• Неизвестный id, неверный токен и истёкший результат одинаково дают 404 not_found.
• Если хранилище заполнено, запросы с JSON получают 503 storage_full (кредит не списывается; повторите через Retry-After или попросите один формат), а retain=true и retention_days возвращают файл без заголовков X-Result-*.

Срок хранения#

По умолчанию сохранённый результат живёт 24 часа. Если пользователи возвращаются за файлами, попросите больше через retention_days — от 1 до 30 суток, бесплатно. Параметр сохраняет результат даже на один формат (как retain=true) и отдаёт ссылку в заголовках X-Result-*; срок — в expires_at / X-Result-Expires.

• Только для mode=live и не вместе с retain=false. Тестовые результаты живут 1 час, предпросмотры — 24 часа.
• Сохранённые результаты входят в квоту хранилища аккаунта. Когда место кончается, вытесняются самые старые в таком порядке: тестовые, предпросмотры, боевые без retention_days и в последнюю очередь — с retention_days. Если места всё равно нет — 503 storage_full (кредит не списывается).
• Форматы, дособранные из сохранённого результата, бесплатны весь срок. DELETE удаляет результат в любой момент.

curl -sS "https://shapesoda.com/v1/vectorize?retention_days=30" \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  --data-binary @logo.png -D - -o logo.svg   # X-Result-Expires: через 30 суток

Картинка по ссылкеСкоро#

Вместо файла передайте адрес публичной картинки в image_url (параметром запроса или полем формы) с пустым телом. Всё остальное работает как с файлом.

curl -sS https://shapesoda.com/v1/vectorize \
  -H "Authorization: Bearer $SHAPESODA_KEY" \
  -F image_url=https://example.com/logo.png \
  -F preset=cut \
  -o logo.svg

• http или https, порт 80 или 443, без логина и пароля, до 2048 символов — иначе 400 url_invalid.
• Картинка скачивается через изолированный egress-прокси: частные, локальные, link-local адреса и адреса метаданных облаков закрыты, в том числе после перенаправлений (422 url_blocked).
• Не больше 3 перенаправлений, 10 секунд (504 url_timeout) и 10 МБ (413 too_large). Сервер не ответил или вернул ошибку — 422 url_unreachable.
• Передавайте либо файл, либо image_url, не оба сразу. В тестовом режиме не работает.

Аккаунт и кредиты#

Возвращает аккаунт, которому принадлежит ключ, и его кредиты. Кредиты считаются по календарным месяцам (UTC).

{
  "account": { "id": "acc_3f9c1e7a2b4d6e80", "name": "[email protected]" },
  "credits": {
    "available": 97,
    "balance": 97,
    "quota": 0,
    "quota_used": 0,
    "quota_left": 0,
    "spent_month": 3,
    "spend_limit": null
  }
}

Прайс-лист#

Те же цены, что в разделе Цены, в виде JSON и без авторизации. В ответе: api_plans (месячные планы с кредитами: credits, price, per_image), subscriptions (подписки для сайта), credits_never_expire, redownload_free_days, result_retention_hours, signup_credits, enterprise_contact и payments_enabled / billing (данные для оплаты, если для посетителя включены платежи).

Ошибки#

Ошибки приходят со стандартными кодами HTTP и JSON-телом с постоянным машинным кодом code. Обрабатывайте code, а не message: сообщение — подсказка для человека, оно может меняться.

{
  "error": {
    "code": "too_many_pixels",
    "message": "Human-readable description",
    "request_id": "req_4f1c2a9e0b7d4c3a8e21"
  }
}

Кредит резервируется в начале обработки и автоматически возвращается при ошибке — вы платите только за полученные результаты.

Ограничения частоты#

Бюджет запросов ключа общий для REST API и MCP-сервера. GET /v1/account в него не входит. Нужно больше — напишите на [email protected].

Повторные запросы#

• Повторяйте только rate_limited и busy (через время из Retry-After) и один раз internal с короткой паузой. Остальные ошибки 4xx повторятся.
• Retry-After — целое число секунд, а не дата HTTP. Он приходит с rate_limited (время до следующего разрешённого запроса), busy и timeout (5), storage_full (60) и суточными лимитами (секунды до 00:00 UTC).
• Отклонённый запрос не расходует лимит. Лимит в минуту устроен как «ведро с токенами»: запрос, получивший 429 rate_limited, токен не тратит, поэтому достаточно подождать Retry-After.
• Повторы бесплатны: тот же запрос (та же картинка и те же параметры) в течение 24 часов повторно не оплачивается — в ответе X-Credits-Charged: 0. Та же картинка с другими параметрами тоже бесплатна 30 дней в пределах суточного лимита — см. Бесплатные повторы.
• Ставьте щедрый таймаут клиента — не меньше 120 секунд, чтобы не оборвать медленный запрос, когда картинка уже обработана и оплачена.
• Для пакетной обработки запускайте несколько запросов параллельно (2–4), а не десятки: всё сверх пачки получит 429.

async function vectorize(image, attempt = 0, retriedInternal = false) {
  const res = await fetch("https://shapesoda.com/v1/vectorize", {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.SHAPESODA_KEY}` },
    body: image,
    signal: AbortSignal.timeout(120_000),
  });
  if (res.ok) return res.text();
  const { error } = await res.json();
  if (["rate_limited", "busy"].includes(error.code) && attempt < 3) {
    const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt);
    await new Promise((r) => setTimeout(r, wait * 1000));
    return vectorize(image, attempt + 1, retriedInternal);
  }
  if (error.code === "internal" && !retriedInternal) { // один повтор с короткой паузой
    await new Promise((r) => setTimeout(r, 1000));
    return vectorize(image, attempt, true);
  }
  throw new Error(`${error.code}: ${error.message} (${error.request_id})`);
}

Чек-лист для продакшена#

• Таймаут: поставьте таймаут клиента не меньше 120 секунд.
• Проверяйте до сохранения: пишите тело в файл, только если статус 200, а Content-Type — тот, что вы просили (image/svg+xml, application/pdf, …, а для нескольких форматов — application/json). Ошибки приходят в JSON — не сохраняйте их как .svg.
• Учитывайте Retry-After (секунды); повторяйте только rate_limited, busy и один раз internal. См. Повторные запросы.
• Держите ключ API в секрете и только на сервере: не в браузере, не в мобильном приложении и не в репозитории. Утёкший ключ отзовите.
• Токены результатов: передавайте их в заголовке Authorization, а не в ?token=, и не пускайте ссылки на результаты в журналы и аналитику.
• Разработка: пока собираете интеграцию, используйте mode=test (бесплатно, с водяным знаком, 100 вызовов в сутки); в релизе переключитесь на live.
• Поддержка: сохраняйте X-Request-Id при каждой ошибке.

Безопасность и приватность#

• Ключи хранятся в виде хешей. Мы храним только хеш с секретом (HMAC-SHA-256) и короткий префикс ключа, поэтому ключ показывается один раз и не восстанавливается — его можно только отозвать и заменить.
• Лимит расходов задаёте вы. Месячный лимит в меню аккаунта действует для всех ключей, MCP-сервера и сайта: ни агент, ни утёкший ключ не потратят больше, чем вы разрешили.
• Картинки хранятся, только когда это нужно вам. Запрос на один формат обрабатывается в памяти в изолированном процессе и сразу забывается — на диск и в базу ничего не пишется. Несколько форматов, retain=true, retention_days, предпросмотры и результаты MCP хранятся 24 часа (с retention_days — до 30 суток) в зашифрованном виде — ключ есть только у владельца токена результата, — а потом удаляются; скачать их может любой, у кого есть ссылка с токеном. Загрузки MCP живут в памяти не дольше 10 минут. Для обучения моделей картинки не используются. Подробнее — в разделе Хранение результата и в Политике конфиденциальности.
• SVG проверяется. Каждый результат перед отдачей сверяется со строгим белым списком (контуры, группы и градиенты с простыми цветами) — никаких скриптов, обработчиков событий, внешних ссылок и встроенного содержимого. PDF, EPS и DXF собираются только из геометрии и цветов вектора.
• Вход проверяется. Формат определяется по содержимому, разрешение — до декодирования (защита от «бомб»), каждая задача выполняется в отдельном процессе с ограничением по времени. Картинки по ссылке скачиваются в отдельном процессе через egress-прокси, который закрывает внутренние адреса.

SDK и CLI#

Официальные библиотеки оборачивают тот же API: типизированные опции, автоматические повторы после 429/503, скачивание результатов. Они сгенерированы из спецификации OpenAPI, поэтому доступен каждый параметр с этой страницы.

• Python: pip install shapesoda (PyPI). Shapesoda(key).vectorize_file("logo.png", formats=["svg","pdf"], preset="print"), а также preview_file() и upgrade().
• JavaScript / TypeScript: npm install @shapesoda/sdk (npm). new Shapesoda(key).vectorizeFile("logo.png", { formats: ["svg","pdf"], preset: "print" }), а также previewFile() и upgrade(). Работает через import и require, Node 18+.
• Go, PHP, Ruby, Java, C#: сгенерированные клиенты лежат в папке clients/sdk репозитория; публикация в pkg.go.dev, Packagist, RubyGems, Maven Central и NuGet идёт. Пока их нет в реестрах, сгенерируйте клиент из спецификации (см. ниже) или используйте примеры на HTTP выше.
• CLI: npx shapesoda ./in ./out --preset cut --format svg,dxf (npm, Node 18+). Папка на вход, папка на выход, повторы и пропуск готовых файлов встроены; --preview, --test, shapesoda account.

Спецификация OpenAPI#

Машиночитаемое описание API в формате OpenAPI 3.1 — импортируйте в Postman, Insomnia или Bruno либо сгенерируйте клиент:

npx @openapitools/openapi-generator-cli generate \
  -i https://shapesoda.com/openapi.json -g typescript-fetch -o ./shapesoda-client

MCP для ИИ-приложений и агентов#

Model Context Protocol позволяет ИИ-приложениям и агентам вызывать внешние инструменты. MCP-сервер Shapesoda превращает картинки в SVG, PDF, EPS, DXF или PNG прямо в ChatGPT, Claude, Cursor, Claude Code и любом другом MCP-клиенте. Аккаунт Shapesoda подключается входом (OAuth); агенты и скрипты по-прежнему могут работать с ключом API — с теми же кредитами и лимитами, что и REST API.

Бесплатно: 3 векторизации в месяц без аккаунта, 10 в месяц с подключённым аккаунтом (OAuth или ключ), дальше кредиты. REST и сайт это не меняет. Личный план с сайта в чатах без лимита, если аккаунт подключён входом; вызовы с ключом API тратят кредиты. Смена настроек той же картинки в окне Shapesoda бесплатна 24 часа — за одну картинку платите один раз. Тестовому режиму, предпросмотру, retention_days и vectorize_url нужен аккаунт. Бесплатные обновляются 1-го числа каждого месяца (UTC); остаток показывают get_usage и free_remaining_today в каждом результате. Внутри чатов ничего не продаём: цены и оплата — на сайте.

Подключить в ChatGPT, Claude, Cursor или Claude Code#

Адрес сервера: https://shapesoda.com/mcp. Когда бесплатные закончатся, чат предложит подключить аккаунт Shapesoda: войдите через Google или по коду из письма и нажмите «Разрешить». Подключённые приложения видны в аккаунте, там же их можно отключить.

ChatGPT#

Найдите Shapesoda в каталоге приложений ChatGPT или добавьте адрес сервера как своё приложение в режиме разработчика. Приложите картинку и напишите @Shapesoda или «сделай SVG»: ChatGPT один раз спросит разрешение передать файл (вход image у vectorize), и окно Shapesoda покажет шторку «до/после», настройки, скачивание во всех форматах и «Копировать SVG».

Claude#

В claude.ai или Claude Desktop откройте «Настройки» → «Коннекторы» и добавьте Shapesoda из каталога или через «Добавить свой коннектор» с адресом сервера. Claude не передаёт приложениям приложенные файлы, поэтому просто попросите векторизовать картинку: он вызовет open_editor, и вы выберете файл в окне Shapesoda.

Claude Code#

Добавьте сервер, затем выполните /mcp, выберите shapesoda и Authenticate — аккаунт подключится в браузере:

claude mcp add --transport http shapesoda https://shapesoda.com/mcp

Или с ключом API вместо входа:

claude mcp add --transport http shapesoda https://shapesoda.com/mcp \
  --header "Authorization: Bearer $SHAPESODA_KEY"

Cursor#

Установите плагин Shapesoda из маркетплейса Cursor или добавьте сервер в ~/.cursor/mcp.json (или в .cursor/mcp.json проекта). При первом вызове Cursor предложит подключить аккаунт.

{
  "mcpServers": {
    "shapesoda": { "url": "https://shapesoda.com/mcp" }
  }
}

С ключом API Cursor подставит ${env:SHAPESODA_KEY} из переменных окружения, и ключ не окажется в файле:

{
  "mcpServers": {
    "shapesoda": {
      "url": "https://shapesoda.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SHAPESODA_KEY}" }
    }
  }
}

Другие клиенты, которые поддерживают удалённые MCP-серверы (Streamable HTTP), подключаются так же: адрес https://shapesoda.com/mcp, вход OAuth 2.1 (клиент находит его по /.well-known/oauth-protected-resource) или заголовок Authorization: Bearer <ключ>. Сервер отвечает JSON (без потока SSE) и поддерживает версии протокола 2025-11-25, 2025-06-18 и 2025-03-26.

Инструменты#

Как агент передаёт файл#

Агенты обычно не умеют прикладывать двоичные файлы к вызову инструмента, поэтому большие картинки идут через короткоживущую ссылку загрузки:

1. create_upload

   возвращает upload_id и секретную ссылку upload_url.

2. Загрузка через curl

   Агент выполняет полученную команду: curl -sS -X PUT --data-binary @image.png "<upload_url>". Ссылка принимает один файл PNG, JPEG, WebP, BMP, GIF или TIFF и не требует другой авторизации.

3. vectorize с upload_id

   В результате — ссылка на каждый запрошенный формат в files (на 24 часа, токен уже в ссылке), download_url на первый из них, SVG прямо в ответе (если он меньше 60 КБ), размеры картинки, credits_charged и credits_remaining.

Небольшую картинку (до 2 МБ) агент может передать сразу в image_base64, без загрузки.

Ссылку загрузки обслуживает PUT /v1/uploads/{upload_id}. Это часть потока загрузки MCP: он есть в спецификации OpenAPI для полноты, но в REST-интеграции вы его не вызываете.

Цены#

Ежемесячная подписка на выбранное число кредитов. Один кредит — одна успешно векторизованная картинка во всех форматах, запрошенных в этом вызове, через API, MCP или сайт. Отмена в любой момент.

• Неиспользованные кредиты переходят дальше (до 5 месяцев)
• Отмена в любой момент, кредиты действуют до конца тарифа
• Общий баланс с сайтом
• Неудачные запросы бесплатны