API 文件
將 Vectorgram 整合進您的應用程式。一個端點送出、一個輪詢、一個下載 — 工作天生就是非同步的。Base URL 為 https://api.vectorgram.ai，認證方式為 Authorization: Bearer <api_key>。金鑰長得像 vectorgram_sk_live_… — 前綴刻意完整拼出，因此即使在舊的 .env 中發現的金鑰，也能不必實際嘗試就辨認出來。
新帳號可免費取得 25 次 API 轉換，期限 30 天 — 完整品質、無浮水印。之後，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 form data 傳送到 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 個）；再往下，群組只能容納一個檔案，第二個會回 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 雕刻機與 vinyl 切割機跟隨的路徑：每條線一刀，而不是沿著線兩側各繞一圈。粗到不算線條的部分仍保持填色形狀。detail、gradients 與 smoothing 不適用，會被忽略。未知值回 400。
接縫閉合，所有方案皆可使用。預設 true — 每個填色會向鄰居延伸 0.75 px，兩色之間不會出現細亮線。false 給出精確分割：形狀邊對邊相接、無重疊（適合編輯幾何）。兩種設定下形狀都不會移動。centerline 模式忽略此參數。
端點
自動產生的參考文件 — 每個欄位、每種回應形狀 — 就是服務託管在 /docs/swagger 的 Swagger UI，OpenAPI 文件則在 /v3/api-docs。
Webhook
工作是非同步執行的 — 大檔案要數分鐘 — 因此請訂閱 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，而不是訊息本身 — 訊息的措辭可能會調整。