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.
Copia esta clave ahora. Se muestra una sola vez: de ella solo guardamos un hash con clave secreta, más sus cuatro primeros y cuatro últimos caracteres para que la reconozcas en la lista.
Hasta 2 claves activas por cuenta.
| Clave | Creada | Último uso | Esta hora | Hoy | Acción |
|---|
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.
export RASTERLESS_API_KEY='TU_CLAVE_DE_API'
$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.
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. 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.
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. 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:
{
"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
| Endpoint | Descripció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.
| Parámetro | Valores | Predeterminado | Descripció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.
| HTTP | Código | Significado |
|---|---|---|
| 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ímite | Valor |
|---|---|
| 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.
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 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.
URL https://api.rasterless.com/mcp
Authentication none (the request header carries the key)
Request header authorization: Bearer rl_live_…
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.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer ${env:RASTERLESS_API_KEY}" }
}
}
}
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.
{
"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}" }
}
}
}
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.
{
"mcpServers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"transport": "http",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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.
[mcp_servers.rasterless]
url = "https://api.rasterless.com/mcp"
bearer_token_env_var = "RASTERLESS_API_KEY"
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.
{
"mcpServers": {
"rasterless": {
"httpUrl": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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.
{
"context_servers": {
"rasterless": {
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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.
{
"mcpServers": {
"rasterless": {
"type": "streamableHttp",
"url": "https://api.rasterless.com/mcp",
"headers": { "Authorization": "Bearer rl_live_…" }
}
}
}
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
- Una imagen por petición. No hay ningún endpoint que acepte una carpeta o un archivo comprimido de imágenes.
- No hay webhooks ni cola de trabajos: la petición vuelve cuando la conversión termina o cuando agota su presupuesto de tiempo; ese presupuesto es de 90 segundos aquí y de 300 segundos en el sitio, así que las imágenes pesadas conviene convertirlas en el sitio.
- No hay SDK. Sirve cualquier cliente HTTP que pueda enviar
multipart/form-data. - Las entradas son PNG, JPEG, WEBP, BMP, GIF o AVIF; no se aceptan archivos SVG, PDF, TIFF ni HEIC. Las salidas son SVG, PDF, EPS, DXF y PNG, y nada más.
- No se edita después del trazado: la API devuelve archivos, no un dibujo editable.
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.