Rasterless

Geliştiriciler: Rasterless API'si ve MCP sunucusu

Aynı dönüştürücüyü bir betikten ya da bir ajandan, bir bearer anahtarla çağırın.

Sevdiğiniz ajanlarla çalışır

Bu sitedeki dönüştürücünün yaptığı her şey HTTP üzerinden de kullanılabilir: bir görsel girer, istediğiniz formatlar çıkar; seçenekler de sınırlar da aynıdır. Model Context Protocol destekleyen bir ajan, aynı anahtarla uzak MCP sunucusu üzerinden dönüştürücüyü bir araç olarak çağırabilir.

Bu sayfadaki tablolar, istekleri yanıtlayan koddan üretilir; bu yüzden bir seçenek adı ya da bir sınır, sunucunun kabul ettiğinden sapamaz. Henüz kesinleşmemiş değerler tahmin edilmez, kesinleşmedikleri açıkça işaretlenir.

Hızlı başlangıç

Önce Google ile giriş yapın ve hemen ardından gelen panelde bir API anahtarı oluşturun. Anahtarlar rl_live_ ile başlar ve yalnızca bir kez gösterilir. Anahtarı sürüm denetiminin dışında tutun; örnekler onu RASTERLESS_API_KEY adlı bir ortam değişkeninden okur.

API anahtarlarınız

API anahtarlarınızı oluşturmak ve yönetmek için bu sayfada Google ile giriş yapın. Panel JavaScript gerektirir.

İlk çağrınız

1. Anahtarı bir ortam değişkenine koyun. Yer tutucunun yerine kendi anahtarınızı yazın. Değişken, o terminal penceresini kapatana kadar geçerlidir.

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

2. Anahtarı doğrulayın. GET /v1/account anahtarı ve kalan kotasını döndürür; dönüşüm sayılmaz. 401 api_key_invalid genellikle anahtarın bir kısmının kopyalanırken kaybolduğu anlamına gelir.

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. Bilgisayarınızdaki bir dosyayı dönüştürün. @ işaretinden sonraki kısım görselin yoludur; ./logo.png, terminalin bulunduğu klasördeki logo.png dosyasıdır. PowerShell'de curl.exe yazın: Windows PowerShell'de tek başına curl başka bir komutu çalıştırır. curl.exe Windows 10'da 17063 derlemesinden beri yüklü gelir.

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. Yanıtı okuyun. Bu örnek gerçek bir yanıtın alanlarını ve türlerini taşır; değerler bir deneme dönüşümünden alındı, indirme bağlantıları temsilîdir:

Örnek yanıt
{
  "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
}

Yanıt bir JSON'dur: outputs istediğiniz her format için imzalı bir indirme bağlantısı, colors_used ise motorun kullandığı renk sayısını taşır. Bağlantılar 1 saat sonra geçersiz olur; bu yüzden bağlantıları saklamak yerine dosyaları yanıt geldiğinde indirin. Yalnızca bir format isteyip adrese ?return=file eklerseniz JSON yerine dosyanın kendisini alırsınız.

id işi adlandırır, seconds dönüşümün ne kadar sürdüğünü gösterir. shapes sonuçtaki şekil sayısıdır, preview_url bağlantılarla aynı ömre sahip bir PNG önizlemedir; colors_auto.detected ise colors=auto değerinin renk sayısını görselde bulup bulmadığını ya da varsayılanı kullandığını söyler.

Kimlik doğrulama

Her istek anahtarı HTTPS üzerinden bir Authorization: Bearer başlığında taşır. API çerez kurmaz ve tarayıcı doğrulaması göstermez: kimliğin tamamı anahtardır, bu yüzden ona bir parola gibi davranın ve çağrıları kendi sunucunuzda tutun. Tarayıcı kodundaki ya da bir mobil uygulamadaki anahtar, herkesin okuyabileceği bir anahtardır. Anahtarsız bir istek 401 api_key_missing, yanlış bir anahtar 401 api_key_invalid, iptal edilmiş bir anahtar ise 401 api_key_revoked döner. İptal bir sonraki istekte geçerli olur ve her hesap aynı anda sınırlı sayıda etkin anahtar tutabilir.

Kullanım koşulları gereği anahtarlarınızdan birini askıya alır veya iptal edersek, anahtar listenizde iptal edilmiş olarak görünür ve Google hesabınızın e-posta adresine yazarız.

Uç noktalar ve parametreler

Uç noktaAçıklama
POST /v1/vectorize Bir görseli dönüştürür ve format başına imzalı bir bağlantı döndürür.
GET /v1/options Her seçeneğin kabul edilen değerlerini listeler.
GET /v1/account Anahtarın kotasını ve ne kadarının kaldığını gösterir.

POST /v1/vectorize isteği multipart/form-data alır: görsel image adlı bir alanda, seçenekler sıradan form alanları olarak gelir. Değerler GET /v1/options uç noktasının döndürdüğü eksenlerdir ve tablo aynı sabitlerden kurulur, yani sunucuyla çelişemez.

POST /v1/vectorize form alanları
ParametreDeğerler VarsayılanAçıklama
image zorunlu PNG, JPEG, WEBP, BMP, GIF, AVIF — Çok parçalı (multipart) dosya alanında gönderilen görsel. Türünü dosya adı değil, dosyanın ilk baytları belirler.
formats svg, pdf, eps, dxf, png svg Virgülle ayrılmış bir ya da daha fazla format; yanıt her format için bir bağlantı taşır.
colors 2–64, auto auto Palet boyutu; 2 siyah-beyaz bir iz verir. auto, düz renkli bir grafikte sayıyı görselden okur, okuyamazsa 26 kullanır.
svg_version svg_1_0, svg_1_1, svg_tiny_1_2 svg_1_1 SVG kök öğesine yazılan sürüm.
draw_style fill_shapes, stroke_shapes, stroke_edges fill_shapes Dolgu şekiller, kontur şekiller ya da yalnızca kenarlar. DXF'te ilk ikisi aynı kapalı konturları verir; yalnızca kenarlar açık yollar verir.
shape_stacking cutouts, stacked cutouts Delikli (cut-outs) alttaki şekillerde delik açar; üst üste (stacked) şekilleri birbirinin üzerine boyar.
group_by none, color, parent, layer none Yalnız SVG gruplaması: yok, renge göre, kapsayan şekle göre ya da katmana göre.
size_mm WxH, 1–5000 mm — 150x150 gibi fiziksel boyut. SVG, PDF, EPS ve DXF'e uygulanır; piksel birimlerini korumak için boş bırakın.
denoise 0–50 0 Kenarları koruyan bir ön filtrenin gücü; 0 filtreyi kapatır. MCP aracında bulunmaz.

group_by yalnızca bir SVG'nin yollarını nasıl grupladığını değiştirir. DXF'te fill_shapes ve stroke_shapes aynı kapalı konturları (LWPOLYLINE ve üçüncü dereceden SPLINE) renk başına bir FILL_ katmanında yazar; stroke_edges ise kenar ağını yazar: her sınır bir kez, açık yol olarak, EDGE_ katmanlarında. DXF milimetre birimiyle R2010 (AC1024) olarak yazılır.

Hatalar

Bir hata, error altında bir JSON döndürür: bir code, kodları ailelere ayıran bir type (bad_input, auth, quota, too_complex, timeout, busy, not_found, server), onun arkasındaki değerleri taşıyan params ve İngilizce yazılmış yedek bir message. Dallanmayı type üzerinden yapın, code değerini günlüğe yazın ve mesaj metnini hiçbir zaman ayrıştırmayın. Tipik bir gövde {"error": {"code": "file_too_large", "type": "bad_input", "params": {"max_mb": 25}}} biçimindedir, mesaj da yanında gelir.

/v1'de bugün çalışan bir isteği bozacak bir değişiklik, yürürlüğe girmesinden en az 30 gün önce bu sayfada duyurulur. Çalışan istekleri olduğu gibi bırakan eklemeler, örneğin yeni ve isteğe bağlı bir alan, bildirimsiz gelebilir.

HTTPKodAnlamı
400 image_missing image alanında dosya yok.
400 multipart_invalid Gövde multipart/form-data olarak okunamadı.
400 unsupported_input Dosya uzantısı kabul edilen bir girdi değil.
400 not_an_image Dosyanın ilk baytları kabul edilen bir raster görsele ait değil.
400 invalid_option Bir seçeneğin değeri kendi listesinin dışında; params hangisi olduğunu söyler.
400 size_mm_format size_mm en x boy biçiminde yazılmamış; örneğin 150x150 olmalı.
400 size_mm_range size_mm'nin bir kenarı kabul edilen aralığın dışında.
400 return_needs_one_format ?return=file birden fazla formatla birlikte istendi.
401 api_key_missing Authorization başlığında anahtar yok.
401 api_key_invalid Anahtar geçerli değil.
401 api_key_revoked Anahtar iptal edildi; yeni bir anahtar oluşturun.
403 key_suspended Hesaptaki bir anahtar askıya alındı; yeni anahtar oluşturulamaz.
409 key_limit Hesap, etkin anahtar sayısının üst sınırına zaten ulaştı.
413 file_too_large Yüklenen dosya, dosya boyutu sınırını aşıyor.
413 image_too_large Çözülmüş görsel, piksel sınırını aşıyor.
422 too_complex İş başlamadı: tahmini süre bütçesinin üstünde ya da (image_bound false) sunucuda bu istek için yeterli süre kalmamıştı. Tahminden geçen daha düşük bir renk sayısı varsa önerilir.
422 timeout Dönüşüm süre bütçesini aştı; daha az renk işe yaramaz, daha küçük bir görsel işe yarayabilir.
429 busy Bütün işçiler meşgul; Retry-After başlığındaki süreden sonra yeniden deneyin.
429 quota_hourly Anahtar saatlik kotasını doldurdu.
429 quota_daily Anahtar günlük kotasını doldurdu.
429 quota_url_fetch Anahtar saatlik image_url getirme hakkını kullandı (MCP aracı).
429 quota_requests Anahtar, sonuçları ne olursa olsun saatlik dönüşüm isteği sayısını doldurdu; Retry-After başlığındaki süreden sonra tekrar deneyin.
429 key_create_limit Hesap son 24 saatteki yeni anahtar hakkını kullandı; Retry-After başlığındaki süreden sonra yeniden deneyin.

429 busy aldığınızda Retry-After başlığındaki süre kadar bekleyin ve isteği yeniden gönderin.

422 too_complex aldığınızda dönüşüm hiç başlamamıştır; nedenini error.image_bound söyler. true ise görselin kendisi sınırın üstündedir. O zaman error.suggested_n_colors bir sayıysa, tahminini yeni bir isteğin karşılaşacağı sınırlara karşı denediğimiz daha düşük bir renk sayısıdır; çoğunlukla geçenlerin en büyüğüdür ve o sayıyla yeniden deneme bu kontrolden geçer. Bu bir tahmindir, söz değildir: yeniden deneme yine timeout ile bitebilir. Değer null ve fewer_colors_help false ise tahmin 2 renkte bile sınırın üstünde kalır; daha az renk işe yaramaz, daha küçük bir görsel yarayabilir. İkisi de null ise öneri hesaplanamamıştır.

image_bound false ise sebep görsel değildir, sunucunun bu istek için ayırabileceği süre yetmemiştir: suggested_n_colors ve fewer_colors_help ikisi de null olur ve aynı istek biraz sonra yeniden gönderilebilir.

422 timeout aldığınızda dönüşüm başlamış ve süre bütçesini aşmıştır. Renk sayısı dönüşüm süresini neredeyse değiştirmediği için gövde renk sayısı önermez: suggested_n_colors null, fewer_colors_help false olur. Daha küçük bir görsel ancak 1,5 megapikselin altında işe yarar, çünkü daha büyük görseller zaten bu boyutta izlenir; bunun yarısı kadarını (ör. 1000 × 750 piksel) deneyin ya da gürültüyü ve dokuyu azaltın. image_bound yalnız too_complex gövdesinde bulunur.

timeout dönüşümü anahtarın kotasına geri verir (quota_refunded: true): aynı görsel için saatte bir kez ve anahtar başına her saat içinde (saat başından saat başına) en çok 2 kez; bunun ötesinde gövde quota_refunded: false der.

Nadiren bir dönüşüm bütçesini aşar ve bağlantı yaklaşık 100 saniyede, JSON gövdesi olmadan HTTP 524 ile kapanır; bunu timeout gibi ele alın.

Sınırlar ve kota

SınırDeğer
Anahtar başına saatlik dönüşüm 20
Anahtar başına günlük dönüşüm 100
Hesap başına etkin anahtar 2
İlk 2 anahtardan sonra hesap başına 24 saatte yeni anahtar 1
Anahtar başına saatlik image_url getirme (MCP) 120
Anahtar başına saatlik dönüşüm isteği (API ve MCP) 200
Dosya boyutu 25 MB
Çözülmüş görsel boyutu 40 MP
Dönüşüm başına süre bütçesi 90 s
İndirme bağlantısının ömrü 1 h
size_mm, kenar başına 1–5000 mm

Getirme satırı, MCP aracı vectorize_image bir image_url indirdiği her seferi sayar. Sayım indirme başlamadan önce yapılır; bu yüzden başarısız olan ya da görsel olmayan bir şey döndüren indirme de sayılır. Bu sayaç dönüşüm kotasından ayrıdır.

1,5 megapikselin üstündeki görseller izlenmeden önce küçültülür, bu yüzden çıktının piksel boyutu küçültülmüş kopyaya göre belirlenir; fiziksel ölçü gerektiğinde size_mm verin. İstek başına bir görsel.

Fiyatlandırma

API anahtarları ve onlarla yukarıdaki kota içinde yaptığınız dönüştürmeler beta boyunca ücretsizdir. Açık onayınız olmadan hiçbir ücret alınmaz (kullanım koşulları, 4. madde).

MCP sunucusu

MCP sunucusu, bir ajanın dönüştürücüyü bir araç olarak çağırmasını sağlar. https://api.rasterless.com/mcp adresinde Streamable HTTP taşımasını kullanır ve aynı bearer anahtarı aynı başlıkta alır. İki araç sunar: vectorize_image, image_url (herkese açık bir https adresi) ya da image_base64 olarak verilen bir görseli parametre tablosundaki seçeneklerle dönüştürür; get_options ise ajanın seçim yapabilmesi için kabul edilen değerleri ve anahtarın kalan kotasını döndürür. Kurulum için istemcinizi seçin:

Claude Code

Komut, anahtarı kullanıcı ayarlarınıza kaydeder. .mcp.json biçimi anahtarı ortamdan okur, bu yüzden dosyayı depoya commit edebilirsiniz. Uzun bir dönüşüm varsayılan araç zaman aşımını aşabilir; MCP_TOOL_TIMEOUT=120000 bu süreyi yükseltir.

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}" }
    }
  }
}

Resmî kurulum belgeleri (Claude Code)

Claude Desktophenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

Özel bağlayıcılardaki istek başlıkları beta aşamasında ve yalnızca bazı kuruluşlarda açık. Request headers bölümü görünmüyorsa bu istemci anahtarı henüz gönderemez. Bağlayıcıyı kuruluştaki herkes paylaşır ve hepsi aynı anahtarı kullanır.

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_…

Resmî kurulum belgeleri (Claude Desktop)

Cursorhenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

Cursor anahtarı ortam değişkeninden okur, bu yüzden dosyada hiçbir gizli bilgi bulunmaz.

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

Resmî kurulum belgeleri (Cursor)

Visual Studio Codehenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

İlk dosya güncel biçimdir. Eski .vscode/mcp.json anahtarı sorar ve dosyanın dışında tutar; hâlâ çalışıyor ama kullanımdan kaldırılıyor.

.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}" }
    }
  }
}

Resmî kurulum belgeleri (Visual Studio Code)

Windsurfhenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

Windsurf'ün ajan ayarları artık Devin Desktop altında. .local.json dosyası sürüm denetiminin dışında tutulur.

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

Resmî kurulum belgeleri (Windsurf)

Codex CLIhenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

Codex, değişkenin değerini bearer token olarak gönderir; dosyanın kendisinde hiçbir gizli bilgi bulunmaz.

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

Resmî kurulum belgeleri (Codex CLI)

Gemini CLIhenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

Bu dosyada httpUrl: kullanın; burada url, eski SSE taşımasını ifade eder.

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

Resmî kurulum belgeleri (Gemini CLI)

Zedhenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

Authorization başlığı olmadığında Zed bunun yerine bir oturum açma akışı başlatır; bu yüzden başlığı yerinde tutun.

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

Resmî kurulum belgeleri (Zed)

Clinehenüz denenmedi

Bu kurulumu canlı sunucuya karşı gerçek bir anahtarla henüz denemedik; istemcinin kendi belgelerine dayanıyor.

type değerini streamableHttp olarak bırakın; bu değer olmadan Cline eski SSE taşımasına geri döner.

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

Resmî kurulum belgeleri (Cline)

İstemci anahtarı bir ortam değişkeninden okuyamıyorsa yapılandırma dosyası anahtarı düz metin olarak tutar. Bir istemci bunu belgelediyse parçacık o yolu kullanır; belgelemediyse dosyayı sürüm denetiminin dışında tutun.

MCP aracı bilgisayarınızdaki bir dosyayı açamaz: herkese açık bir https adresi ya da dosyanın baytlarını base64 olarak alır. Diskinizdeki bir dosyayı bir betikten dönüştürmek için hızlı başlangıçtaki curl komutunu kullanın.

API'nin yapmadıkları

Sorular

Çıktı web sitesindekiyle aynı mı?

Evet. API, bu sitedeki dönüştürücüyle aynı motoru aynı seçeneklerle çalıştırır; yani aynı görsel, aynı ayarlarla aynı dosyaları verir. Yalnız süre bütçesi farklı: API ya da MCP dönüşümü başına 90 saniye, sitede 300 saniye, çünkü API tek bir yanıtı iş bitince döndürür; ağır görselleri sitede dönüştürmek daha iyi.

API'yi bir web sayfasından çağırabilir miyim?

Çağrıları kendi sunucunuzda tutun. Tarayıcı koduna konan bir anahtarı sayfayı açan herkes okuyabilir ve o anahtarla yapılan her dönüşüm sizin kotanızdan düşer.

MCP sunucusunu hangi ajanlar kullanabilir?

Streamable HTTP üzerinden uzak bir sunucuya bağlanabilen ve Authorization başlığı gönderebilen her MCP istemcisi. Kurulum bölümü, kendi belgelerine göre denetlediğimiz istemcileri ve her birinin beklediği yapılandırmayı listeler.

Gönderdiğim görsellere ne oluyor?

Sitedekiyle aynı şey: indirme bağlantıları 1 saat sonra geçersiz olur; yüklenen görseller ve üretilen dosyalar 1 günlük otomatik silme kuralıyla kaldırılır. Başka hiçbir amaçla kullanılmazlar.

Bir dönüşüm çok ağırsa ne olur?

Süre bütçesinin ötesinde çalışmaz. Dosya yerine 422 alırsınız. Gövde daha düşük bir renk sayısı öneriyorsa isteği o sayıyla yeniden gönderin. image_bound false ise görsel ağır değil, sunucunun süresi yetmemiştir: aynı isteği biraz sonra yeniden gönderin. Aksi hâlde daha küçük bir görsel deneyin.

İlgili sayfalar