Documentación de la API
Integra Vectorgram en tu aplicación. Un endpoint para enviar, otro para consultar, otro para descargar — los trabajos son asíncronos por diseño. La URL base es https://api.vectorgram.ai, la autenticación es Authorization: Bearer <api_key>. Las claves tienen este aspecto vectorgram_sk_live_… — el prefijo se escribe a propósito, así una clave encontrada en un antiguo .env puede identificarse sin necesidad de probarla.
Una 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 se descuentan de la cuota mensual de ese plan. No hay sobrecoste: pasada la cuota, las llamadas responden 402 con la fecha de reinicio. GET /v1/account informa de ambas cuotas y de 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 aún no ha ocurrido. Enviar la misma petición dos veces con una misma Idempotency-Key devuelve el primer trabajo en lugar de crear un segundo; 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 y no una cuenta atrás inventada; progress durante el procesado se interpola a partir de la estimación de tamaño y se limita al 95% hasta que el archivo existe. Las imágenes grandes pueden tardar minutos — consulta con un intervalo sensato o, mejor aún, 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 ya existe un resultado, necesita el mismo token bearer y sirve el archivo como adjunto. Con retention=none el archivo se elimina a medida que se sirve — descárgalo una sola vez.
Parámetros de conversión
Todos los campos son multipart form data en POST /v1/vectorize. Los cuatro marcados como manual son los controles de trazado: disponibles en Pro, Studio, Agency y Enterprise. En Free y Lite se aceptan y después se sustituyen por los valores predeterminados, en lugar de rechazarse, así que un cliente que siempre los envía sigue convirtiendo — solo que obtiene 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 esta. Por defecto auto, que deja que el motor la clasifique.
Opcional, y svg es el único valor. SVG es lo que escribe el motor 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 tras la primera descarga. Se recorta al máximo de tu plan en lugar de rechazarse — Free no puede conservar un resultado 10 días por mucho que lo pida.
Tu propia clave de agrupación, devuelta en el trabajo y utilizable como filtro. Envía una petición por imagen. La conversión por lotes empieza en Pro (30 archivos, 50 en Studio, 100 en Agency); por debajo, el grupo admite un solo 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 en caso contrario); con los mismos límites que batch_id — 128 caracteres, sin caracteres de control. El primer archivo admitido pone nombre a la carpeta; los archivos posteriores del lote no la renombran. Si se omite, la carpeta lleva 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 deslizador 1–100 y se agrupa en tramos.
Tratamiento 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 trazador redondeó por accidente. Se acepta un valor de deslizador 0–100 y se agrupa en tramos.
Lo que dibuja el motor. Por defecto fill — cada forma es un contorno relleno. centerline dibuja un trazo abierto por el centro de cada línea (fill="none", con un color y un grosor de trazo), que es lo que siguen plóters, grabadoras láser, routers CNC y cortadoras de vinilo: una pasada por línea en lugar de dos contornos alrededor. Las partes demasiado gruesas para ser una línea quedan como formas rellenas. detail, gradients y smoothing no se 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, así no asoma una línea fina y clara entre dos colores. false da la partición exacta, donde las formas se encuentran borde con borde sin superponerse (para editar la 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 se ejecutan 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, en la creación, 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 de la petición en bruto con el secreto de tu endpoint y comparándolo en tiempo constante — trata una discrepancia como una petición no autenticada. La entrega es al menos una vez: una respuesta no 2xx se reintenta tres veces con backoff exponencial, así que haz que tu manejador sea idempotente respecto a id. Los endpoints deben resolverse a una dirección pública; eso se vuelve a comprobar en el momento de la entrega, no solo en el registro.
Errores
Los fallos son JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Guíate por code, no por el mensaje — los mensajes se reformulan.