Desenvolvedores: a API e o servidor MCP do Rasterless
Chame o mesmo conversor por script ou agente, com uma chave bearer.
Funciona com os seus agentes favoritos
Tudo o que o conversor deste site faz está disponível por HTTP: uma imagem entra, saem os formatos que você pedir, com as mesmas opções e os mesmos limites. Um agente que fala o Model Context Protocol pode chamá-lo como ferramenta pelo servidor MCP remoto, com a mesma chave.
As tabelas desta página são geradas a partir do código que responde às requisições, então o nome de uma opção ou um limite não tem como se afastar do que o servidor aceita. Valores que ainda não estão definidos aparecem marcados como tal, em vez de serem adivinhados.
Primeiros passos
Primeiro, entre com o Google e crie uma chave de API no painel a seguir. As chaves começam com rl_live_ e são mostradas uma só vez. Mantenha a chave fora do controle de versão; os exemplos a leem de uma variável de ambiente chamada RASTERLESS_API_KEY.
Suas chaves de API
Entre com o Google nesta página para criar e gerenciar as suas chaves de API. O painel precisa de JavaScript.
Copie esta chave agora. Ela é mostrada uma só vez: guardamos apenas um hash dela com chave secreta, mais os quatro primeiros e os quatro últimos caracteres para você reconhecê-la na lista.
Até 2 chaves ativas por conta.
| Chave | Criada em | Último uso | Esta hora | Hoje | Ação |
|---|
Sua primeira chamada
1. Coloque a chave em uma variável de ambiente. Substitua o marcador pela sua chave. A variável vale até você fechar aquela janela do terminal.
export RASTERLESS_API_KEY='SUA_CHAVE_DE_API'
$env:RASTERLESS_API_KEY = 'SUA_CHAVE_DE_API'
2. Verifique a chave. GET /v1/account responde com a chave e a cota restante, e não conta como conversão. Um 401 api_key_invalid costuma indicar que parte da chave se perdeu ao copiá-la.
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. Converta um arquivo do seu computador. Depois do @ vem o caminho da imagem; ./logo.png é o arquivo logo.png na pasta em que o terminal está. No PowerShell, digite curl.exe: no Windows PowerShell, curl sozinho executa outro comando. O curl.exe vem com o Windows 10 a partir da build 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. Leia a resposta. Este exemplo tem os campos e os tipos de uma resposta real; os valores vêm de uma conversão de teste e os links de download são ilustrativos:
{
"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
}
A resposta é um JSON: outputs traz um link de download assinado para cada formato pedido, e colors_used, o número de cores que o motor usou. Os links expiram depois de 1 hora, então baixe os arquivos assim que a resposta chegar, em vez de guardar os links. Peça um só formato e acrescente ?return=file ao endereço para receber o próprio arquivo em vez do JSON.
id identifica o trabalho e seconds é quanto tempo a conversão levou. shapes conta as formas no resultado, preview_url é uma prévia em PNG com a mesma validade dos links, e colors_auto.detected diz se colors=auto encontrou a contagem na imagem ou usou o padrão.
Autenticação
Toda requisição leva a chave num cabeçalho Authorization: Bearer por HTTPS. A API não define cookie nem mostra verificação no navegador: a chave é a identidade inteira, então trate-a como uma senha e mantenha as chamadas no seu servidor. Uma chave no código do navegador ou num app de celular é uma chave que qualquer pessoa pode ler. Uma requisição sem chave retorna 401 api_key_missing; uma chave errada, 401 api_key_invalid; e uma chave revogada, 401 api_key_revoked. A revogação vale a partir da próxima requisição, e cada conta pode ter um número limitado de chaves ativas ao mesmo tempo.
Se suspendermos ou revogarmos uma das suas chaves com base nos termos de serviço, ela aparece como revogada na sua lista de chaves, e escrevemos para o e-mail da sua conta Google.
Endpoints e parâmetros
| Endpoint | Descrição |
|---|---|
POST /v1/vectorize |
Converte uma imagem e retorna um link assinado por formato. |
GET /v1/options |
Lista os valores aceitos de cada opção. |
GET /v1/account |
Mostra a cota da chave e quanto dela ainda resta. |
POST /v1/vectorize recebe multipart/form-data: a imagem num campo chamado image e as opções como campos de formulário comuns. Os valores são os eixos que GET /v1/options retorna, e a tabela é montada a partir das mesmas constantes, então não tem como discordar do servidor.
| Parâmetro | Valores | Padrão | Descrição |
|---|---|---|---|
image obrigatório |
PNG, JPEG, WEBP, BMP, GIF, AVIF | — | A imagem, como campo de arquivo multipart. Os primeiros bytes decidem o tipo, não o nome do arquivo. |
formats |
svg, pdf, eps, dxf, png | svg | Um ou mais, separados por vírgulas; a resposta traz um link por formato. |
colors |
2–64, auto | auto | Tamanho da paleta; 2 dá um traçado em preto e branco. auto lê o número a partir de um gráfico de cores chapadas e, se não conseguir, usa 26. |
svg_version |
svg_1_0, svg_1_1, svg_tiny_1_2 | svg_1_1 | A versão escrita no elemento raiz do SVG. |
draw_style |
fill_shapes, stroke_shapes, stroke_edges | fill_shapes | Formas preenchidas, formas contornadas ou só as bordas. No DXF as duas primeiras dão os mesmos contornos fechados; só as bordas dá caminhos abertos. |
shape_stacking |
cutouts, stacked | cutouts | Os recortes furam as formas que estão embaixo; o empilhado pinta uma sobre a outra. |
group_by |
none, color, parent, layer | none | Só o agrupamento do SVG: nenhum, por cor, por forma-mãe ou por camada. |
size_mm |
WxH, 1–5000 mm | — | Tamanho físico, como 150x150. Vale para SVG, PDF, EPS e DXF; deixe vazio para manter unidades em pixels. |
denoise |
0–50 | 0 | Intensidade de um pré-filtro que preserva as bordas; 0 o desliga. Não disponível na ferramenta MCP. |
group_by muda apenas como um SVG agrupa os seus caminhos. No DXF, fill_shapes e stroke_shapes escrevem os mesmos contornos fechados (LWPOLYLINE e SPLINE de grau 3) numa camada FILL_ por cor; stroke_edges escreve em vez disso a rede de bordas, cada limite uma vez como caminho aberto, em camadas EDGE_. O DXF é escrito como R2010 (AC1024) com unidades em milímetros.
Erros
Um erro retorna um JSON sob error: um code, um type que agrupa os códigos em famílias (bad_input, auth, quota, too_complex, timeout, busy, not_found, server), os valores por trás dele em params e uma message de reserva em inglês. Decida pelo type, registre o code no log e nunca analise o texto da mensagem. Um corpo típico é {"error": {"code": "file_too_large", "type": "bad_input", "params": {"max_mb": 25}}} com a mensagem ao lado.
Uma mudança em /v1 que quebraria uma requisição que funciona hoje é anunciada nesta página com pelo menos 30 dias de antecedência. Acréscimos que mantêm como estão as requisições que funcionam, como um novo campo opcional, podem aparecer sem aviso.
| HTTP | Código | Significado |
|---|---|---|
| 400 | image_missing |
Nenhum arquivo no campo image. |
| 400 | multipart_invalid |
Não foi possível ler o corpo como multipart/form-data. |
| 400 | unsupported_input |
A extensão do arquivo não é uma entrada aceita. |
| 400 | not_an_image |
Os primeiros bytes do arquivo não são de uma imagem raster aceita. |
| 400 | invalid_option |
Uma opção tem um valor fora da sua lista; params indica qual. |
| 400 | size_mm_format |
size_mm não está escrito como LxA (largura x altura), por exemplo 150x150. |
| 400 | size_mm_range |
Um lado de size_mm está fora do intervalo aceito. |
| 400 | return_needs_one_format |
?return=file foi pedido com mais de um formato. |
| 401 | api_key_missing |
Nenhuma chave no cabeçalho Authorization. |
| 401 | api_key_invalid |
A chave não é válida. |
| 401 | api_key_revoked |
A chave foi revogada; crie uma nova. |
| 403 | key_suspended |
Uma chave da conta está suspensa; não é possível criar uma chave nova. |
| 409 | key_limit |
A conta já tem o número máximo de chaves ativas. |
| 413 | file_too_large |
O envio passa do limite de tamanho de arquivo. |
| 413 | image_too_large |
A imagem decodificada passa do limite de pixels. |
| 422 | too_complex |
O trabalho não foi iniciado: a estimativa passa do orçamento de tempo ou (image_bound false) sobrou pouco tempo no servidor para esta requisição. Sugere-se um número menor de cores se algum passar na estimativa. |
| 422 | timeout |
A conversão passou do seu orçamento de tempo; menos cores não ajudam, uma imagem menor pode ajudar. |
| 429 | busy |
Todos os processos de conversão estão ocupados; tente de novo depois do tempo indicado no cabeçalho Retry-After. |
| 429 | quota_hourly |
A chave usou a sua cota por hora. |
| 429 | quota_daily |
A chave usou a sua cota diária. |
| 429 | quota_url_fetch |
A chave usou suas buscas de image_url desta hora (ferramenta MCP). |
| 429 | quota_requests |
A chave enviou seu número de requisições de conversão desta hora, qualquer que seja o resultado; tente de novo após o tempo do cabeçalho Retry-After. |
| 429 | key_create_limit |
A conta já usou sua cota de chaves novas das últimas 24 horas; tente de novo depois do tempo indicado no cabeçalho Retry-After. |
Com 429 busy, espere o tempo indicado no cabeçalho Retry-After e envie a requisição de novo.
Com 422 too_complex, a conversão nem começou, e error.image_bound diz por quê. Se for true, a própria imagem passa do limite. Se error.suggested_n_colors for então um número, é um número menor de cores cuja estimativa conferimos com os limites que uma nova requisição encontra, em geral o maior que passa; uma nova tentativa com esse número passa por essa verificação. É uma estimativa, não uma promessa: a nova tentativa ainda pode terminar em timeout. Se o valor for null e fewer_colors_help for false, a estimativa fica acima do limite mesmo com 2 cores; menos cores não ajudam, uma imagem menor talvez ajude. Se os dois forem null, não foi possível calcular uma sugestão.
Se image_bound for false, o motivo não é a imagem: faltou tempo ao servidor para esta requisição. suggested_n_colors e fewer_colors_help vêm os dois como null, e a mesma requisição pode ser enviada de novo daqui a pouco.
Com 422 timeout, a conversão começou e passou do seu orçamento de tempo. O número de cores quase não muda quanto tempo uma conversão leva, então o corpo não sugere um número de cores: suggested_n_colors é null e fewer_colors_help é false. Uma imagem menor só ajuda abaixo de 1,5 megapixel, porque imagens maiores já são traçadas nesse tamanho; tente mais ou menos a metade disso (por exemplo, 1000 × 750 px) ou reduza o ruído e a textura. image_bound só aparece com too_complex.
Um timeout devolve a conversão à cota da chave (quota_refunded: true): uma vez por imagem a cada hora e no máximo 2 vezes por chave em cada hora cheia do relógio; acima disso, o corpo traz quota_refunded: false.
Raramente uma conversão passa do seu orçamento de tempo e a conexão se encerra em cerca de 100 segundos com HTTP 524 e sem corpo JSON; trate isso como um timeout.
Limites e cota
| Limite | Valor |
|---|---|
| Conversões por chave, por hora | 20 |
| Conversões por chave, por dia | 100 |
| Chaves ativas por conta | 2 |
| Chaves novas por conta a cada 24 horas, depois das 2 primeiras | 1 |
| Buscas de image_url pelo MCP, por chave e por hora | 120 |
| Requisições de conversão por chave e por hora (API e MCP) | 200 |
| Tamanho do arquivo | 25 MB |
| Tamanho da imagem decodificada | 40 MP |
| Orçamento de tempo por conversão | 90 s |
| Validade do link de download | 1 h |
| size_mm, por lado | 1–5000 mm |
A linha de buscas conta cada vez que a ferramenta MCP vectorize_image baixa uma image_url. A contagem é feita antes de o download começar, então um download que falha ou que traz algo que não é imagem também conta. Esse contador é separado da cota de conversões.
Imagens com mais de 1,5 megapixel são reduzidas antes do traçado, então o tamanho em pixels da saída segue a cópia reduzida; defina size_mm quando precisar de dimensões físicas. Uma imagem por requisição.
Preço
As chaves de API e as conversões que você faz com elas dentro da cota acima são gratuitas durante o beta. Nada será cobrado sem o seu acordo claro antes (termos de serviço, seção 4).
Servidor MCP
O servidor MCP permite que um agente chame o conversor como ferramenta. Ele fala Streamable HTTP em https://api.rasterless.com/mcp e aceita a mesma chave bearer, no mesmo cabeçalho. Oferece duas ferramentas: vectorize_image converte uma imagem, enviada como image_url (um endereço https público) ou como image_base64, com as opções da tabela de parâmetros; get_options retorna os valores aceitos e a cota que ainda resta à chave, para que o agente possa escolher. Escolha o seu cliente para ver a configuração:
Claude Code
O comando guarda a chave nas suas configurações de usuário. A forma .mcp.json a lê do ambiente, então o arquivo pode ser versionado. Uma conversão longa pode passar do tempo limite padrão das ferramentas; MCP_TOOL_TIMEOUT=120000 aumenta esse limite.
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 Desktopainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
Os cabeçalhos de requisição em conectores personalizados estão em beta e só algumas organizações os têm. Se a seção Request headers não aparecer, este cliente ainda não consegue enviar a chave. O conector é compartilhado por todos na organização, com uma chave só.
URL https://api.rasterless.com/mcp
Authentication none (the request header carries the key)
Request header authorization: Bearer rl_live_…
Cursorainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
O Cursor lê a chave da variável de ambiente, então o arquivo não guarda nenhum segredo.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${env:RASTERLESS_API_KEY}" }
}
}
}
Visual Studio Codeainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
O primeiro arquivo é o formato atual. O antigo .vscode/mcp.json pede a chave e a mantém fora do arquivo; ainda funciona, mas está sendo descontinuado.
{
"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}" }
}
}
}
Windsurfainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
As configurações de agente do Windsurf agora ficam no Devin Desktop. O arquivo .local.json fica fora do controle de versão.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"transport": "http",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Codex CLIainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
O Codex envia o valor da variável como token bearer; o arquivo em si não guarda nenhum segredo.
[mcp_servers.rasterless]
url = "https://api.rasterless.com/mcp"
bearer_token_env_var = "RASTERLESS_API_KEY"
Gemini CLIainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
Use httpUrl: neste arquivo, url significa o transporte SSE mais antigo.
{
"mcpServers": {
"rasterless": {
"httpUrl": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Zedainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
Sem um cabeçalho Authorization, o Zed inicia um fluxo de login no lugar, então mantenha o cabeçalho.
{
"context_servers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Clineainda não testado
Ainda não testamos esta configuração no servidor em produção com uma chave real; ela segue a documentação do próprio cliente.
Mantenha type definido como streamableHttp; sem isso, o Cline volta ao transporte SSE mais antigo.
{
"mcpServers": {
"rasterless": {
"type": "streamableHttp",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
Um arquivo de configuração guarda a chave em texto puro, a menos que o cliente consiga lê-la de uma variável de ambiente. Quando o cliente documenta isso, o trecho usa esse recurso; caso contrário, mantenha o arquivo fora do controle de versão.
A ferramenta MCP não consegue abrir um arquivo do seu computador: ela recebe um endereço https público ou os bytes do arquivo em base64. Para converter um arquivo do seu disco a partir de um script, use o comando curl de Primeiros passos.
O que a API não faz
- Uma imagem por requisição. Não existe endpoint que receba uma pasta ou um arquivo compactado de imagens.
- Não há webhooks nem fila de tarefas: a requisição retorna quando a conversão termina ou quando esgota o seu orçamento de tempo; esse orçamento é de 90 segundos aqui e de 300 segundos no site, então imagens pesadas convertem melhor no site.
- Não há SDK. Qualquer cliente HTTP que consiga enviar
multipart/form-datafunciona. - As entradas são PNG, JPEG, WEBP, BMP, GIF ou AVIF; arquivos SVG, PDF, TIFF e HEIC não são aceitos. As saídas são SVG, PDF, EPS, DXF e PNG, e nada mais.
- Sem edição depois do traçado: a API retorna arquivos, não um desenho editável.
Perguntas
A saída é a mesma do site?
Sim. A API roda o mesmo motor, com as mesmas opções do conversor deste site, então a mesma imagem com as mesmas configurações gera os mesmos arquivos. Só o orçamento de tempo é diferente: 90 segundos por conversão pela API ou pelo MCP contra 300 segundos no site, porque a API devolve uma única resposta no fim; imagens pesadas convertem melhor no site.
Posso chamar a API a partir de uma página web?
Mantenha as chamadas no seu servidor. Uma chave colocada no código do navegador pode ser lida por qualquer pessoa que abrir a página, e cada conversão feita com ela conta na sua cota.
Quais agentes podem usar o servidor MCP?
Qualquer cliente MCP que consiga se conectar a um servidor remoto por Streamable HTTP e enviar um cabeçalho Authorization. A seção de configuração lista os clientes que conferimos com a documentação de cada um, com a configuração que cada um espera.
O que acontece com as imagens que eu envio?
O mesmo que no site: os links de download expiram depois de 1 hora, e as imagens enviadas e os arquivos gerados são removidos por uma regra automática de exclusão de 1 dia. Eles não são usados para mais nada.
E se uma conversão for pesada demais?
Ela não passa do seu orçamento de tempo. Em vez de um arquivo, você recebe um 422. Se o corpo sugerir um número menor de cores, envie a requisição de novo com esse número. Se image_bound for false, não foi a imagem que pesou, faltou tempo ao servidor: envie a mesma requisição de novo daqui a pouco. Caso contrário, tente uma imagem menor.