API 文档
把 Vectorgram 集成到您的应用里。一个端点提交，一个端点轮询，一个端点下载 — 任务在架构上就是异步的。基础 URL 为 https://api.vectorgram.ai，认证方式是 Authorization: Bearer <api_key>。密钥形如 vectorgram_sk_live_… — 前缀是刻意完整拼写的，这样在旧的 .env 里发现的密钥，不用试也能识别出来。
新账号可在 30 天内免费获得 25 次 API 转换 — 完整质量，无水印。此后，API 需要包含它的套餐（Pro 及以上），调用从该套餐的月度额度中扣除。没有超额费用：超出额度后，调用会收到 402 响应，附带重置日期。 GET /v1/account 会报告两项额度以及各自的剩余量。
快速上手
1 — 获取您的 API 密钥
加载中…
2 — 提交一张图片
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"响应是 202 Accepted，附带一个排队中的任务 — 转换还没有发生。用同一个 Idempotency-Key 发送两次相同的请求，返回的是第一个任务，而不是再建一个；在已经用过的密钥下更改文件或设置，得到的则是 409。
3 — 轮询，或接收 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 依次经过 queued → processing → completed | failed | canceled | expired。排队时，您看到的是真实的 queue_position，而不是虚构的倒计时；progress 在处理期间根据大小估算插值得出，在文件生成之前最高封顶于 95%。大图可能需要几分钟 — 请以合理的间隔轮询，或者更好的做法是注册一个 webhook。
4 — 下载
{
"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 只在结果生成之后出现，需要同样的 bearer 令牌，并以附件形式流式传输文件。使用 retention=none 时，文件在交付的同时即被删除 — 只能下载一次。
转换参数
所有字段都是以 multipart 表单数据发到 POST /v1/vectorize 的。标有 手动 的四项是描摹控制参数：适用于 Pro、Studio、Agency 和 Enterprise。在 Free 和 Lite 上，这些参数会被接受然后替换为默认值，而不是被拒绝，因此总是发送它们的客户端仍然能完成转换 — 只是得到自动结果。
必填。要转换的图片。从文件字节而非文件名识别格式。
这张图片属于哪一类。默认 auto，由引擎自行分类。
可选，且 svg 是唯一取值。引擎写出的就是 SVG，流水线中没有任何环节会把它转换成别的格式 — EPS、PNG、PDF、DXF 和 AI 会收到 400 unsupported_output_format 拒绝，而不是排进队列后失败。
结果保留多久。默认 24h；none 在首次下载后即删除。超出套餐上限时会被收敛到上限，而不是被拒绝 — Free 套餐无法靠请求让结果保留 10 天。
您自己的分组键，会在任务上原样返回，并可用作筛选条件。每张图片提交一个请求。批量转换从 Pro 开始（30 个文件，Studio 50 个，Agency 100 个）；低于 Pro 时，分组只容纳一个文件，第二个会收到 400 batch_limit_exceeded。
批量的文件在仪表板上所在文件夹的名称。可选，且必须与 batch_id 一起发送（否则返回 400 invalid_folder_name）；限制与 batch_id 相同 — 128 个字符，不含控制字符。第一个被接受的文件为文件夹命名，批量中后来的文件不会再改名。留空时，文件夹以创建日期命名。
区域合并之后，图像内容保留多少。默认 high — 自 1.3.0 起引擎最宽松的一档。接受 1–100 的滑块值，并归入相应档位。
渐变处理方式。默认 smooth；stepped 和 auto 保留引擎的平色填充。
圆角处理。默认 strong — 真实的转角保持尖锐，只有描摹时被意外抹圆的地方会被修回来。接受 0–100 的滑块值，并归入相应档位。
引擎画什么。默认 fill — 每个形状都是填充轮廓。centerline 沿每条线条的中线画一条开放描边（fill="none"，带描边颜色和宽度），这正是绘图仪、激光雕刻机、CNC 雕铣机和乙烯基切割机跟随的路径：每条线走一刀，而不是沿两侧各描一圈。粗到算不上线条的部分仍保持为填充形状。detail、gradients 和 smoothing 不适用，会被忽略。未知取值返回 400。
接缝闭合，所有套餐均可用。默认 true — 每个填充向相邻填充的下方延伸 0.75 px，两种颜色之间不会露出细亮线。false 给出精确分割：形状边缘齐平、互不重叠（适合编辑几何结构）。两种设置下都没有任何形状会移动。centerline 下忽略此项。
端点
生成的参考文档 — 每个字段、每种响应结构 — 就是服务在 /docs/swagger 提供的 Swagger UI，OpenAPI 文档在 /v3/api-docs。
Webhooks
由于任务异步运行 — 大文件可能需要几分钟 — 请订阅 webhook，而不是轮询。用 POST /v1/webhooks 注册端点；签名密钥只在创建时返回一次，之后不会再显示。
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" }
}验证签名的方法：用端点密钥对原始请求体计算 HMAC-SHA256，并以恒定时间方式进行比较 — 不匹配即视为未认证的请求。投递至少发生一次：非 2xx 响应会以指数退避重试三次，因此请让您的处理程序对 id 保持幂等。端点必须能解析到公网地址；交付时会重新检查，而不只是在注册时。
错误
失败以 JSON 返回：{ "error": { "code": "…", "message": "…", "details": { … } } }。请看 code，而不是消息文本 — 消息的措辞可能会变。