เอกสาร API
เชื่อม Vectorgram เข้ากับแอปพลิเคชันของคุณ เอนด์พอยต์เดียวสำหรับส่ง เอนด์พอยต์เดียวสำหรับโพลล์ เอนด์พอยต์เดียวสำหรับดาวน์โหลด — งานเป็นแบบอะซิงโครนัสโดยการออกแบบ Base URL https://api.vectorgram.ai การยืนยันตัวตนคือ Authorization: Bearer <api_key> คีย์หน้าตาแบบ vectorgram_sk_live_… — สะกด prefix ไว้ชัดเจนโดยเจตนา คีย์ที่พบใน .env เก่าจึงระบุตัวได้โดยไม่ต้องลองใช้
บัญชีใหม่เริ่มที่ Trial พร้อมการแปลงฟรี 5 ครั้ง — คุณภาพเต็ม ไม่มีลายน้ำ — ใช้ได้ทั้งในเบราว์เซอร์และผ่าน 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 — โพลล์ หรือรับเว็บฮุก
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% จนกว่าไฟล์จะมีจริง ภาพใหญ่อาจใช้เวลาหลายนาที — โพลล์ในช่วงห่างที่สมเหตุผล หรือไม่ก็ลงทะเบียนเว็บฮุกเสียจะดีกว่า
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 token ตัวเดิม และสตรีมไฟล์มาเป็น attachment ด้วย retention=none ไฟล์ถูกลบไปพร้อมกับที่ส่งให้ — ดาวน์โหลดครั้งเดียว
พารามิเตอร์การแปลง
ทุกฟิลด์เป็น multipart form data บน POST /v1/vectorize สี่ตัวที่ทำเครื่องหมาย ปรับด้วยมือ คือตัวควบคุมการไล่เส้น: ใช้ได้ใน Pro, Studio, Agency และ Enterprise ใน Trial และ Lite พวกมันถูกรับไว้แล้วแทนที่ด้วยค่าเริ่มต้นแทนที่จะปฏิเสธ ไคลเอนต์ที่ส่งมาตลอดจึงยังแปลงได้ — แค่ได้ผลลัพธ์แบบอัตโนมัติ
จำเป็น ภาพที่จะแปลง ตรวจจากไบต์ของไฟล์ ไม่ใช่จากชื่อไฟล์
ภาพนี้เป็นชนิดใด ค่าเริ่มต้น auto ให้เอนจินจัดประเภทเอง
ไม่บังคับ และ svg เป็นค่าเดียว SVG คือสิ่งที่เอนจินเขียนและไม่มีอะไรแปลงมันเป็นอย่างอื่น — EPS, PNG, PDF, DXF และ AI ถูกปฏิเสธด้วย 400 unsupported_output_format แทนที่จะเข้าคิวแล้วล้มเหลว
ผลลัพธ์ถูกเก็บไว้นานแค่ไหน ค่าเริ่มต้น 24h; none ลบหลังการดาวน์โหลดครั้งแรก ถูกบีบเข้าหาค่าสูงสุดของแพ็กเกจแทนที่จะปฏิเสธ — Trial ขอเก็บผลลัพธ์ไว้ 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 router และเครื่องตัดไวนิลเดินตาม: ผ่านหนึ่งครั้งต่อเส้นแทนที่จะเป็นสองเส้นขอบรอบมัน ส่วนที่หนาเกินกว่าจะเป็นเส้นคงเป็นรูปทรงเติมสี detail, gradients และ smoothing ไม่มีผลและถูกละเว้น ค่าที่ไม่รู้จักตอบ 400
การปิดรอยต่อ มีในทุกแพ็กเกจ ค่าเริ่มต้น true — การเติมสีแต่ละที่วิ่งซ้อนใต้ของเพื่อนบ้าน 0.75 px จึงไม่มีเส้นสว่างบาง ๆ โผล่ระหว่างสองสี false ให้การแบ่งแบบตรงจุด รูปทรงชิดขอบต่อขอบไม่ทับกัน (สำหรับแก้ไขเรขาคณิต) ไม่ว่ากรณีใดก็ไม่มีรูปทรงขยับ ถูกละเว้นเมื่อใช้ centerline
เอนด์พอยต์
เอกสารอ้างอิงที่สร้างอัตโนมัติ — ทุกฟิลด์ ทุกรูปร่างการตอบกลับ — คือ Swagger UI ที่บริการเสิร์ฟไว้ที่ /docs/swagger พร้อมเอกสาร OpenAPI ที่ /v3/api-docs.
เว็บฮุก
เนื่องจากงานทำงานแบบอะซิงโครนัส — หลายนาทีสำหรับไฟล์ใหญ่ — สมัครรับเว็บฮุกแทนการโพลล์ ลงทะเบียนเอนด์พอยต์ด้วย 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 ของเนื้อความคำขอดิบด้วยรหัสลับของเอนด์พอยต์แล้วเทียบแบบ constant time — ถือว่าไม่ตรงกันคือคำขอที่ไม่ผ่านการยืนยันตัวตน การส่งมอบเป็นอย่างน้อยหนึ่งครั้ง: การตอบที่ไม่ใช่ 2xx จะถูกลองใหม่สามครั้งด้วย exponential backoff จึงควรทำ handler ของคุณให้ idempotent บน id เอนด์พอยต์ต้องชี้ไปที่ที่อยู่สาธารณะ; ตรวจซ้ำอีกครั้งตอนส่งมอบจริง ไม่ใช่แค่ตอนลงทะเบียน
ข้อผิดพลาด
ความล้มเหลวเป็น JSON: { "error": { "code": "…", "message": "…", "details": { … } } } ให้อ่าน code ไม่ใช่ข้อความ — ข้อความถูกเรียบเรียงใหม่ได้