صور الحملات

أنشئ صور حملات مستضافة مع التحكم في التنسيق والأسلوب والعناصر البصرية وسياق العلامة والنص الاختياري داخل الصورة.

POST/image-generations

صورة منتج بلا أي نص

include_text=false يطلب صورة بلا ملصقات أو شعارات أو أرقام أو نص وهمي.

curl --request POST \
  --url https://www.lahjty.com/api/v1/image-generations \
  --header "Authorization: Bearer $LAHJTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: image-coffee-1846" \
  --data '{
  "prompt": "Premium Saudi specialty coffee campaign on a warm stone counter",
  "type": "product_showcase",
  "output_language": "ar",
  "market": "SA",
  "dialect": "saudi",
  "platform": "instagram",
  "style": "photorealistic",
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "visual_keywords": [
    "Saudi coffee cup",
    "coffee beans",
    "warm morning light"
  ],
  "excluded_visuals": [
    "people",
    "logos",
    "text"
  ],
  "include_text": false,
  "external_customer_id": "merchant-91"
}'

Example response

response.json

{
  "id": "img_01jexample",
  "object": "image_generation",
  "request_id": "req_01jexample",
  "status": "completed",
  "image": {
    "url": "https://example.convex.cloud/api/storage/example",
    "mime_type": "image/png",
    "width": 1024,
    "height": 1024,
    "bytes": 842331
  },
  "aspect_ratio": "1:1",
  "resolution": "1K",
  "text_policy": {
    "mode": "none",
    "deterministic": false,
    "renderer": null
  },
  "usage": {
    "credits_used": 5,
    "balance_after": 493
  }
}

POST/image-generations

إعلان مع نص عربي داخل الصورة

النص يُكتب بواسطة نموذج الصورة وقد لا تكون تهجئته حتمية؛ راجعه قبل النشر. وتكلف الصورة 8 عملات بدقة 2K بدلاً من 5.

curl --request POST \
  --url https://www.lahjty.com/api/v1/image-generations \
  --header "Authorization: Bearer $LAHJTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: image-offer-1847" \
  --data '{
  "prompt": "Premium weekend specialty coffee promotion",
  "type": "offer_announcement",
  "output_language": "ar",
  "market": "SA",
  "dialect": "saudi",
  "platform": "whatsapp",
  "style": "photorealistic",
  "aspect_ratio": "4:5",
  "resolution": "2K",
  "include_text": true,
  "overlay_text": "خصم 20٪ هذا الأسبوع",
  "overlay_text_language": "ar"
}'

لاستخدام صورة منتجك وشعارك، ارفع كلاً منهما بدوره reference أو logo، ثم أرسل reference_storage_ids ومعرّف logo_storage_id منفصلاً. تقبل الصور العامة وإنشاء إعلانات المكتبة logo_mode: يستخدم model الشعار مرجعاً للنموذج، ويضعه overlay كما هو، ويحذفه none من النتيجة. عند إرفاق شعار يكون model هو الافتراضي. قد يغيّر النموذج شكل العلامة؛ ويحافظ overlay على الأصل.

خصّص إعلاناً من المكتبة

ابحث بوصف الطلب، أو انسخ معرّف إعلان من لهجتي وافحصه مباشرة. يتطلب البحث والتفاصيل صلاحية ad-library:read، والتحضير والرفع صلاحية ad-library:write، والإنشاء صلاحية images:write. الاقتراحات تعبّر عن ملاءمة البيانات الوصفية وليست قياساً للأداء.

ابحث باستخدام brief والمرشحات، ثم اختر معرّفاً من النتائج. إذا نسخت معرّفاً، يمكنك تجاوز البحث.
اقرأ /ad-library/{id}. إذا كانت preparation.status تساوي ready، فاستخدم contract.fields وreference_requirement مباشرة. وإلا فوضّح preparation.analysis_credits واطلب الموافقة قبل POST /prepare. العقد المحضّر مسبقاً مجاني، والتحليل الجديد يكلف حالياً رصيداً واحداً.
ارفع مراجع المنتج المطلوبة أو الشعار المصرّح بهما عبر /ad-library/uploads. استخدم معرّفات التخزين المعادة للحساب نفسه؛ ولا تستخدم معرّفات حساب آخر.
املأ template_fields بمعرّفات الحقول الفعلية من العقد وبمعلومات المستخدم. أنشئ الإعلان بعد الموافقة على تكلفة الصورة: 5 أرصدة بدقة 1K الافتراضية، أو 8 أرصدة عندما تكون resolution بقيمة 2K. احتفظ بالجسم نفسه وIdempotency-Key عند انتهاء المهلة، واسترجع حالة الطلب قبل إعادة المحاولة.

GET/ad-library?brief=Saudi%20coffee%20morning%20offer&locale=en&limit=5

ابحث عن مرجع مناسب

بحث للقراءة فقط دون خصم أرصدة.

curl --request GET \
  --url https://www.lahjty.com/api/v1/ad-library?brief=Saudi%20coffee%20morning%20offer&locale=en&limit=5 \
  --header "Authorization: Bearer $LAHJTY_API_KEY"

GET/ad-library/REPLACE_WITH_AD_ID

افحص معرّف الإعلان المنسوخ

استبدل القيمة التوضيحية بالمعرّف المنسوخ نفسه.

curl --request GET \
  --url https://www.lahjty.com/api/v1/ad-library/REPLACE_WITH_AD_ID \
  --header "Authorization: Bearer $LAHJTY_API_KEY"

POST/ad-library/REPLACE_WITH_AD_ID/prepare

حضّر الإعلان عند الحاجة فقط

بعد فحص حالة التحضير والموافقة على تكلفته فقط.

curl --request POST \
  --url https://www.lahjty.com/api/v1/ad-library/REPLACE_WITH_AD_ID/prepare \
  --header "Authorization: Bearer $LAHJTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: prepare-selected-ad-001" \
  --data '{
  "locale": "ar"
}'

POST/ad-library/uploads

ارفع مرجع منتج يملكه المستخدم

استخدم رابط صورة مصرحاً به واحتفظ بمعرّف التخزين المعاد.

curl --request POST \
  --url https://www.lahjty.com/api/v1/ad-library/uploads \
  --header "Authorization: Bearer $LAHJTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: upload-product-reference-001" \
  --data '{
  "url": "https://your-brand.example/product.jpg",
  "role": "reference"
}'

POST/ad-library/REPLACE_WITH_AD_ID/generations

أنشئ الإعلان من العقد المختار

استبدل معرّفات الحقول والتخزين التوضيحية بقيم العقد ونتيجة الرفع. احذف reference_storage_ids فقط عندما تكون المراجع اختيارية. هذه أمثلة طلبات وليست نتائج منفذة.

curl --request POST \
  --url https://www.lahjty.com/api/v1/ad-library/REPLACE_WITH_AD_ID/generations \
  --header "Authorization: Bearer $LAHJTY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: generate-selected-ad-001" \
  --data '{
  "locale": "ar",
  "aspect_ratio": "1:1",
  "template_fields": {
    "REPLACE_WITH_CONTRACT_FIELD_ID": "قهوة الصباح"
  },
  "reference_storage_ids": [
    "REPLACE_WITH_OWNED_STORAGE_ID"
  ]
}'

عناصر التحكم المهمة

type يحدد صورة حملة أو عرض منتج أو أسلوب حياة أو إعلان عرض أو وعي بالعلامة.
visual_keywords / excluded_visuals يحافظان على العناصر المطلوبة ويستبعدان العناصر غير المرغوبة.
brand_profile_id يضيف ملف علامة يملكه الحساب دون اختراع شعار.