Documentación de la API REST
Integra Vectorgram en tu aplicación. Un endpoint para enviar, uno para consultar, uno para descargar — los trabajos son asíncronos por diseño. URL base https://api.vectorgram.ai, la autenticación es Authorization: Bearer <api_key>. Las claves se ven así: vectorgram_sk_live_… — el prefijo se escribe a propósito, para que una clave encontrada en un .env viejo pueda identificarse sin tener que probarla.
Toda cuenta nueva recibe 25 conversiones de API gratis durante 30 días — calidad completa, sin marca de agua. Después, la API necesita un plan que la incluya (Pro o superior), y las llamadas salen de la cuota mensual de ese plan. No hay excedentes: al pasar de la cuota, las llamadas responden 402 con la fecha de reinicio. GET /v1/account reporta ambas cuotas y lo que queda de cada una.
Inicio rápido
1 — Consigue tu clave de API
Cargando…
2 — Envía una imagen
curl -X POST https://api.vectorgram.ai/v1/vectorize \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: 8f1b0c2e-0a1d-4f77-9c3a-2b6e5d4c1a90" \
-F "file=@image.png" \
-F "image_type=clipart" \
-F "detail=high" \
-F "gradients=smooth" \
-F "smoothing=strong" \
-F "retention=24h"La respuesta es 202 Accepted con un trabajo en cola — la conversión todavía no ha ocurrido. Enviar la misma solicitud dos veces con una misma Idempotency-Key devuelve el primer trabajo en lugar de crear otro; cambiar el archivo o los ajustes bajo una clave ya usada es un 409.
3 — Consulta, o recibe un webhook
GET /v1/jobs/job_abc123
{
"id": "job_abc123",
"status": "queued",
"progress": 0,
"queue_position": 3,
"mode": "logo",
"retention": "24h",
"megapixels": 2.1,
"created_at": "2026-08-03T10:30:00Z"
}status pasa por queued → processing → completed | failed | canceled | expired. Mientras está en cola recibes un queue_position real en lugar de una cuenta regresiva inventada; progress durante el procesamiento se interpola a partir del estimado de tamaño y se queda en 95% hasta que el archivo exista. Las imágenes grandes pueden tardar minutos — consulta con un intervalo razonable o, mejor, registra un webhook.
4 — Descarga
{
"id": "job_abc123",
"status": "completed",
"progress": 100,
"download_url": "https://api.vectorgram.ai/v1/jobs/job_abc123/download",
"completed_at": "2026-08-03T10:30:04Z",
"expires_at": "2026-08-04T10:30:04Z"
}download_url aparece solo cuando existe un resultado, necesita el mismo token bearer y manda el archivo como adjunto. Con retention=none el archivo se elimina al ser entregado — descárgalo una sola vez.
Parámetros de conversión
Todos los campos son multipart form data en POST /v1/vectorize. Los cuatro marcados con manual son los controles de trazado: disponibles en Pro, Studio, Agency y Enterprise. En Free y Lite se aceptan y luego se reemplazan por los valores por defecto, en lugar de rechazarse, para que un cliente que siempre los manda siga convirtiendo — solo recibe el resultado automático.
Obligatorio. La imagen a convertir. Se detecta por sus bytes, no por su nombre de archivo.
Qué tipo de imagen es. Por defecto auto, que deja que el motor la clasifique.
Opcional, y svg es el único valor. SVG es lo que el motor escribe y nada lo convierte en otra cosa — EPS, PNG, PDF, DXF y AI se rechazan con 400 unsupported_output_format en lugar de encolarse para fallar.
Cuánto tiempo se conserva el resultado. Por defecto 24h; none lo elimina después de la primera descarga. Se ajusta al máximo de tu plan en lugar de rechazarse — Free no puede conservar un resultado 10 días por pedirlo.
Tu propia clave de agrupación, devuelta en el trabajo y utilizable como filtro. Envía una solicitud por imagen. La conversión por lotes empieza en Pro (30 archivos, 50 en Studio, 100 en Agency); por debajo, el grupo admite un archivo y un segundo responde 400 batch_limit_exceeded.
El nombre de la carpeta donde quedarán los archivos del lote en el panel. Opcional y requiere batch_id (400 invalid_folder_name si no); con el mismo límite que batch_id — 128 caracteres, sin caracteres de control. El primer archivo admitido pone el nombre a la carpeta; los archivos posteriores del lote no la renombran. Si se omite, la carpeta se etiqueta con su fecha de creación.
Cuánto de la imagen sobrevive a la fusión de regiones. Por defecto high — el paso más laxo que tiene el motor desde la 1.3.0. Se acepta un valor de slider de 1–100 y se agrupa por tramos.
Manejo de degradados. Por defecto smooth; stepped y auto dejan los rellenos planos del motor.
Redondeo de esquinas. Por defecto strong — las esquinas reales quedan nítidas y solo vuelve lo que el motor de vectorización redondeó por accidente. Se acepta un valor de slider de 0–100 y se agrupa por tramos.
Qué dibuja el motor. Por defecto fill — cada forma como un contorno relleno. centerline dibuja un trazo abierto por el medio de cada línea (fill="none", con un color y grosor de trazo), que es lo que siguen los plóters, grabadores láser, routers CNC y cortadoras de vinil: una pasada por línea en lugar de dos contornos alrededor. Las partes demasiado gruesas para ser línea quedan como formas rellenas. detail, gradients y smoothing no aplican y se ignoran. Un valor desconocido responde 400.
Cierre de costuras, en todos los planes. Por defecto true — cada relleno corre 0.75 px por debajo de su vecino, para que no asome una línea fina y clara entre dos colores. false da la partición exacta, donde las formas se encuentran borde con borde sin superposición (para editar geometría). Ninguna forma se mueve en ningún caso. Se ignora con centerline.
Endpoints
La referencia generada — cada campo, cada forma de respuesta — es la interfaz Swagger que el servicio sirve en /docs/swagger, con el documento OpenAPI en /v3/api-docs.
Webhooks
Como los trabajos corren de forma asíncrona — minutos para archivos grandes — suscríbete a webhooks en lugar de consultar. Registra un endpoint con POST /v1/webhooks; el secreto de firma se devuelve una sola vez, al crearlo, y nunca más.
POST https://your-app.example/hooks/vectorgram
X-Vectorgram-Event: processing.completed
X-Vectorgram-Signature: sha256=<hmac of the raw body, hex>
{
"id": "evt_9f2c…",
"event": "processing.completed",
"created_at": "2026-08-03T10:30:04Z",
"data": { "job_id": "job_abc123", "status": "completed" }
}Verifica la firma calculando el HMAC-SHA256 del cuerpo crudo de la solicitud con el secreto de tu endpoint y comparándolo en tiempo constante — trata una discrepancia como una solicitud no autenticada. La entrega es al menos una vez: una respuesta que no sea 2xx se reintenta tres veces con backoff exponencial, así que haz que tu handler sea idempotente respecto a id. Los endpoints deben resolverse a una dirección pública; se revalida al momento de la entrega, no solo al registrarse.
Errores
Los fallos son JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Fíjate en code, no en el mensaje — los mensajes se reescriben.