Rasterless

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.

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.

bash
export RASTERLESS_API_KEY='SUA_CHAVE_DE_API'
PowerShell
$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.

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

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. 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:

Resposta de exemplo
{
  "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

EndpointDescriçã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.

Campos de formulário de POST /v1/vectorize
ParâmetroValores PadrãoDescriçã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.

HTTPCódigoSignificado
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

LimiteValor
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.

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

Documentação oficial de configuração (Claude Code)

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ó.

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

Documentação oficial de configuração (Claude Desktop)

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.

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

Documentação oficial de configuração (Cursor)

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.

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

Documentação oficial de configuração (Visual Studio Code)

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.

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

Documentação oficial de configuração (Windsurf)

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.

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

Documentação oficial de configuração (Codex CLI)

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.

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

Documentação oficial de configuração (Gemini CLI)

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.

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

Documentação oficial de configuração (Zed)

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.

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

Documentação oficial de configuração (Cline)

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

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.

Páginas relacionadas