Documentação da API
Integre o Vectorgram ao seu aplicativo. Um endpoint para enviar, um para consultar, um para baixar — os jobs são assíncronos por design. URL base https://api.vectorgram.ai, a autenticação é Authorization: Bearer <api_key>. As chaves têm esta forma vectorgram_sk_live_… — o prefixo é escrito por extenso de propósito, para que uma chave encontrada num antigo .env possa ser identificada sem precisar ser testada.
Uma conta nova recebe 25 conversões de API grátis por 30 dias — qualidade total, sem marca-d'água. Depois disso, a API precisa de um plano que a inclua (Pro e acima), e as chamadas saem da cota mensal desse plano. Não há excedente: passada a cota, as chamadas respondem 402 com a data de renovação. GET /v1/account informa as duas cotas e o que resta de cada uma.
Início rápido
1 — Obtenha sua chave de API
Carregando…
2 — Envie 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 enfileirado — 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; mudar o arquivo ou as configurações sob uma chave já usada é 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 o job está na fila, você recebe uma queue_position real em vez de uma contagem regressiva inventada; progress durante o processamento é interpolado a partir da estimativa de tamanho e limitado a 95% até o arquivo existir. Imagens grandes podem levar minutos — consulte em um intervalo razoável ou, melhor ainda, registre um webhook.
4 — Download
{
"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 somente quando já existe um resultado, precisa do mesmo bearer token e serve o arquivo em streaming como anexo. Com retention=none o arquivo é excluído ao ser servido — baixe-o uma única vez.
Parâmetros de conversão
Todos os campos são multipart form data em POST /v1/vectorize. Os quatro marcados com manual são os controles de traçado: disponíveis no Pro, Studio, Agency e Enterprise. No Free e no Lite eles são aceitos e depois substituídos pelos padrões, em vez de recusados, então um cliente que sempre os envia continua convertendo — só recebe o resultado automático.
Obrigatório. A imagem a converter. O tipo é detectado pelos bytes, e não pelo nome do arquivo.
Que tipo de imagem é esta. Padrão auto, que deixa o motor classificá-la.
Opcional, e svg é o único valor. SVG é o que o motor grava, e nada o converte em outra coisa — EPS, PNG, PDF, DXF e AI são recusados com 400 unsupported_output_format em vez de entrarem na fila para falhar.
Por quanto tempo o resultado é guardado. Padrão 24h; none o exclui depois do primeiro download. Limitado ao máximo do seu plano, em vez de recusado — o Free não passa a reter um resultado por 10 dias só porque foi pedido.
Sua própria chave de agrupamento, ecoada de volta no job e utilizável como filtro. Envie um pedido por imagem. A conversão em lote começa no Pro (30 arquivos, 50 no Studio, 100 no Agency); abaixo disso o grupo comporta um arquivo, e um segundo responde 400 batch_limit_exceeded.
O nome da pasta em que os arquivos do lote vão ficar no painel. Opcional e exige batch_id (400 invalid_folder_name caso contrário); limitado como o batch_id — 128 caracteres, sem caracteres de controle. O primeiro arquivo aceito dá o nome à pasta; os arquivos seguintes do lote não a renomeiam. Se omitido, a pasta recebe um carimbo com a data de criação.
Quanto da imagem sobrevive à mesclagem de regiões. Padrão high — o passo mais frouxo que o motor tem desde a 1.3.0. Um valor de slider de 1–100 é aceito e agrupado.
Tratamento de gradientes. Padrão smooth; stepped e auto resultam nos preenchimentos planos do motor.
Arredondamento de cantos. Padrão strong — os cantos reais permanecem nítidos; só o que o traçador arredondou por acidente volta arredondado. Um valor de slider de 0–100 é aceito e agrupado.
O que o motor desenha. Padrão fill — cada forma é um contorno preenchido. centerline desenha um traço aberto pelo meio de cada linha (fill="none", com cor e espessura de traço), que é o que plotters, gravadores a laser, routers CNC e plotters de recorte seguem: uma passada por linha em vez de dois contornos ao redor dela. Partes grossas demais para serem uma linha permanecem formas preenchidas. detail, gradients e smoothing não se aplicam e são ignorados. Um valor desconhecido responde 400.
Fechamento de emendas, em todos os planos. Padrão true — cada preenchimento corre 0,75 px por baixo do vizinho, para que nenhuma linha clara fina apareça entre duas cores. false dá a partição exata, em que as formas se encontram borda a borda sem sobreposição (para editar geometria). Nenhuma forma se move em nenhum dos casos. Ignorado com centerline.
Endpoints
A referência gerada — cada campo, cada forma de resposta — é a Swagger UI que o serviço serve em /docs/swagger, com o documento OpenAPI em /v3/api-docs.
Webhooks
Como os jobs rodam de forma assíncrona — minutos para arquivos grandes —, assine webhooks em vez de fazer polling. Registre um endpoint com POST /v1/webhooks; o segredo de assinatura é retornado 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 bruto da requisição com o segredo do seu endpoint e comparando em tempo constante — trate uma divergência como uma requisição não autenticada. A entrega é pelo menos uma vez: uma resposta não 2xx é tentada de novo três vezes com backoff exponencial, então faça o seu handler idempotente em id. Os endpoints precisam resolver para um endereço público; isso é verificado de novo na entrega, e não apenas no registro.
Erros
As falhas são JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. Leia code, não a mensagem — as mensagens mudam de redação.