Rasterless

Desarrolladores: la API y el servidor MCP de Rasterless

Llama al mismo convertidor desde un script o un agente con una clave bearer.

Funciona con tus agentes favoritos

Todo lo que hace el convertidor de este sitio está disponible por HTTP: entra una imagen y salen los formatos que pidas, con las mismas opciones y los mismos límites. Un agente que hable el Model Context Protocol puede llamarlo como herramienta a través del servidor MCP remoto, con la misma clave.

Las tablas de esta página se generan a partir del código que responde a las peticiones, así que el nombre de una opción o un límite no puede apartarse de lo que acepta el servidor. Los valores que aún no están decididos aparecen marcados como tales en lugar de adivinarse.

Primeros pasos

Primero, inicia sesión con Google y crea una clave de API en el panel siguiente. Las claves empiezan por rl_live_ y se muestran una sola vez. Mantén la clave fuera del control de versiones; los ejemplos la leen de una variable de entorno llamada RASTERLESS_API_KEY.

Tus claves de API

Inicia sesión con Google en esta página para crear y gestionar tus claves de API. El panel necesita JavaScript.

Tu primera llamada

1. Guarda la clave en una variable de entorno. Sustituye el marcador por tu clave. La variable dura hasta que cierres esa ventana del terminal.

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

2. Comprueba la clave. GET /v1/account responde con la clave y su cuota restante, y no cuenta como conversión. Un 401 api_key_invalid suele indicar que una parte de la clave se perdió al copiarla.

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. Convierte un archivo de tu ordenador. Tras @ va la ruta de la imagen; ./logo.png es el archivo logo.png de la carpeta en la que está el terminal. En PowerShell, escribe curl.exe: en Windows PowerShell, curl a secas ejecuta otro comando. curl.exe viene con Windows 10 desde la compilación 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. Lee la respuesta. Este ejemplo tiene los campos y tipos de una respuesta real; los valores proceden de una conversión de prueba y los enlaces de descarga son ilustrativos:

Respuesta de ejemplo
{
  "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
}

La respuesta es un JSON: outputs contiene un enlace de descarga firmado para cada formato que pediste, y colors_used, el número de colores que usó el motor. Los enlaces caducan al cabo de 1 hora, así que descarga los archivos en cuanto llegue la respuesta en lugar de guardar los enlaces. Pide un solo formato y añade ?return=file a la dirección para recibir el propio archivo en lugar del JSON.

id identifica el trabajo y seconds es lo que tardó la conversión. shapes cuenta las formas del resultado, preview_url es una vista previa en PNG con la misma vigencia que los enlaces, y colors_auto.detected indica si colors=auto encontró el número en la imagen o usó el valor por defecto.

Autenticación

Cada petición lleva la clave en una cabecera Authorization: Bearer sobre HTTPS. La API no pone ninguna cookie ni muestra ninguna verificación en el navegador: la clave es toda la identidad, así que trátala como una contraseña y haz las llamadas desde tu servidor. Una clave en el código del navegador o en una app móvil es una clave que cualquiera puede leer. Una petición sin clave devuelve 401 api_key_missing; una clave errónea, 401 api_key_invalid; y una clave revocada, 401 api_key_revoked. La revocación tiene efecto desde la siguiente petición, y cada cuenta puede tener un número limitado de claves activas a la vez.

Si suspendemos o revocamos una de tus claves según las condiciones del servicio, aparece como revocada en tu lista de claves y te escribimos a la dirección de correo de tu cuenta de Google.

Endpoints y parámetros

EndpointDescripción
POST /v1/vectorize Convierte una imagen y devuelve un enlace firmado por formato.
GET /v1/options Enumera los valores aceptados de cada opción.
GET /v1/account Muestra la cuota de la clave y cuánto queda de ella.

POST /v1/vectorize recibe multipart/form-data: la imagen en un campo llamado image y las opciones como campos de formulario normales. Los valores son los ejes que devuelve GET /v1/options, y la tabla se construye con las mismas constantes, así que no puede contradecir al servidor.

Campos de formulario de POST /v1/vectorize
ParámetroValores PredeterminadoDescripción
image obligatorio PNG, JPEG, WEBP, BMP, GIF, AVIF — La imagen, como campo de archivo multipart. El tipo lo deciden sus primeros bytes, no el nombre del archivo.
formats svg, pdf, eps, dxf, png svg Uno o varios, separados por comas; la respuesta trae un enlace por formato.
colors 2–64, auto auto Tamaño de la paleta; 2 da un trazado en blanco y negro. auto lee el número de un gráfico de colores planos y, si no puede, usa 26.
svg_version svg_1_0, svg_1_1, svg_tiny_1_2 svg_1_1 La versión que se escribe en el elemento raíz del SVG.
draw_style fill_shapes, stroke_shapes, stroke_edges fill_shapes Formas rellenas, formas contorneadas o solo bordes. En el DXF las dos primeras dan los mismos contornos cerrados; solo bordes da trazados abiertos.
shape_stacking cutouts, stacked cutouts Los recortes perforan las formas de debajo; el apilado las pinta una sobre otra.
group_by none, color, parent, layer none Solo agrupación del SVG: ninguna, por color, por forma padre o por capa.
size_mm WxH, 1–5000 mm — Tamaño físico, como 150x150. Se aplica a SVG, PDF, EPS y DXF; déjalo vacío para mantener unidades en píxeles.
denoise 0–50 0 Intensidad de un prefiltro que conserva los bordes; 0 lo desactiva. No está disponible en la herramienta MCP.

group_by solo cambia cómo agrupa un SVG sus trazados. En el DXF, fill_shapes y stroke_shapes escriben los mismos contornos cerrados (LWPOLYLINE y SPLINE de grado 3) en una capa FILL_ por color; stroke_edges escribe en su lugar la red de bordes, cada límite una vez como trazado abierto, en capas EDGE_. El DXF se escribe como R2010 (AC1024) con unidades en milímetros.

Errores

Un error devuelve un JSON bajo error: un code, un type que agrupa los códigos en familias (bad_input, auth, quota, too_complex, timeout, busy, not_found, server), los valores que lo acompañan en params y un message de reserva en inglés. Decide según type, registra code en el log y nunca analices el texto del mensaje. Un cuerpo típico es {"error": {"code": "file_too_large", "type": "bad_input", "params": {"max_mb": 25}}} con el mensaje al lado.

Un cambio en /v1 que rompería una petición que hoy funciona se anuncia en esta página al menos 30 días antes de que entre en vigor. Las incorporaciones que dejan intactas las peticiones que funcionan, como un nuevo campo opcional, pueden aparecer sin aviso.

HTTPCódigoSignificado
400 image_missing No hay ningún archivo en el campo image.
400 multipart_invalid No se pudo leer el cuerpo como multipart/form-data.
400 unsupported_input La extensión del archivo no es una entrada aceptada.
400 not_an_image Los primeros bytes del archivo no son de una imagen ráster aceptada.
400 invalid_option Una opción tiene un valor fuera de su lista; params indica cuál.
400 size_mm_format size_mm no está escrito como ANxAL (ancho x alto), por ejemplo 150x150.
400 size_mm_range Un lado de size_mm está fuera del rango aceptado.
400 return_needs_one_format Se pidió ?return=file con más de un formato.
401 api_key_missing No hay clave en la cabecera Authorization.
401 api_key_invalid La clave no es válida.
401 api_key_revoked La clave se ha revocado; crea una nueva.
403 key_suspended Una clave de la cuenta está suspendida; no se puede crear una clave nueva.
409 key_limit La cuenta ya tiene el número máximo de claves activas.
413 file_too_large El archivo subido supera el límite de tamaño.
413 image_too_large La imagen decodificada supera el límite de píxeles.
422 too_complex El trabajo no se inició: su estimación supera el presupuesto de tiempo o (image_bound false) al servidor le quedaba poco tiempo para esta petición. Se sugiere un número de colores menor si alguno pasa la estimación.
422 timeout La conversión superó su presupuesto de tiempo; menos colores no ayudan, una imagen más pequeña puede ayudar.
429 busy Todos los procesos de conversión están ocupados; reintenta después del tiempo que indica la cabecera Retry-After.
429 quota_hourly La clave ha agotado su cuota por hora.
429 quota_daily La clave ha agotado su cuota diaria.
429 quota_url_fetch La clave agotó sus descargas de image_url de esta hora (herramienta MCP).
429 quota_requests La clave envió su número de solicitudes de conversión de esta hora, sea cual sea su resultado; reintenta tras el tiempo de la cabecera Retry-After.
429 key_create_limit La cuenta ya usó su cupo de claves nuevas de las últimas 24 horas; reintenta después del tiempo que indica la cabecera Retry-After.

Con 429 busy, espera el tiempo que indica la cabecera Retry-After y vuelve a enviar la petición.

Con 422 too_complex, la conversión ni siquiera empezó, y error.image_bound dice por qué. Si es true, la propia imagen supera el límite. Si error.suggested_n_colors es entonces un número, es un número de colores menor cuya estimación comprobamos con los límites que encuentra una petición nueva, normalmente el mayor que pasa; un nuevo intento con ese número pasa esta comprobación. Es una estimación, no una promesa: el nuevo intento todavía puede terminar en timeout. Si el valor es null y fewer_colors_help es false, la estimación queda por encima del límite incluso con 2 colores; menos colores no ayudan, una imagen más pequeña quizá sí. Si los dos son null, no se pudo calcular una sugerencia.

Si image_bound es false, el motivo no es la imagen: al servidor le faltó tiempo para esta petición. suggested_n_colors y fewer_colors_help vienen los dos a null, y la misma petición puede enviarse de nuevo dentro de un momento.

Con 422 timeout, la conversión empezó y superó su presupuesto de tiempo. El número de colores apenas cambia cuánto tarda una conversión, así que el cuerpo no sugiere un número de colores: suggested_n_colors es null y fewer_colors_help es false. Una imagen menor solo ayuda por debajo de 1,5 megapíxeles, porque las mayores ya se trazan a ese tamaño; prueba con aproximadamente la mitad (p. ej., 1000 × 750 px) o reduce el ruido y la textura. image_bound solo aparece con too_complex.

Un timeout devuelve la conversión a la cuota de la clave (quota_refunded: true): una vez por imagen cada hora y como máximo 2 veces por clave en cada hora de reloj; por encima de eso, el cuerpo trae quota_refunded: false.

Rara vez una conversión supera su presupuesto y la conexión se cierra hacia los 100 segundos con HTTP 524, sin cuerpo JSON; trátalo como un timeout.

Límites y cuota

LímiteValor
Conversiones por clave, por hora 20
Conversiones por clave, por día 100
Claves activas por cuenta 2
Claves nuevas por cuenta cada 24 horas, después de las 2 primeras 1
Descargas de image_url por MCP, por clave y por hora 120
Solicitudes de conversión por clave y por hora (API y MCP) 200
Tamaño del archivo 25 MB
Tamaño de la imagen decodificada 40 MP
Presupuesto de tiempo por conversión 90 s
Vigencia del enlace de descarga 1 h
size_mm, por lado 1–5000 mm

La fila de descargas cuenta cada vez que la herramienta MCP vectorize_image descarga una image_url. Se cuenta antes de que empiece la descarga, así que una descarga que falla o que no devuelve una imagen también cuenta. Este contador es independiente de la cuota de conversiones.

Las imágenes de más de 1,5 megapíxeles se reducen antes del trazado, así que el tamaño en píxeles de la salida sigue a la copia reducida; indica size_mm cuando necesites medidas físicas. Una imagen por petición.

Precio

Las claves de API y las conversiones que haces con ellas dentro de la cuota de arriba son gratuitas durante la beta. No se cobrará nada sin tu acuerdo claro previo (condiciones del servicio, sección 4).

Servidor MCP

El servidor MCP permite que un agente llame al convertidor como herramienta. Habla Streamable HTTP en https://api.rasterless.com/mcp y acepta la misma clave bearer en la misma cabecera. Ofrece dos herramientas: vectorize_image convierte una imagen, dada como image_url (una dirección https pública) o como image_base64, con las opciones de la tabla de parámetros; get_options devuelve los valores aceptados y la cuota que le queda a la clave, para que el agente pueda elegir. Elige tu cliente para ver la configuración:

Claude Code

El comando guarda la clave en tu configuración de usuario. La forma .mcp.json la lee del entorno, así que el archivo se puede subir al repositorio. Una conversión larga puede superar el tiempo de espera predeterminado de las herramientas; MCP_TOOL_TIMEOUT=120000 lo amplía.

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

Documentación oficial de configuración (Claude Code)

Claude Desktopaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Las cabeceras de petición en los conectores personalizados están en beta y solo algunas organizaciones las tienen. Si falta la sección Request headers, este cliente todavía no puede enviar la clave. El conector lo comparten todos en la organización, con una sola clave.

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

Documentación oficial de configuración (Claude Desktop)

Cursoraún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Cursor lee la clave de la variable de entorno, así que el archivo no guarda ningún secreto.

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

Documentación oficial de configuración (Cursor)

Visual Studio Codeaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

El primer archivo es el formato actual. El antiguo .vscode/mcp.json pide la clave y la deja fuera del archivo; todavía funciona, pero se está retirando.

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

Documentación oficial de configuración (Visual Studio Code)

Windsurfaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Los ajustes de agente de Windsurf ahora están en Devin Desktop. El archivo .local.json queda fuera del control de versiones.

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

Documentación oficial de configuración (Windsurf)

Codex CLIaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Codex envía el valor de la variable como token bearer; el archivo en sí no guarda ningún secreto.

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

Documentación oficial de configuración (Codex CLI)

Gemini CLIaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Usa httpUrl: en este archivo, url significa el transporte SSE antiguo.

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

Documentación oficial de configuración (Gemini CLI)

Zedaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Sin una cabecera Authorization, Zed inicia en su lugar un flujo de inicio de sesión, así que deja la cabecera puesta.

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

Documentación oficial de configuración (Zed)

Clineaún sin probar

Todavía no hemos probado esta configuración contra el servidor en producción con una clave real; sigue la documentación del propio cliente.

Deja type en streamableHttp; sin él, Cline vuelve al transporte SSE antiguo.

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

Documentación oficial de configuración (Cline)

Un archivo de configuración guarda la clave en texto plano, salvo que el cliente pueda leerla de una variable de entorno. Cuando un cliente lo documenta, el fragmento lo usa; si no, mantén el archivo fuera del control de versiones.

La herramienta MCP no puede abrir un archivo de tu ordenador: recibe una dirección https pública o los bytes del archivo en base64. Para convertir un archivo de tu disco desde un script, usa el comando curl de Primeros pasos.

Lo que la API no hace

Preguntas

¿La salida es la misma que en el sitio web?

Sí. La API ejecuta el mismo motor con las mismas opciones que el convertidor de este sitio, así que la misma imagen con los mismos ajustes da los mismos archivos. Solo cambia el presupuesto de tiempo: 90 segundos por conversión a través de la API o del MCP frente a 300 segundos en el sitio, porque la API devuelve una única respuesta al final; las imágenes pesadas conviene convertirlas en el sitio.

¿Puedo llamar a la API desde una página web?

Haz las llamadas desde tu servidor. Una clave puesta en el código del navegador la puede leer cualquiera que abra la página, y cada conversión hecha con ella se descuenta de tu cuota.

¿Qué agentes pueden usar el servidor MCP?

Cualquier cliente MCP que pueda conectarse a un servidor remoto por Streamable HTTP y enviar una cabecera Authorization. La sección de configuración enumera los clientes que hemos comprobado con su propia documentación, con la configuración que espera cada uno.

¿Qué pasa con las imágenes que envío?

Lo mismo que en el sitio: los enlaces de descarga caducan al cabo de 1 hora, y las imágenes subidas y los archivos generados se eliminan mediante una regla automática de borrado de 1 día. No se usan para nada más.

¿Y si una conversión es demasiado pesada?

No se ejecuta más allá de su presupuesto de tiempo. En lugar de un archivo recibes un 422. Si el cuerpo sugiere un número de colores menor, vuelve a enviar la petición con ese número. Si image_bound es false, no pesaba la imagen sino que al servidor le faltó tiempo: vuelve a enviar la misma petición dentro de un momento. Si no, prueba con una imagen más pequeña.

Páginas relacionadas