Rasterless

Dla programistów: API Rasterless i serwer MCP

Wywołaj ten sam konwerter ze skryptu albo z agenta, jednym kluczem API.

Działa z twoimi ulubionymi agentami

Wszystko, co robi konwerter na tej stronie, jest dostępne przez HTTP: jeden obraz na wejściu, wybrane przez ciebie formaty na wyjściu, z tymi samymi opcjami i tymi samymi limitami. Agent, który obsługuje Model Context Protocol, może wywołać konwerter jako narzędzie przez zdalny serwer MCP, tym samym kluczem.

Tabele na tej stronie są generowane z kodu, który odpowiada na żądania, więc nazwa opcji ani limit nie mogą się rozjechać z tym, co przyjmuje serwer. Wartości, które nie są jeszcze ustalone, są oznaczone jako takie, zamiast być zgadywane.

Szybki start

Najpierw zaloguj się przez Google i utwórz klucz API w panelu, który znajdziesz dalej. Klucze zaczynają się od rl_live_ i są pokazywane tylko raz. Nie trzymaj klucza w systemie kontroli wersji; przykłady odczytują go ze zmiennej środowiskowej o nazwie RASTERLESS_API_KEY.

Twoje klucze API

Zaloguj się na tej stronie przez Google, żeby tworzyć klucze API i nimi zarządzać. Panel wymaga JavaScriptu.

Pierwsze wywołanie

1. Zapisz klucz w zmiennej środowiskowej. Zastąp symbol zastępczy swoim kluczem. Zmienna obowiązuje, dopóki nie zamkniesz tego okna terminala.

bash
export RASTERLESS_API_KEY='TWOJ_KLUCZ_API'
PowerShell
$env:RASTERLESS_API_KEY = 'TWOJ_KLUCZ_API'

2. Sprawdź klucz. GET /v1/account zwraca klucz i pozostały przydział i nie liczy się jako konwersja. 401 api_key_invalid zwykle oznacza, że przy kopiowaniu zgubiła się część klucza.

bash
curl -sS https://api.rasterless.com/v1/account \
  -H "Authorization: Bearer $RASTERLESS_API_KEY"
PowerShell
curl.exe -sS https://api.rasterless.com/v1/account `
  -H "Authorization: Bearer $env:RASTERLESS_API_KEY"

3. Przekonwertuj plik z komputera. Po @ następuje ścieżka obrazu; ./logo.png to plik logo.png w folderze, w którym jest terminal. W PowerShellu wpisz curl.exe: w Windows PowerShell samo curl uruchamia inne polecenie. curl.exe jest w Windows 10 od kompilacji 17063.

bash
curl -X POST https://api.rasterless.com/v1/vectorize \
  -H "Authorization: Bearer $RASTERLESS_API_KEY" \
  -F image=@./logo.png \
  -F formats=svg,dxf \
  -F colors=auto
PowerShell
curl.exe -X POST https://api.rasterless.com/v1/vectorize `
  -H "Authorization: Bearer $env:RASTERLESS_API_KEY" `
  -F "image=@./logo.png" `
  -F "formats=svg,dxf" `
  -F "colors=auto"

4. Odczytaj odpowiedź. Ten przykład ma pola i typy prawdziwej odpowiedzi; wartości pochodzą z konwersji testowej, a linki do pobrania są przykładowe:

Przykładowa odpowiedź
{
  "id": "d23ed01b4e504118855e620297706bbb",
  "colors_used": 4,
  "seconds": 2.61,
  "outputs": {
    "svg": "https://storage.googleapis.com/…/output.svg?X-Goog-Algorithm=GOOG4-RSA-SHA256&…",
    "dxf": "https://storage.googleapis.com/…/output.dxf?X-Goog-Algorithm=GOOG4-RSA-SHA256&…"
  },
  "expires_in": 3600,
  "preview_url": "https://storage.googleapis.com/…/output_preview.png?X-Goog-Algorithm=GOOG4-RSA-SHA256&…",
  "colors_auto": {
    "detected": true,
    "regime": "A",
    "margin": 11590.0
  },
  "shapes": 5
}

Odpowiedź to JSON: outputs zawiera podpisany link do pobrania dla każdego zamówionego formatu, a colors_used liczbę kolorów, której użył silnik. Linki wygasają po 1 godzinie, więc pobierz pliki, gdy tylko przyjdzie odpowiedź, zamiast przechowywać linki. Zamów jeden format i dodaj do adresu ?return=file, żeby dostać sam plik zamiast JSON-a.

id identyfikuje zadanie, a seconds to czas trwania konwersji. shapes liczy kształty w wyniku, preview_url to podgląd PNG o tym samym czasie ważności co linki, a colors_auto.detected mówi, czy colors=auto znalazło liczbę kolorów w obrazie, czy użyło wartości domyślnej.

Uwierzytelnianie

Każde żądanie niesie klucz w nagłówku Authorization: Bearer, przez HTTPS. API nie ustawia żadnego pliku cookie i nie pokazuje weryfikacji w przeglądarce: klucz to cała tożsamość, więc traktuj go jak hasło i wykonuj wywołania na swoim serwerze. Klucz w kodzie przeglądarki albo w aplikacji mobilnej to klucz, który każdy może odczytać. Żądanie bez klucza zwraca 401 api_key_missing, błędny klucz 401 api_key_invalid, a unieważniony klucz 401 api_key_revoked. Unieważnienie działa od następnego żądania, a każde konto może mieć jednocześnie ograniczoną liczbę aktywnych kluczy.

Jeśli na podstawie regulaminu zawiesimy lub unieważnimy któryś z twoich kluczy, na liście kluczy pojawi się jako unieważniony, a my napiszemy na adres e-mail twojego konta Google.

Endpointy i parametry

EndpointOpis
POST /v1/vectorize Konwertuje jeden obraz i zwraca podpisany link dla każdego formatu.
GET /v1/options Wymienia akceptowane wartości każdej opcji.
GET /v1/account Pokazuje limit klucza i to, ile z niego zostało.

POST /v1/vectorize przyjmuje multipart/form-data: obraz w polu o nazwie image, a opcje jako zwykłe pola formularza. Wartości to osie, które zwraca GET /v1/options, a tabela jest budowana z tych samych stałych, więc nie może się nie zgadzać z serwerem.

Pola formularza POST /v1/vectorize
ParametrWartości DomyślnieOpis
image wymagany PNG, JPEG, WEBP, BMP, GIF, AVIF — Obraz jako pole pliku multipart. Typ określają pierwsze bajty, a nie nazwa pliku.
formats svg, pdf, eps, dxf, png svg Jeden lub więcej, rozdzielone przecinkami; odpowiedź zawiera po jednym linku na format.
colors 2–64, auto auto Wielkość palety; 2 daje trasowanie czarno-białe. auto odczytuje liczbę z grafiki o płaskich kolorach, a gdy się nie da, używa 26.
svg_version svg_1_0, svg_1_1, svg_tiny_1_2 svg_1_1 Wersja zapisywana w elemencie głównym SVG.
draw_style fill_shapes, stroke_shapes, stroke_edges fill_shapes Wypełnione kształty, obrysowane kształty albo same krawędzie. W DXF dwa pierwsze dają te same zamknięte kontury; same krawędzie dają otwarte ścieżki.
shape_stacking cutouts, stacked cutouts Wycięcia przebijają otwory w kształtach pod spodem; nałożone kładzie je jeden na drugim.
group_by none, color, parent, layer none Tylko grupowanie w SVG: brak, według koloru, według kształtu nadrzędnego albo według warstwy.
size_mm WxH, 1–5000 mm — Rozmiar fizyczny, na przykład 150x150. Dotyczy SVG, PDF, EPS i DXF; zostaw puste, żeby zachować jednostki pikselowe.
denoise 0–50 0 Siła filtra wstępnego, który zachowuje krawędzie; 0 go wyłącza. Niedostępne w narzędziu MCP.

group_by zmienia tylko to, jak SVG grupuje swoje ścieżki. W DXF fill_shapes i stroke_shapes zapisują te same zamknięte kontury (LWPOLYLINE i SPLINE trzeciego stopnia) na jednej warstwie FILL_ na kolor; stroke_edges zapisuje zamiast tego sieć krawędzi, każdą granicę raz jako otwartą ścieżkę, na warstwach EDGE_. DXF jest zapisywany jako R2010 (AC1024) w milimetrach.

Błędy

Błąd zwraca JSON w obiekcie error: pole code, pole type, które grupuje kody w rodziny (bad_input, auth, quota, too_complex, timeout, busy, not_found, server), wartości, które za nim stoją, w params i zapasowy komunikat message po angielsku. Rozgałęziaj logikę według type, zapisuj code w logach i nigdy nie parsuj treści komunikatu. Typowa treść odpowiedzi to {"error": {"code": "file_too_large", "type": "bad_input", "params": {"max_mb": 25}}}, a obok niej komunikat.

Zmianę w /v1, która zepsułaby działające dziś żądanie, ogłaszamy na tej stronie co najmniej 30 dni przed jej wejściem w życie. Dodatki, przy których działające żądania pozostają bez zmian, na przykład nowe pole opcjonalne, mogą pojawiać się bez uprzedzenia.

HTTPKodZnaczenie
400 image_missing Brak pliku w polu image.
400 multipart_invalid Nie udało się odczytać treści żądania jako multipart/form-data.
400 unsupported_input Rozszerzenie pliku nie jest akceptowanym wejściem.
400 not_an_image Pierwsze bajty pliku nie są akceptowanym obrazem rastrowym.
400 invalid_option Opcja ma wartość spoza swojej listy; params podaje, która.
400 size_mm_format size_mm nie jest zapisany w postaci SZERxWYS, na przykład 150x150.
400 size_mm_range Jeden z boków size_mm wykracza poza akceptowany zakres.
400 return_needs_one_format Zażądano ?return=file przy więcej niż jednym formacie.
401 api_key_missing Brak klucza w nagłówku Authorization.
401 api_key_invalid Klucz jest nieważny.
401 api_key_revoked Klucz został unieważniony; utwórz nowy.
403 key_suspended Jeden z kluczy konta jest zawieszony; nie można utworzyć nowego klucza.
409 key_limit Konto ma już maksymalną liczbę aktywnych kluczy.
413 file_too_large Wgrany plik przekracza limit rozmiaru pliku.
413 image_too_large Zdekodowany obraz przekracza limit pikseli.
422 too_complex Zadanie nie zostało uruchomione: jego oszacowanie przekracza budżet czasu albo (image_bound false) serwerowi zostało za mało czasu na to żądanie. Mniejsza liczba kolorów jest sugerowana, jeśli któraś przechodzi oszacowanie.
422 timeout Konwersja przekroczyła swój budżet czasu; mniej kolorów nie pomoże, mniejszy obraz może pomóc.
429 busy Wszystkie procesy robocze są zajęte; spróbuj ponownie po czasie z nagłówka Retry-After.
429 quota_hourly Klucz wykorzystał swój limit godzinowy.
429 quota_daily Klucz wykorzystał swój limit dzienny.
429 quota_url_fetch Klucz wykorzystał godzinny limit pobrań image_url (narzędzie MCP).
429 quota_requests Klucz wysłał godzinny limit żądań konwersji, niezależnie od ich wyniku; ponów po czasie z nagłówka Retry-After.
429 key_create_limit Konto wykorzystało już limit nowych kluczy z ostatnich 24 godzin; spróbuj ponownie po czasie z nagłówka Retry-After.

Przy 429 busy odczekaj czas podany w nagłówku Retry-After i wyślij żądanie ponownie.

Przy 422 too_complex konwersja w ogóle się nie zaczęła, a error.image_bound mówi dlaczego. Jeśli ma wartość true, sam obraz przekracza limit. Jeśli error.suggested_n_colors jest wtedy liczbą, to jest to mniejsza liczba kolorów, której oszacowanie sprawdziliśmy względem limitów, jakie napotka nowe żądanie, zwykle największa, która przechodzi; ponowna próba z tą liczbą przejdzie tę kontrolę. To oszacowanie, nie obietnica: ponowna próba nadal może skończyć się kodem timeout. Jeśli wartość to null, a fewer_colors_help ma wartość false, oszacowanie przekracza limit nawet przy 2 kolorach; mniej kolorów nie pomoże, mniejszy obraz może pomóc. Jeśli oba pola mają wartość null, nie udało się wyliczyć sugestii.

Jeśli image_bound ma wartość false, przyczyną nie jest obraz: serwerowi zabrakło czasu na to żądanie. suggested_n_colors i fewer_colors_help mają wtedy wartość null, a to samo żądanie można wysłać ponownie za chwilę.

Przy 422 timeout konwersja się rozpoczęła i przekroczyła swój budżet czasu. Liczba kolorów prawie nie zmienia czasu konwersji, więc treść odpowiedzi nie sugeruje liczby kolorów: suggested_n_colors to null, a fewer_colors_help to false. Mniejszy obraz pomaga tylko poniżej 1,5 megapiksela, bo większe obrazy i tak są trasowane w tym rozmiarze; spróbuj mniej więcej połowy tego (np. 1000 × 750 px) albo zmniejsz szum i teksturę. image_bound występuje tylko przy too_complex.

Przy timeout konwersja wraca do limitu klucza (quota_refunded: true): raz na obraz w ciągu godziny i najwyżej 2 razy na klucz w każdej pełnej godzinie zegarowej; powyżej tego treść odpowiedzi zawiera quota_refunded: false.

Rzadko konwersja przekracza swój budżet czasu i połączenie zamyka się po około 100 sekundach z HTTP 524, bez treści JSON; traktuj to jak timeout.

Limity i przydziały

LimitWartość
Konwersje na klucz, na godzinę 20
Konwersje na klucz, na dzień 100
Aktywne klucze na konto 2
Nowe klucze na konto w ciągu 24 godzin, po pierwszych 2 1
Pobrania image_url przez MCP na klucz, na godzinę 120
Żądania konwersji na klucz, na godzinę (API i MCP) 200
Rozmiar pliku 25 MB
Rozmiar zdekodowanego obrazu 40 MP
Budżet czasu na konwersję 90 s
Ważność linku do pobrania 1 h
size_mm, na bok 1–5000 mm

Wiersz pobrań liczy każde pobranie image_url przez narzędzie MCP vectorize_image. Liczenie następuje przed rozpoczęciem pobierania, więc pobranie, które się nie uda albo zwróci coś innego niż obraz, też się liczy. Ten licznik jest oddzielny od przydziału konwersji.

Obrazy większe niż 1,5 megapiksela są przed trasowaniem pomniejszane, więc wymiary wyniku w pikselach wynikają z pomniejszonej kopii; ustaw size_mm, jeśli potrzebujesz wymiarów fizycznych. Jeden obraz na żądanie.

Cennik

Klucze API i konwersje, które wykonujesz nimi w ramach powyższego limitu, są bezpłatne w okresie beta. Nic nie zostanie naliczone bez twojej wcześniejszej wyraźnej zgody (regulamin, sekcja 4).

Serwer MCP

Serwer MCP pozwala agentowi wywoływać konwerter jako narzędzie. Działa przez Streamable HTTP pod adresem https://api.rasterless.com/mcp i przyjmuje ten sam klucz typu bearer w tym samym nagłówku. Udostępnia dwa narzędzia: vectorize_image konwertuje jeden obraz, podany jako image_url (publiczny adres https) albo jako image_base64, z opcjami z tabeli parametrów; get_options zwraca akceptowane wartości i pozostały limit klucza, żeby agent mógł wybrać. Wybierz swojego klienta, żeby zobaczyć konfigurację:

Claude Code

Polecenie zapisuje klucz w twoich ustawieniach użytkownika. Wariant .mcp.json odczytuje go ze środowiska, więc plik można dodać do repozytorium. Długa konwersja może przekroczyć domyślny limit czasu narzędzia; MCP_TOOL_TIMEOUT=120000 go podnosi.

Terminal
claude mcp add --transport http rasterless https://api.rasterless.com/mcp \
  --header "Authorization: Bearer $RASTERLESS_API_KEY"
.mcp.json
{
  "mcpServers": {
    "rasterless": {
      "type": "http",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Claude Code)

Claude Desktopjeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Nagłówki żądań w niestandardowych konektorach są w wersji beta i mają je tylko niektóre organizacje. Jeśli brakuje sekcji Request headers, ten klient nie może jeszcze wysłać klucza. Konektor jest wspólny dla wszystkich w organizacji, z jednym kluczem.

Customize › Connectors › Add custom connector
URL             https://api.rasterless.com/mcp
Authentication  none (the request header carries the key)
Request header  authorization: Bearer rl_live_…

Oficjalna dokumentacja konfiguracji (Claude Desktop)

Cursorjeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Cursor odczytuje klucz ze zmiennej środowiskowej, więc plik nie zawiera żadnego sekretu.

~/.cursor/mcp.json
{
  "mcpServers": {
    "rasterless": {
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${env:RASTERLESS_API_KEY}" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Cursor)

Visual Studio Codejeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Pierwszy plik to obecny format. Starszy .vscode/mcp.json pyta o klucz i nie zapisuje go w pliku; nadal działa, ale jest wycofywany.

.mcp.json
{
  "mcpServers": {
    "rasterless": {
      "type": "http",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" },
      "tools": ["*"]
    }
  }
}
.vscode/mcp.json
{
  "inputs": [
    { "type": "promptString", "id": "rasterless-key",
      "description": "API key", "password": true }
  ],
  "servers": {
    "rasterless": {
      "type": "http",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer ${input:rasterless-key}" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Visual Studio Code)

Windsurfjeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Ustawienia agenta Windsurf znajdują się teraz w Devin Desktop. Plik .local.json pozostaje poza kontrolą wersji.

.devin/mcp_config.local.json
{
  "mcpServers": {
    "rasterless": {
      "url": "https://api.rasterless.com/mcp",
      "transport": "http",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Windsurf)

Codex CLIjeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Codex wysyła wartość zmiennej jako token bearer; sam plik nie zawiera żadnego sekretu.

~/.codex/config.toml
[mcp_servers.rasterless]
url = "https://api.rasterless.com/mcp"
bearer_token_env_var = "RASTERLESS_API_KEY"

Oficjalna dokumentacja konfiguracji (Codex CLI)

Gemini CLIjeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Użyj httpUrl: w tym pliku url oznacza starszy transport SSE.

~/.gemini/settings.json
{
  "mcpServers": {
    "rasterless": {
      "httpUrl": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Gemini CLI)

Zedjeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Bez nagłówka Authorization Zed uruchamia zamiast tego proces logowania, więc zostaw nagłówek na miejscu.

settings.json
{
  "context_servers": {
    "rasterless": {
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Zed)

Clinejeszcze nie testowano

Tej konfiguracji nie sprawdziliśmy jeszcze z prawdziwym kluczem na działającym serwerze; opiera się na dokumentacji samego klienta.

Zostaw type ustawione na streamableHttp; bez tego Cline wraca do starszego transportu SSE.

cline_mcp_settings.json
{
  "mcpServers": {
    "rasterless": {
      "type": "streamableHttp",
      "url": "https://api.rasterless.com/mcp",
      "headers": { "Authorization": "Bearer rl_live_…" }
    }
  }
}

Oficjalna dokumentacja konfiguracji (Cline)

Plik konfiguracyjny przechowuje klucz otwartym tekstem, chyba że klient potrafi odczytać go ze zmiennej środowiskowej. Tam, gdzie klient to dokumentuje, fragment z tego korzysta; w przeciwnym razie trzymaj plik poza systemem kontroli wersji.

Narzędzie MCP nie otworzy pliku na twoim komputerze: przyjmuje publiczny adres https albo bajty pliku w base64. Aby przekonwertować plik z dysku w skrypcie, użyj polecenia curl z sekcji Szybki start.

Czego API nie robi

Pytania

Czy wynik jest taki sam jak na stronie?

Tak. API uruchamia ten sam silnik z tymi samymi opcjami co konwerter na tej stronie, więc ten sam obraz z tymi samymi ustawieniami daje te same pliki. Różni się tylko budżet czasu: 90 sekund na konwersję przez API lub MCP wobec 300 sekund na stronie, bo API zwraca jedną odpowiedź na końcu; ciężkie obrazy lepiej konwertować na stronie.

Czy mogę wywoływać API ze strony internetowej?

Wykonuj wywołania na swoim serwerze. Klucz umieszczony w kodzie przeglądarki może odczytać każdy, kto otworzy stronę, a każda konwersja wykonana tym kluczem obciąża twój limit.

Które agenty mogą korzystać z serwera MCP?

Każdy klient MCP, który potrafi połączyć się ze zdalnym serwerem przez Streamable HTTP i wysłać nagłówek Authorization. Sekcja konfiguracji wymienia klientów, których sprawdziliśmy z ich własną dokumentacją, wraz z konfiguracją, jakiej oczekuje każdy z nich.

Co dzieje się z obrazami, które wysyłam?

To samo co na stronie: linki do pobrania wygasają po 1 godzinie, a wgrane obrazy i wygenerowane pliki usuwa automatyczna reguła kasowania po 1 dniu. Nie są używane do niczego innego.

Co, jeśli konwersja jest zbyt ciężka?

Nie trwa dłużej, niż pozwala jej budżet czasu. Zamiast pliku dostajesz 422. Jeśli treść odpowiedzi sugeruje mniejszą liczbę kolorów, wyślij żądanie ponownie z tą liczbą. Jeśli image_bound ma wartość false, to nie obraz był za ciężki, tylko serwerowi zabrakło czasu: wyślij to samo żądanie ponownie za chwilę. W przeciwnym razie spróbuj z mniejszym obrazem.

Powiązane strony