Documentação da API REST
Integre o Vectorgram na sua aplicação. Um endpoint para submeter, um para consultar, um para transferir — os jobs são assíncronos por conceção. URL base https://api.vectorgram.ai, a autenticação é Authorization: Bearer <api_key>. As chaves parecem-se com vectorgram_sk_live_… — o prefixo é escrito por extesso de propósito, para que uma chave encontrada num antigo .env possa ser identificada sem a experimentar.
Uma conta nova recebe 25 conversões de API grátis durante 30 dias — qualidade total, sem marca de água. Depois disso, a API precisa de um plano que a inclua (Pro ou superior) e as chamadas consomem o limite mensal desse plano. Não há excedentes: ultrapassado o limite, as chamadas respondem 402 com a data de reposição. GET /v1/account comunica ambos os limites e o que resta de cada um.
Início rápido
1 — Obtenha a sua chave de API
A carregar…
2 — Submeta uma imagem
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"A resposta é 202 Accepted com um job na fila — a conversão ainda não aconteceu. Enviar o mesmo pedido duas vezes com uma Idempotency-Key devolve o primeiro job em vez de criar um segundo; alterar o ficheiro ou as definições sob uma chave já utilizada dá um 409.
3 — Consulte, ou receba um 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 percorre queued → processing → completed | failed | canceled | expired. Enquanto está na fila, recebe um queue_position real em vez de uma contagem inventada; progress durante o processamento é interpolado a partir da estimativa de tamanho e fica limitado a 95% até que o ficheiro exista. Imagens grandes podem demorar minutos — consulte a intervalos sensatos ou, melhor ainda, registe um webhook.
4 — Transfira
{
"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 só aparece quando existe um resultado, precisa do mesmo bearer token e transmite o ficheiro como anexo. Com retention=none o ficheiro é apagado à medida que é servido — transfira-o uma única vez.
Parâmetros de conversão
Todos os campos são dados de formulário multipart em POST /v1/vectorize. Os quatro marcados manual são os controlos de traçado: disponíveis em Pro, Studio, Agency e Enterprise. Em Free e Lite são aceites e depois substituídos pelos valores predefinidos, em vez de recusados, para que um cliente que os envie sempre converta na mesma — apenas obtém o resultado automático.
Obrigatório. A imagem a converter. Detetada pelos seus bytes, não pelo nome do ficheiro.
Que tipo de imagem é. Predefinição auto, que deixa o motor classificá-la.
Opcional, e svg é o único valor. SVG é o que o motor escreve e nada o converte noutra coisa — EPS, PNG, PDF, DXF e AI são recusados com 400 unsupported_output_format em vez de entrarem na fila para falhar.
Durante quanto tempo o resultado é guardado. Predefinição 24h; none apaga-o após a primeira transferência. Limitado ao máximo do seu plano em vez de recusado — o Free não consegue guardar um resultado durante 10 dias só por o pedir.
A sua própria chave de agrupamento, ecoada no job e utilizável como filtro. Submeta um pedido por imagem. A conversão em lote começa no Pro (30 ficheiros, 50 no Studio, 100 no Agency); abaixo disso, o grupo contém um ficheiro e um segundo responde 400 batch_limit_exceeded.
O nome da pasta onde os ficheiros do lote ficarão no painel. Opcional e requer batch_id (400 invalid_folder_name caso contrário); limitado como o batch_id — 128 caracteres, sem caracteres de controlo. O primeiro ficheiro admitido dá o nome à pasta; os ficheiros posteriores do lote não a renomeiam. Se for omitido, a pasta fica marcada com a data de criação.
Quanto da imagem sobrevive à fusão de regiões. Predefinição high — o passo mais folgado que o motor tem desde o 1.3.0. Um valor de slider entre 1 e 100 é aceite e agrupado.
Tratamento de gradientes. Predefinição smooth; stepped e auto deixam os preenchimentos planos do motor.
Arredondamento de cantos. Predefinição strong — os cantos reais mantêm-se agudos; só volta o que o traçador arredondou por acaso. Um valor de slider entre 0 e 100 é aceite e agrupado.
O que o motor desenha. Predefinição fill — cada forma como um contorno preenchido. centerline desenha um traço aberto ao longo do meio de cada linha (fill="none", com cor e espessura de traço), que é o que os plotters, gravadores a laser, fresadoras CNC e máquinas de corte de vinil seguem: uma passagem por linha em vez de dois contornos à sua volta. As partes demasiado espessas para serem linhas mantêm-se formas preenchidas. detail, gradients e smoothing não se aplicam e são ignorados. Um valor desconhecido responde 400.
Fecho de juntas, em todos os planos. Predefinição true — cada preenchimento corre 0,75 px por baixo do vizinho, para não aparecer uma linha clara fina entre duas cores. false dá a partição exata, em que as formas se encontram de bordo a bordo sem sobreposição (para editar a geometria). Nenhuma forma se move em nenhum dos casos. Ignorado com centerline.
Endpoints
A referência gerada — cada campo, cada forma de resposta — é a interface Swagger UI que o serviço serve em /docs/swagger, com o documento OpenAPI em /v3/api-docs.
Webhooks
Como os jobs correm de forma assíncrona — minutos para ficheiros grandes —, subscreva webhooks em vez de consultar. Registe um endpoint com POST /v1/webhooks; o segredo de assinatura é devolvido uma vez, na criação, e nunca mais.
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" }
}Verifique a assinatura calculando o HMAC-SHA256 do corpo do pedido em bruto com o segredo do seu endpoint e comparando em tempo constante — trate uma divergência como um pedido não autenticado. A entrega é pelo menos uma vez: uma resposta não-2xx é repetida três vezes com backoff exponencial, por isso torne o seu handler idempotente em id. Os endpoints têm de resolver para um endereço público; isso é verificado novamente no momento da entrega, e não apenas no registo.
Erros
As falhas são JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Leia code, não a mensagem — as mensagens são reescritas.