Google Try On API: مثال برمجي ومتطلبات الصور وحلول لمشكلات التعطل

نظرة عملية على Virtual Try-On API من Google: مثال برمجي يعمل بلغة Python وبطلب REST، ومتطلبات صورة الشخص وصورة القطعة، وقائمة حلول مرتبة حسب العَرَض للأخطاء والنتائج الفارغة وسوء الملاءمة.

Google Try On API: مثال برمجي ومتطلبات الصور وحلول لمشكلات التعطل
Cristian Da Conceicao

ترسل صورتين إلى Virtual Try-On API من Google، إحداهما لشخص والأخرى لقطعة ملابس، وتتوقع صورة واضحة لذلك الشخص وهو يرتدي الملابس. أحيانًا تحصل على هذا بالضبط. وأحيانًا أخرى تحصل على خطأ 403 أو قائمة فارغة، أو سترة صوفية اختلطت بالجينز. يعود الفرق عادةً إلى ثلاثة أمور: الكود، والصور، وعدد من الإعدادات التي لا يقرأها أحد إلا عندما يتعطل كل شيء.

يتناول هذا المقال الأمور الثلاثة. ستحصل على مثال Python يعمل، وعلى طلب REST يمكنك لصقه في الطرفية، وعلى متطلبات الصور التي تحدد إن كانت النتيجة تبدو حقيقية، وعلى قائمة إصلاحات حسب كل عَرَض لحالات "لا يعمل". وبما أن نموذج Google لا يمكن تشغيله على PicassoIA، فهناك أيضًا قسم عن الحصول على نتائج مشابهة باستخدام نماذج متاحة عليها.

ما الذي تفعله الواجهة فعليًا

Virtual Try-On من Google نموذج على Vertex AI. تعطيه صورة لشخص وصورة واحدة أو أكثر للمنتج، فيعيد صورًا جديدة للشخص نفسه وهو يرتدي المنتج. لا يولّد نموذجًا عشوائيًا، بل يعدّل صورتك، فيحافظ على الوجه والوضعية والخلفية والنسب، ويستبدل الملابس.

مطوّر يكتب كودًا على مكتب خشبي لواجهة برمجة صور

💡 نموذج ذهني سريع: فكّر فيها كنقطة نهاية للتعديل، لا كنقطة نهاية لتحويل النص إلى صورة. لا يوجد أمر نصي إبداعي تضبطه. وجودة النتيجة تُحدَّد تقريبًا بالكامل بالصورتين اللتين ترفعهما.

معرّفات النموذج والإصدارات

هنا يتعثر الناس لأول مرة. تُدرج الصفحة المرجعية الإنجليزية الحالية من Google المعرّف virtual-try-on-001 نموذجًا مدعومًا، وهو موسوم بأنه متاح بشكل عام. لا تزال الصفحات القديمة وعدة نسخ مترجمة من الوثائق تذكر virtual-try-on-preview-08-04، وهو إصدار المعاينة. إذا نسخت مقتطفًا من برنامج تعليمي قديم ولم يستطع مشروعك استدعاء معرّف المعاينة، فسترى خطأ من نوع "model not found" يبدو كعلّة برمجية، لكنه في الحقيقة مشكلة في التسمية.

البندالتفاصيل
معرّف النموذج الحاليvirtual-try-on-001
معرّف المعاينة القديمvirtual-try-on-preview-08-04
المنصةVertex AI على Google Cloud
المدخلاتصورة شخص واحدة، وصورة منتج واحدة أو أكثر
مصادر الصوربايتات Base64 أو عنوان URI في Cloud Storage
عدد المتغيرات لكل طلبمن 1 إلى 4 (sampleCount)
حجم الإخراجيطابق نسبة الصورة المدخلة ودقتها

أين يقع PicassoIA من ذلك

نموذج Virtual Try-On من Google غير متاح على PicassoIA. إذا أردت معاينة الملابس افتراضيًا اليوم دون مشروع في Google Cloud، فالبدائل مشروحة لاحقًا في المقال، ومنها P Image Try On، الذي بُني لهذه المهمة تحديدًا.

مثال كود Python

إليك سير عمل بسيط يعمل. يفترض أنك تملك بالفعل مشروعًا في Google Cloud مع تفعيل Vertex AI وربط الفوترة.

الإعداد قبل أول استدعاء

  1. أنشئ مشروع Google Cloud أو اختر مشروعًا موجودًا، وفعّل Vertex AI API.
  2. ثبّت Google Gen AI SDK باستخدام pip install google-genai.
  3. صادق محليًا باستخدام gcloud auth application-default login.
  4. تأكد من أن حسابك يملك دورًا يسمح له باستدعاء نماذج Vertex AI.
  5. اختر منطقة. استخدم المنطقة نفسها في العميل وفي أي عنوان REST.

استدعاء Python

from google import genai
from google.genai.types import Image, ProductImage, RecontextImageSource

client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1",
)

result = client.models.recontext_image(
    model="virtual-try-on-001",
    source=RecontextImageSource(
        person_image=Image.from_file(location="person.jpg"),
        product_images=[
            ProductImage(product_image=Image.from_file(location="sweater.jpg"))
        ],
    ),
)

with open("tryon-result.png", "wb") as f:
    f.write(result.generated_images[0].image.image_bytes)

بعض الملاحظات على هذا المقتطف:

  • vertexai=True يخبر SDK أن يستخدم Vertex AI بدلًا من نقطة نهاية Gemini للمستهلكين. إن أغفلته فستفشل المصادقة بطرق مربكة.
  • product_images قائمة، لذا تسمح البنية بعدة قطع ملابس، لكن ابدأ بعنصر واحد حتى يعمل السير الأساسي.
  • تتطور أسماء الدوال والفئات في SDK بين الإصدارات. إذا فشل استيراد، فراجع المرجع الحالي في وثائق SDK لمعرفة الأسماء الدقيقة، بدلًا من تصحيح كودك أنت.

سترة صوفية بنّية اللون مطوية ومصوّرة من الأعلى على سطح أبيض

نسخة REST

إذا كنت تفضّل HTTP المباشر، أو تستدعي من لغة بلا SDK، فيبدو الطلب هكذا:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/virtual-try-on-001:predict" \
  -d '{
    "instances": [{
      "personImage": { "image": { "bytesBase64Encoded": "PERSON_BASE64" } },
      "productImages": [
        { "image": { "bytesBase64Encoded": "GARMENT_BASE64" } }
      ]
    }],
    "parameters": { "sampleCount": 1 }
  }'

تعود الاستجابة كقائمة من التنبؤات، يحمل كل منها صورة بصيغة base64. فكّ ترميزها واكتبها في ملف.

المعاملما الذي يفعلهانتبه إلى
sampleCountعدد المتغيرات، من 1 إلى 4عدد عينات أكبر يعني تكلفة أعلى لكل استدعاء
storageUriيرسل المخرجات إلى حاوية Cloud Storageيحتاج حساب الخدمة إلى صلاحية الكتابة
seedيجعل النتائج قابلة للتكرارأُفيد بأنه لا يعمل عند تفعيل العلامة المائية في إصدار المعاينة
safetySettingيضبط قوة المرشحالقيمة الافتراضية هي block_medium_and_above، وblock_none يحتاج إلى صلاحية خاصة

💡 نصيحة: أدرج إصدار المعاينة أيضًا معاملات مثل baseSteps وaddWatermark. لا تفترض وجودها في virtual-try-on-001. أرسل فقط المعاملات الموجودة في المرجع الحالي، وأضف الباقي واحدًا تلو الآخر.

قواعد الصور التي تهم فعلًا

لا تنشر مرجعية Google قائمة مرتبة بأحجام البكسل وحدود الملفات يمكنني التحقق منها، لذا تعامل مع القواعد أدناه على أنها متطلبات عملية مستخلصة من طريقة عمل نماذج التجربة، وليست حدودًا رسمية. أما الرسمي فهو أن الإخراج يحافظ على النسبة والدقة نفسهما لصورة الإدخال، فالصورة الصغيرة والمقصوصة تعطيك نتيجة صغيرة ومقصوصة.

رجل يقف مستقيمًا أمام جدار أبيض بسيط، والجسم كاملًا ظاهر

صورة الشخص

صورة الشخص هي الأساس. كل ما يحافظ عليه النموذج، يحافظ عليه من هنا.

  • الجسم كاملًا أو الجزء العلوي بوضوح، حسب القطعة. تحتاج السترة إلى ظهور الكتفين والذراعين. ويحتاج البنطال إلى ظهور الساقين.
  • وضعية مواجهة للكاميرا مع إبعاد الذراعين قليلًا عن الجذع. الذراعان المتشابكتان تخفيان الأكمام وتربكان التعديل.
  • خلفية بسيطة وخالية من الفوضى. الخلفيات المزدحمة تجعل حواف الأشياء تختلط ببعضها.
  • إضاءة متساوية وناعمة. الظلال الحادة عبر الصدر تُدمج في القطعة الجديدة.
  • ملابس أساسية ضيقة الملاءمة. الهودي الفضفاض تحت قميص ضيق يجبر النموذج على تخمين شكل الجسم.
  • شخص واحد فقط. صور المجموعات تنتج نتائج غير متوقعة.
  • دقة عالية، لأن الإخراج يرث الدقة.

صورة القطعة

ينبغي أن تبدو صورة المنتج كصورة كتالوج، لا كلقطة من أرضية غرفة نوم.

  • تصوير مسطح (Flat lay) أو على دمية شبح (Ghost mannequin) على خلفية بيضاء أو محايدة.
  • القطعة ظاهرة بالكامل، دون أكمام أو أطراف مقصوصة.
  • خالية من التجاعيد، لأن التجاعيد تُعامل كجزء من التصميم.
  • ألوان حقيقية، لأن المرشحات الثقيلة تغيّر الدرجة.
  • قطعة واحدة في كل صورة. قد ينجح عرض القطعة على عارضة في صورة المنتج، لكن اللقطة المسطحة النظيفة بداية أكثر أمانًا.

يدان تمسكان سترة صفراء خردلية على شماعة خشبية أمام جدار بسيط

نوع الصورةجيدسيئ
الشخصمواجهة للكاميرا، وضعية محايدة، إضاءة ناعمةذراعان متشابكتان، منظر جانبي، ظلال قاسية
الشخصجدار بسيط خلفهغرفة مزدحمة، مرايا، عدة أشخاص
القطعةتصوير مسطح، خلفية بيضاءمجعّدة على سرير، مطوية جزئيًا
القطعةالقطعة كاملة داخل الإطارياقة مقصوصة أو طرف مفقود
الاثنانمسافة كاميرا متطابقةلقطة قريبة جدًا لأحدهما، ولقطة بعيدة للآخر

💡 اختصار: صوّر الشخص التجريبي أمام جدار فارغ قرب نافذة، بالكاميرا على مستوى العين ومن مسافة حوالي مترين. هذا الإعداد الواحد يزيل معظم شكاوى "الملاءمة السيئة" قبل تشغيل أي كود.

لا يعمل؟ إصلاحات حسب العَرَض

عند حدوث عطل، ابدأ من نوع الخطأ بدلًا من التخمين. تقع معظم المشكلات في إحدى ثلاث فئات.

امرأة متعبة أمام مكتب تفرك صدغها وهي تنظر إلى حاسوب محمول

أخطاء الصلاحيات والنموذج

العَرَض: 403 أو "permission denied". إما أن Vertex AI API غير مفعّل في المشروع، أو الفوترة غير موجودة، أو أن حسابك يفتقر إلى دور يسمح له باستدعاء النماذج. فعّل الواجهة، ثم تأكد من الفوترة، ثم راجع الدور.

العَرَض: 404 أو "model not found". غالبًا ما تكون المشكلة في معرّف النموذج. بدّل إلى virtual-try-on-001، وتأكد من أن المنطقة في عميلك تطابق المنطقة في طلبك. قد يعمل معرّف النموذج في إعداد منطقة ما ثم يفشل في منطقة أخرى.

العَرَض: 401 أو رمز وصول منتهي. شغّل gcloud auth application-default login مرة أخرى. رموز الوصول القادمة من CLI تنتهي صلاحيتها، فقد يعمل السكربت صباحًا ويفشل بعد الظهر.

العَرَض: 429 أو "quota exceeded". لقد بلغت حد المعدل أو الحصة. أضف إعادة المحاولة مع تراجع أُسّي (exponential backoff)، وخفّض sampleCount، وراجع صفحة الحصص في وحدة تحكم Cloud. لم أجد أرقامًا منشورة يمكنني التحقق منها، لذا فوحدة التحكم هي المكان الذي تقرأ فيه حدودك الفعلية.

النتائج الفارغة وحجب الأمان

العَرَض: نجح الاستدعاء لكن قائمة التنبؤات فارغة أو تفتقد الصور. غالبًا ما يكون هذا مرشح الأمان. الإعداد الافتراضي يحجب المستوى المتوسط وما فوقه، وقد تُفعّل صور الأشخاص بملابس السباحة أو الملابس الداخلية أو الملابس الضيقة هذا المرشح حتى لو كانت النية بريئة. جرّب ملابس أساسية أكثر حيادًا للشخص في الصورة، ولقطة لقطعة لا تبدو كاشفة. لا تعتمد على block_none، لأن Google تقيّد الوصول إليه.

العَرَض: 400 أو "invalid argument". تحقّق من شكل الحمولة. يجب أن تكون Base64 بايتات خام دون بادئة data:image/png;base64,. يقبل personImage صورة واحدة، ويقبل productImages قائمة. نسيان الغلاف الذي يحيط بحقل الصورة هو الخطأ الكلاسيكي.

العَرَض: لا يفعل seed شيئًا أو يسبب خطأ. في إصدار المعاينة، لم يكن بالإمكان الجمع بين seed والعلامة المائية. إن احتجت إلى مخرجات قابلة للتكرار، فأزل معامل العلامة المائية أو أسقط seed، واختبر على معرّف النموذج الحالي.

لقطة قريبة لشخص يكتب على حاسوب محمول وعلى المكتب ملاحظات تصحيح أخطاء

الملاءمة السيئة والمخرجات الغريبة

إذا عمل API دون أخطاء لكن الصورة تبدو خاطئة، فالسبب دائمًا تقريبًا واحدة من الصورتين.

ما تراهالسبب المرجحالإصلاح
الأكمام تبدو مرسومة على الجسمذراعا الشخص متشابكتان أو مخفيتانأعد التصوير مع إبعاد الذراعين قليلًا
لون القطعة يبدو خاطئًاصورة منتج معدّلة بالمرشحاتاستخدم لقطة غير معدّلة وبإضاءة متساوية
نقشة القماش غير واضحةصورة قطعة منخفضة الدقةارفع أعلى دقة متاحة
قميص قديم ما زال ظاهرًا عند الياقةالملابس الأساسية فضفاضة أو متراكبةاستخدم طبقة أساسية بسيطة وضيقة الملاءمة
الإخراج يبدو مقصوصًاالإدخال كان مقصوصًاتذكّر أن الإخراج يطابق نسبة الإدخال
الوجه يبدو مختلفًا قليلًامساحة الوجه صغيرة في الصورةاقترب أكثر أو استخدم دقة أعلى

💡 ترتيب التشخيص الذي يوفّر الوقت: اختبر بأنظف صورة شخص وأنظف صورة قطعة تملكهما. إن نجح ذلك، فكودك سليم والمشكلة في صورك الحقيقية. وإن فشل، فالمشكلة في الإعداد وليست في الصور.

كيف تحصل على نتائج مشابهة على PicassoIA

Virtual Try-On من Google غير متاح على PicassoIA حتى الآن. للحصول على نتائج مشابهة اليوم، جرّب P Image Try On، المصمم لوضع قطعة ملابس على صورة شخص دون أي مشروع سحابي أو إعداد فوترة أو كود.

امرأة تلتقط صورة سيلفي بطول الجسم أمام مرآة في غرفة نوم مشمسة

خطوات P Image Try On

  1. افتح صفحة النموذج P Image Try On على PicassoIA.
  2. ارفع صورة الشخص، مع اتباع القواعد نفسها أعلاه: مواجهة للكاميرا، وخلفية بسيطة، وإضاءة ناعمة.
  3. ارفع صورة القطعة، ويفضّل أن تكون تصويرًا مسطحًا على خلفية بيضاء.
  4. شغّل النموذج وراجع النتيجة.
  5. إذا كانت الملاءمة غير دقيقة، فاستبدل صورة الأساس بأخرى أنظف وأعد التشغيل. تغييرات الصور الصغيرة أهم من أي شيء آخر.

نصائح حول المعاملات: اجعل صورتي الشخص والقطعة بجودة متقاربة، وتجنّب المرشحات الثقيلة، واختبر قطعة واحدة في كل مرة. إن كانت النتيجة قريبة لكنها غير مثالية، فاستخدمها كنقطة بداية لتعديل بدلًا من البدء من جديد.

نماذج أخرى تستحق التجربة

أحيانًا لا يكون نموذج تجربة مخصص هو الأداة المناسبة، مثلًا عندما تريد تغيير الخلفية أو ضبط الإضاءة أو إصلاح تفصيلة بعد التبديل. هذه النماذج تعمل جيدًا كأدوات مكمّلة:

النموذجالأفضل لـ
Nano Banana Proتعديلات صور عالية الجودة انطلاقًا من صورة مرجعية وتعليمات بلغة عادية
Nano Bananaتعديلات سريعة وتغيير الملابس بأمر نصي قصير
PicassoIA Image Editor Proتعديلات صور غير محدودة، مثل تنظيف الخلفية أو تغيير لون القطعة

سير عمل عملي: نفّذ تبديل القطعة باستخدام P Image Try On، ثم اصقل النتيجة باستخدام PicassoIA Image Editor Pro، مثلًا لإزالة ظل شارد أو إصلاح تجعيدة.

حالات استخدام واقعية

المتاجر الإلكترونية

تستخدم متاجر الأزياء التجربة الافتراضية لتقليل المرتجعات ومنح المتسوقين فكرة أفضل عن المقاس. يناسب API المتاجر التي تملك صور كتالوج نظيفة وتستطيع تشغيله كخطوة في الخادم الخلفي. يرفع المتسوق صورة، فيستدعي خادمك النموذج، ثم تظهر المعاينة في صفحة المنتج.

متسوقة تحمل هاتفًا ذكيًا باتجاه رف ملابس داخل متجر مضاء

بعض النقاط العملية لأصحاب المتاجر:

  • صوّر كل منتج بالطريقة نفسها، حتى تبقى مدخلات القطع متسقة.
  • اشرح للمتسوقين كيفية التقاط الصورة بمثال بسيط بجوار زر الرفع.
  • تعامل مع النتائج الفارغة بلباقة بعرض رسالة تطلب صورة مختلفة، بدلًا من شاشة خطأ.
  • خزّن النتائج مؤقتًا، لأن الاستدعاءات المتكررة تكلّف مالًا.

معاينات الأزياء الشخصية

ليس الجميع يملك متجرًا. إذا أردت ببساطة أن ترى كيف قد تبدو سترة قبل شرائها، فالمسار بلا كود أسرع من بناء مشروع سحابي. التقط صورة واضحة، وخذ صورة المنتج من صفحة متجر، وشغّل نموذج تجربة من المتصفح.

يدان ترتّبان صورًا لأزياء مطبوعة وعينات قماش على طاولة من خشب الجوز

هذا روتين بسيط يعمل جيدًا للاستخدام الشخصي:

  1. التقط صورة شخص واحدة جيدة وأعد استخدامها في كل تجربة.
  2. اختر ثلاث قطع بألوان أو قصّات مختلفة.
  3. شغّل كل واحدة وقارن النتائج جنبًا إلى جنب.
  4. احتفظ بأفضل اثنتين وتجاهل البقية.

💡 تذكير: معاينة التجربة تعرض تقديرًا فقط. انسدال القماش ومرونته والملاءمة الحقيقية تعتمد كلها على القطعة نفسها، لذا تعامل مع الصورة كدليل للون والأسلوب، لا كفحص دقيق للمقاس.

جرّب معاينات أزيائك الخاصة

Google Try On API قوي عندما تملك مشروعًا في Cloud وصورًا نظيفة وسببًا للأتمتة. وحين يعيقك الإعداد أو الحصة أو مرشح الأمان، لا يلزمك التوقف عن التجربة. افتح P Image Try On على PicassoIA، وارفع صورة أمام جدار بسيط وقطعة بتصوير مسطح، وشاهد النتيجة في بضع دقائق. ثم استخدم Nano Banana Pro أو PicassoIA Image Editor Pro لصقل التفاصيل.

جرّب ثلاث قطع وإعدادين للإضاءة وخلفية نظيفة واحدة، ثم قارن. ستلاحظ بسرعة أي عادات في تصوير الصور تهم فعلًا. مستعد لتجربة المزيد؟ تصفّح كل النماذج المتاحة على picassoia.com/en/all-models وابدأ بإنشاء صورك الخاصة اليوم.

شارك هذا المقال

اختر لغتك

Freeأنشئ صورًا وفيديوهات بالذكاء الاصطناعيمجانًا، دون بطاقة ائتمانعمليات توليد مجانية للبدءيشمل Seedance 2.5 Liteابدأ مجانًا الآن

مقالات ذات صلة