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.
Skopiuj ten klucz teraz. Jest pokazywany tylko raz: przechowujemy wyłącznie jego skrót obliczony z tajnym kluczem oraz cztery pierwsze i cztery ostatnie znaki, żebyś rozpoznał go na liście.
Limit aktywnych kluczy na konto: 2.
| Klucz | Utworzono | Ostatnie użycie | Ta godzina | Dzisiaj | Akcja |
|---|
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.
export RASTERLESS_API_KEY='TWOJ_KLUCZ_API'
$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.
curl -sS https://api.rasterless.com/v1/account \
-H "Authorization: Bearer $RASTERLESS_API_KEY"
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.
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
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:
{
"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
| Endpoint | Opis |
|---|---|
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.
| Parametr | Wartości | Domyślnie | Opis |
|---|---|---|---|
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.
| HTTP | Kod | Znaczenie |
|---|---|---|
| 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
| Limit | Wartość |
|---|---|
| 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.
claude mcp add --transport http rasterless https://api.rasterless.com/mcp \
--header "Authorization: Bearer $RASTERLESS_API_KEY"
{
"mcpServers": {
"rasterless": {
"type": "http",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" }
}
}
}
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.
URL https://api.rasterless.com/mcp
Authentication none (the request header carries the key)
Request header authorization: Bearer rl_live_…
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.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${env:RASTERLESS_API_KEY}" }
}
}
}
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.
{
"mcpServers": {
"rasterless": {
"type": "http",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${RASTERLESS_API_KEY}" },
"tools": ["*"]
}
}
}
{
"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}" }
}
}
}
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.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"transport": "http",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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.
[mcp_servers.rasterless]
url = "https://api.rasterless.com/mcp"
bearer_token_env_var = "RASTERLESS_API_KEY"
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.
{
"mcpServers": {
"rasterless": {
"httpUrl": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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.
{
"context_servers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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.
{
"mcpServers": {
"rasterless": {
"type": "streamableHttp",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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
- Jeden obraz na żądanie. Nie ma endpointu, który przyjmuje folder albo archiwum obrazów.
- Brak webhooków i brak kolejki zadań: żądanie wraca, gdy konwersja się zakończy albo wyczerpie swój budżet czasu; ten budżet wynosi tu 90 sekund, a na stronie 300 sekund, więc ciężkie obrazy lepiej konwertować na stronie.
- Brak SDK. Działa każdy klient HTTP, który potrafi wysłać
multipart/form-data. - Na wejściu przyjmowane są formaty PNG, JPEG, WEBP, BMP, GIF lub AVIF; pliki SVG, PDF, TIFF i HEIC nie są akceptowane. Na wyjściu są SVG, PDF, EPS, DXF i PNG, i nic więcej.
- Brak edycji po trasowaniu: API zwraca pliki, a nie edytowalny rysunek.
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.