رابط برنامه‌نویسی (API) PixelToPath

شروع سریع

سه مرحله و شما در حال تبدیل تصاویر به SVG از ترمینال، اسکریپت‌ها یا برنامه‌تان هستید.

اولین تبدیل شما

curl -sS -f -X POST https://api.pixel-to-path.com/v1/convert \
  -H "Authorization: Bearer ptp_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "colormode=binary" \
  -o logo.svg

مرجع تعاملی: pixel-to-path.com/v1/docs (OpenAPI/Swagger).

احراز هویت

هر درخواست با یک توکن Bearer در هدر Authorization احراز هویت می‌شود:

Authorization: Bearer ptp_live_0123abc…

• کلیدها محرمانه هستند: آن‌ها به صورت هش‌شده در سرور ذخیره می‌شوند و فقط یک‌بار هنگام ایجاد نمایش داده می‌شوند. کلید را گم کرده‌اید؟ آن را باطل کنید و کلید جدیدی بسازید.
• یک حساب، چند کلید: تا ۵ کلید فعال ایجاد کنید تا پروژه‌های خود را از هم جدا کنید. سهمیه رایگان ماهانه شما بر اساس حساب محاسبه می‌شود، نه هر کلید.
• ابطال فوری: یک کلید باطل‌شده، بلافاصله چه از طریق پورتال و چه در پاسخ API (برای حساب مسدودشده) از کار می‌افتد.

POST /v1/convert

آپلود + تبدیل در یک فراخوانی بدون حالت (stateless). هر فراخوانی موفق حداکثر ۱ اعتبار هزینه دارد — فراخوانی‌های ناموفق، نامعتبر یا محدودشده هزینه‌ای ندارند.

درخواست (multipart/form-data)

دو موتور، بر اساس انتخاب "colormode"

API دقیقاً از همان موتورهای مبدل رایگان آنلاین و برنامه دسکتاپ استفاده می‌کند:

تصاویر دقیقاً مانند وب‌سایت پیش‌پردازش می‌شوند: طولانی‌ترین ضلع قبل از تبدیل به ۱۵۰۰ پیکسل تغییر اندازه می‌دهد، و API نوع شناسایی‌شده تصویر (line_art، logo، photo یا illustration) را در هدر X-Detected-Type برمی‌گرداند.

پاسخ

در صورت موفقیت: کد 200 OK با نوع image/svg+xml — بدنه، همان فایل SVG است. هدرهای اطلاعاتی:

GET /v1/me

وضعیت حساب کاربری برای کلیدی که از آن استفاده شده است. رایگان — هرگز از سهمیه شما کم نمی‌شود و اعتباری کسر نمی‌گردد.

نمونه پاسخ

GET /v1/me
Authorization: Bearer ptp_live_…

{
  "key": { "name": "prod", "prefix": "ptp_live_0123abc", … },
  "usage": {
    "month": "2026-09", "free_used": 7, "free_limit": 10,
    "free_remaining": 3, "resets_at": "2026-10-01T00:00:00+00:00"
  },
  "credits": { "balance": 120 }
}

خطاها

هر خطا یک پوشش JSON سازگار برمی‌گرداند. فراخوانی‌های ناموفق هرگز اعتباری کسر نمی‌کنند.

HTTP/1.1 402 Payment Required
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly free quota used and no credits left.",
    "usage": { "free_used": 10, "free_limit": 10, "credits": 0 }
  }
}

محدودیت‌های نرخ (Rate limits)

محدودیت‌ها برای هر کلید API اعمال می‌شوند، نه هر IP، بنابراین یک دفتر مشترک یا سرور CI هرگز بابت ترافیک دیگران جریمه نمی‌شود.

قیمت‌گذاری

هر حساب جدید ۱۰ تبدیل رایگان در هر ماه دریافت می‌کند، بدون نیاز به کارت اعتباری. بیشتر نیاز دارید؟ تصاویر پیش‌پرداخت‌شده را بخرید — به هر مقدار (در بسته‌های ۵۰تایی)، با تخفیف‌های حجمی. آن‌ها هرگز منقضی نمی‌شوند و با سهمیه رایگان ماهانه شما ترکیب می‌شوند (ابتدا تبدیل‌های رایگان مصرف می‌شوند).

اعتباردهی خودکار: موجودی شما در عرض چند ثانیه پس از پرداخت از طریق وب‌هوک پرداخت به‌روز می‌شود. بازپرداخت‌ها، اعتبارهای خریداری‌شده را تا سقف موجودی فعلی کسر می‌کنند. پرداخت امن توسط Lemon Squeezy (مالیات بر ارزش افزوده به‌طور خودکار مدیریت می‌شود).

نمونه کدها

کپی، پیست و تطبیق دهید. API با فرمت ساده multipart/form-data کار می‌کند، بنابراین هر کلاینت HTTP‌ای کار خواهد کرد.

cURL

curl -sS -f -X POST https://api.pixel-to-path.com/v1/convert \
  -H "Authorization: Bearer ptp_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "colormode=color" \
  -F "filter_speckle=4" \
  -o photo.svg

پایتون

import requests

resp = requests.post(
    "https://api.pixel-to-path.com/v1/convert",
    headers={"Authorization": "Bearer ptp_live_YOUR_KEY"},
    files={"file": open("photo.jpg", "rb")},
    data={"colormode": "color", "filter_speckle": 4},
)
resp.raise_for_status()
print(resp.headers["X-Credits-Remaining"], "credits left")
with open("photo.svg", "wb") as f:
    f.write(resp.content)

جاوا اسکریپت

const form = new FormData();
form.append("file", new Blob([imageBytes]), "photo.jpg");
form.append("colormode", "color");

const resp = await fetch("https://api.pixel-to-path.com/v1/convert", {
  method: "POST",
  headers: { "Authorization": "Bearer ptp_live_YOUR_KEY" },
  body: form,
});
if (!resp.ok) {
  const { error } = await resp.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const svg = await resp.text();
console.log(resp.headers.get("X-Credits-Remaining"), "credits left");

سوالات متداول