وثائق API
ادمج Vectorgram في تطبيقك. نقطة نهاية للإرسال، وأخرى للاستطلاع، وثالثة للتنزيل، والمهام غير متزامنة بالتصميم. عنوان 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 لا يظهر إلا بعد وجود النتيجة، ويحتاج رمز الحامل نفسه، ويعيد الملف تيارًا كمرفق. ومع 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 ملفًا و50 على Studio و100 على Agency؛ وأدنى منها تتسع المجموعة لملف واحد ويرد على الملف الثاني رمز 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.
نقاط النهاية
المرجع المولد، بكل حقل وكل شكل استجابة، هو واجهة Swagger UI التي تقدمها الخدمة على /docs/swagger، مع وثيقة OpenAPI على /v3/api-docs.
Webhooks
لأن المهام تعمل بشكل غير متزامن، دقائق للملفات الكبيرة، فاشترك في webhooks بدل الاستطلاع المستمر. سجل نقطة نهاية عبر 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 ثلاث مرات بتراجع أسي، فاجعل معالجك idempotent على id. ويجب أن تحل نقاط النهاية إلى عنوان عام، ويعاد التحقق من ذلك عند التسليم لا عند التسجيل فقط.
الأخطاء
الإخفاقات بتنسيق JSON: { "error": { "code": "…", "message": "…", "details": { … } } }. اقرأ code، لا الرسالة، فالرسائل يعاد صياغتها.