واجهة API للتجربة الافتراضية

المصادقة

أرسل المفتاح في ترويسة Authorization. المفاتيح التجريبية تبدأ بـ hk_test_ والحية بـ hk_live_.

Authorization: Bearer hk_live_xxxxxxxxxxxxxxxx

إنشاء تجربة

POST https://houshstyle.ir/api/v1/try-on/ — multipart/form-data أو JSON مع روابط الصور

curl -X POST https://houshstyle.ir/api/v1/try-on/ \
  -H "Authorization: Bearer $HUSH_KEY" \
  -F person_image=@person.jpg \
  -F garment_image=@dress.jpg \
  -F garment_type=w_gown \
  -F garment_image_2=@heels.jpg \
  -F garment_type_2=w_heels \
  -F resolution=hd \
  -F webhook_url=https://your-app.com/hooks/tryon

الاستجابة (202):

{"id": "8b1c…", "status": "queued", "result_url": null, "credits_charged": 2, ...}

استلام النتيجة

GET https://houshstyle.ir/api/v1/try-on/{id}/

الحالات: queued وprocessing وcompleted وfailed. عند completed يكون result_url رابط الصورة النهائية. عند الفشل يُعاد الرصيد تلقائياً (refunded=true).

مثال Python

import requests, time
H = {"Authorization": "Bearer hk_live_..."}
r = requests.post("https://houshstyle.ir/api/v1/try-on/", headers=H,
    files={"person_image": open("me.jpg", "rb"), "garment_image": open("dress.jpg", "rb")},
    data={"garment_type": "w_cocktail"})
job = r.json()
while job["status"] in ("queued", "processing"):
    time.sleep(2)
    job = requests.get(f"https://houshstyle.ir/api/v1/try-on/{job['id']}/", headers=H).json()
print(job["result_url"])

مثال JavaScript (Node)

const fd = new FormData();
fd.append("person_image_url", "https://cdn.example.com/u/123.jpg");
fd.append("garment_id", "42");
const res = await fetch("https://houshstyle.ir/api/v1/try-on/", {
  method: "POST", headers: { Authorization: `Bearer ${process.env.HUSH_KEY}` }, body: fd });
console.log(await res.json());

مثال PHP

$ch = curl_init("https://houshstyle.ir/api/v1/try-on/");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("HUSH_KEY")],
  CURLOPT_POSTFIELDS => ["person_image" => new CURLFile("me.jpg"), "garment_image" => new CURLFile("coat.jpg"),
                         "garment_type" => "m_blazer"]]);
echo curl_exec($ch);

Webhook

عند انتهاء المعالجة يُرسل طلب POST بجسم JSON والترويسات التالية إلى webhook_url:

X-Hush-Timestamp: 1760780000
X-Hush-Signature: sha256=HMAC_SHA256(webhook_secret, timestamp + "." + raw_body)

{"event": "tryon.completed", "data": {"id": "...", "status": "completed", "result_url": "..."}}

# Python verify
import hmac, hashlib
expected = hmac.new(SECRET.encode(), ts.encode() + b"." + body, hashlib.sha256).hexdigest()
assert hmac.compare_digest("sha256=" + expected, signature)

نقاط نهاية أخرى

• GET /api/v1/usage/ — الرصيد المتبقي واستهلاك هذا الشهر
• GET /api/v1/garments/ — القطع المتاحة للتجربة (عامة + منتجاتك)
• GET /api/v1/try-on/list/ — آخر ٥٠ تجربة

رموز الأخطاء

أنواع الملابس والإكسسوارات (garment_type)

المفاتيح u_ للجنسين. الأسماء الإنجليزية القديمة (مثل cocktail dress) ما زالت مقبولة.

ملابس — نسائي

ملابس — رجالي

أطقم وقطع واحدة — نسائي

أطقم وقطع واحدة — رجالي

أطقم وقطع واحدة — للجنسين

إكسسوارات — نسائي

إكسسوارات — رجالي

إكسسوارات — للجنسين