API پرو مجازی لباس چیست و چه زمانی به آن نیاز دارید؟
API رابطی است که سایت یا اپلیکیشن شما از طریق آن عکس شخص و عکس لباس را به سرویس پردازش میفرستد و پیشنمایش دریافت میکند. رابط خرید، انتخاب محصول و نمایش نتیجه در فروشگاه شما باقی میماند؛ ساخت تصویر را سرویس انجام میدهد. این پیشنمایش، اندازه واقعی لباس یا مناسب بودن سایز را تضمین نمیکند.
این راهنما برای توسعهدهندهای است که میخواهد اتصال چکاستایل را طراحی کند. قرارداد درخواست و پاسخ با مستندات رسمی API چکاستایل و پیادهسازی فعلی در ۱۱ مهر ۱۴۰۵ تطبیق داده شده است. برای پارامترهای دقیق همیشه مستندات را مرجع قرار دهید؛ این مقاله مسیر اجرا و تصمیمهای اتصال را توضیح میدهد.
اگر فروشگاه ووکامرسی دارید، ابتدا راهنمای افزونه پرو مجازی ووکامرس را بررسی کنید. API مستقیم زمانی مناسب است که اپلیکیشن، فروشگاه اختصاصی یا رابط سفارشی دارید. برای بررسی کاربرد تجاری و اجرای پایلوت، راهنمای پرو مجازی برای فروشگاه اینترنتی را بخوانید.
پیش از فعالسازی عمومی، چکلیست تست کیفیت پرو مجازی فروشگاه را با فرم ثبت تلاشها و معیار پذیرش خروجی اجرا کنید.
معماری اتصال: مرورگر، سرور فروشگاه و سرویس پرو
- مشتری در صفحه محصول عکس خود را با رضایت بارگذاری میکند؛ عکس همان کالا از دادههای فروشگاه انتخاب میشود.
- مرورگر تصاویر را به سرور فروشگاه میفرستد. سرور نوع و حجم فایل، دسترسی کاربر و محدودیت تعداد درخواست را بررسی میکند.
- سرور فروشگاه با کلید API به چکاستایل درخواست میدهد. کلید در متغیر محیطی یا مخزن امن تنظیمات سرور نگهداری میشود.
- سرور نتیجه یا وضعیت پردازش را به مرورگر برمیگرداند. رابط کاربری وضعیت انتظار، موفقیت یا خطا را نمایش میدهد.
کلید API را در JavaScript مرورگر، اپلیکیشن قابل دانلود یا HTML قرار ندهید. این کلید به حساب و اعتبار شما وصل است. محدودسازی درخواست کاربر در سرور فروشگاه از مصرف کنترلنشده اعتبار جلوگیری میکند. رضایت و نحوه نگهداری عکس را قبل از بارگذاری توضیح دهید؛ راهنمای امنیت عکس در پرو مجازی نقطه شروع است.
آماده کردن کلید و دو تصویر ورودی
از صفحه حساب و اعتبار کلید API بسازید و اعتبار حساب را بررسی کنید. طبق مستندات، هر تصویر موفق یک اعتبار مصرف میکند. قیمت یا سهمیه ثابت را در کد ننویسید؛ وضعیت حساب خود را مرجع قرار دهید.
دو فیلد اجباری person_image و garment_image هستند. هر کدام باید Data URL شامل پیشوند نوع فایل و محتوای Base64 باشند؛ ارسال آدرس اینترنتی عکس به جای این رشته با قرارداد فعلی سازگار نیست. فرمتهای مستند JPG، PNG و WebP و سقف اعلامشده ۵ مگابایت برای هر عکس است. برای حاشیه اطمینان، ورودیها را کوچکتر نگه دارید؛ Base64 حجم رشته ارسالی را افزایش میدهد.
پسوند فایل بهتنهایی برای تشخیص نوع کافی نیست؛ نوع واقعی و محتوای فایل را در سرور بررسی کنید. عکس لباس باید متعلق به همان محصول انتخابشده باشد. برای کیفیت ورودی از راهنمای عکس مناسب پرو مجازی کمک بگیرید؛ ورودی نامناسب میتواند نتیجه را مخدوش کند.
نمونه درخواست API پرو مجازی با cURL
یک فایل request.json با ساختار زیر بسازید. عبارتهای BASE64_PERSON و BASE64_GARMENT جاینگهدارند؛ قبل از اجرا باید با محتوای واقعی تصویر جایگزین شوند.
{
"person_image": "data:image/jpeg;base64,BASE64_PERSON",
"garment_image": "data:image/jpeg;base64,BASE64_GARMENT"
}دستور زیر را در سرور یا محیط توسعه امن اجرا کنید. متغیر CHECKSTYLE_API_KEY باید از قبل در محیط تنظیم شده باشد؛ مقدار واقعی آن را در فایل عمومی ذخیره نکنید.
curl --max-time 180 https://checkstyle.ir/api/v1/try-on \
-H "Authorization: Bearer ${CHECKSTYLE_API_KEY}" \
-H "Content-Type: application/json" \
--data-binary @request.jsonدر حالت همزمان، نتیجه در همان پاسخ برمیگردد. مستندات زمان انتظار دستکم ۱۸۰ ثانیه را توصیه میکنند؛ timeout پراکسی و هاست فروشگاه را هم هماهنگ کنید. این زمان، تضمین سرعت پاسخ نیست.
{
"image": "data:image/png;base64,...",
"credits_remaining": 4
}عدد اعتبار و رشته تصویر در این مثال نمایشیاند. در پاسخ واقعی، image یک Data URL است و نوع خروجی ممکن است PNG، JPEG یا WebP باشد. پس از بررسی نوع مجاز میتوانید آن را نمایش دهید یا بخش Base64 را برای ذخیره رمزگشایی کنید. داده کامل تصویر یا کلید را در لاگ ثبت نکنید.
پردازش مرحلهای برای فروشگاههایی با محدودیت timeout
اگر هاست نمیتواند اتصال طولانی را باز نگه دارد، درخواست را به مسیر مرحلهای بفرستید. پاسخ اولیه با HTTP 202 به معنی پذیرش پردازش است؛ ساخت تصویر هنوز تمام نشده است.
POST /api/v1/try-on?async=1
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
→ { "token": "REQUEST_ID", "status": "processing" }
GET /api/v1/status/REQUEST_ID
Authorization: Bearer YOUR_API_KEY
→ { "status": "processing" }
→ { "status": "completed", "image": "data:image/png;base64,..." }
→ { "status": "failed", "error": "..." }بدنه POST همان دو تصویر مرحله قبل است. REQUEST_ID را از پاسخ واقعی دریافت کنید و وضعیت را از سرور فروشگاه با همان کلید پیگیری کنید. برای polling فاصله محدود و سقف انتظار تعیین کنید؛ مثلاً چند ثانیه بین بررسیها، با افزایش فاصله در انتظار طولانی. این یک پیشنهاد طراحی رابط است، نه نرخ مجاز تضمینشده سرویس.
در پیادهسازی فعلی، وضعیت درخواست تا یک ساعت نگهداری میشود و با راهاندازی مجدد سرویس ممکن است از دسترس خارج شود. 404 میتواند نشانه درخواست ناموجود، منقضی یا متعلق به حساب دیگر باشد. نتیجه موردنیاز را طبق سیاست نگهداری خود دریافت کنید و روی این مسیر بهعنوان آرشیو دائمی حساب نکنید.
قطع اتصال یا timeout را خودکار به معنی شکست ساخت تصویر نگیرید. ارسال دوباره POST ممکن است پردازش تازه و مصرف اعتبار جدا ایجاد کند. دکمه ارسال را هنگام پردازش غیرفعال کنید، شناسه درخواست را نگه دارید و برای تکرار ساخت از کاربر تصمیم روشن بگیرید.
خطاهای API و واکنش مناسب فروشگاه
- 400: قالب JSON یا تصاویر نامعتبرند؛ ورودی را اصلاح کنید و همان درخواست خراب را تکرار نکنید.
- 401: کلید نامعتبر یا غیرفعال است؛ تنظیمات سرور و وضعیت کلید را بررسی کنید.
- 402: اعتبار کافی نیست؛ پیام قابل فهم نمایش دهید و شارژ حساب را به مدیر فروشگاه ارجاع دهید.
- 415: نوع محتوای درخواست اشتباه است؛ هدر
Content-Type: application/jsonرا ارسال کنید. - 502 یا 503: ساخت تصویر شکست خورده یا سرویس فعلاً در دسترس نیست. طبق قرارداد فعلی، درخواست ناموفق اعتبار نهایی مصرف نمیکند؛ تلاش دوباره را محدود و با فاصله اجرا کنید.
- 404 در مسیر وضعیت: شناسه، حساب مالک و زمان گذشته را بررسی کنید؛ پیام «وضعیت درخواست در دسترس نیست» از نمایش نتیجه ساختگی روشنتر است.
در حالت مرحلهای، HTTP 200 بهتنهایی به معنی موفقیت تصویر نیست؛ مقدار status را بررسی کنید. تنها completed به همراه تصویر معتبر اجازه نمایش خروجی میدهد. هنگام انتظار پیام «در حال ساخت پیشنمایش» و هنگام شکست مسیر قابل فهم برای تلاش دوباره ارائه کنید.
چکلیست پیش از فعال کردن اتصال برای مشتریان
- با عکس شخص دارای رضایت و چند محصول واقعی، تطابق رنگ، طرح و جزئیات لباس را بررسی کنید.
- خطاهای کلید نامعتبر، کمبود اعتبار، تصویر خراب و قطع ارتباط را در محیط آزمایش پوشش دهید.
- در موبایل، بارگذاری عکس، انتظار و نمایش نتیجه را بررسی کنید؛ درخواست تکراری ناشی از چند کلیک را محدود کنید.
- رویدادهای شروع، پذیرش پردازش، موفقیت و شکست را بدون عکس یا کلید ثبت کنید؛ هزینه هر خروجی قابل استفاده را بسنجید.
- کنار پیشنمایش، عکس اصلی کالا و جدول سایز را در دسترس بگذارید. تصویر مولد ممکن است رنگ یا جزئیات را تغییر دهد و جای اندازهگیری را نمیگیرد.
- ابتدا روی گروه محدودی از محصولات فعال کنید. اثر بر خرید را با مقایسه کنترلشده بسنجید؛ استفاده از پرو بهتنهایی اثبات افزایش فروش نیست.
پرسشهای رایج درباره اتصال API پرو مجازی
آیا میتوان API چکاستایل را مستقیم از مرورگر صدا زد؟
کلید باید در سرور فروشگاه نگهداری شود. مرورگر درخواست را به سرور شما میفرستد و سرور با کلید API به چکاستایل متصل میشود.
آیا میتوان لینک عکس محصول را به API فرستاد؟
در قرارداد فعلی، person_image و garment_image باید Data URL شامل Base64 عکس باشند؛ URL معمولی جایگزین این دو فیلد نیست.
فرق درخواست همزمان و مرحلهای چیست؟
در حالت همزمان تصویر در همان پاسخ میآید. حالت مرحلهای ابتدا شناسه میدهد و سرور شما با همان کلید، وضعیت processing، completed یا failed را پیگیری میکند.
آیا درخواست ناموفق اعتبار مصرف میکند؟
طبق مستندات فعلی، هر تصویر موفق یک اعتبار مصرف میکند و شکست ساخت اعتبار نهایی مصرف نمیکند. timeout سمت فروشگاه لزوماً به معنی شکست پردازش نیست؛ پیش از ارسال دوباره وضعیت را بررسی کنید.
API پرو مجازی سایز مناسب لباس را مشخص میکند؟
خیر. خروجی یک پیشنمایش تصویری است و فیت، راحتی یا سایز واقعی را تضمین نمیکند؛ جدول سایز و مشخصات همان کالا باید در مسیر خرید باقی بمانند.
اولین اتصال را با یک محصول شروع کنید
