دليل واجهة Lahjty API

Authorization: Bearer lhj_live_••••••••••••

لا ترسل المفتاح في عنوان URL، ولا تحفظه في مستودع الشفرة، وخصص مفتاحاً لكل بيئة أو تكامل.

curl https://www.lahjty.com/api/v1/campaigns \
  -H "Authorization: Bearer $LAHJTY_API_KEY" \
  -H "Idempotency-Key: campaign-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "campaign-1842",
    "external_customer_id": "merchant-91",
    "brief": {
      "description": "Weekend offer for a specialty coffee subscription",
      "offer": "20% off through Saturday",
      "objective": "Drive WhatsApp orders",
      "dialect": "saudi",
      "platform": "whatsapp",
      "tone": "warm",
      "audience": "specific",
      "specific_audience": "Young professionals in Riyadh",
      "keywords": ["نهاية الأسبوع"],
      "required_keywords": ["قهوة مختصة"],
      "excluded_keywords": ["مجاني"],
      "call_to_action": "اطلب الآن"
    },
    "deliverables": {
      "copy": { "type": "ad_copy", "framework": "aida" },
      "image": {
        "enabled": true,
        "type": "product_showcase",
        "style": "photorealistic",
        "aspect_ratio": "1:1",
        "visual_keywords": ["specialty coffee", "Riyadh"],
        "excluded_visuals": ["people", "logos"],
        "include_text": true,
        "overlay_text": "اطلب الآن",
        "overlay_text_language": "ar"
      },
      "speech": {
        "enabled": false,
        "voice_profile": "confident_announcer",
        "delivery": "natural",
        "content_type": "marketing"
      }
    }
  }'

JavaScript / TypeScript

const response = await fetch(
  "https://www.lahjty.com/api/v1/campaigns",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.LAHJTY_API_KEY}`,
      "Idempotency-Key": crypto.randomUUID(),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      brief: {
        description: "Weekend coffee subscription offer",
        dialect: "saudi",
        platform: "whatsapp",
        required_keywords: ["قهوة مختصة"],
        excluded_keywords: ["مجاني"],
      },
      deliverables: {
        copy: { type: "ad_copy", framework: "aida" },
        image: {
          enabled: true,
          type: "offer_announcement",
          include_text: true,
          overlay_text: "Weekend offer",
          overlay_text_language: "en",
        },
        speech: { enabled: false },
      },
    }),
  },
);

if (!response.ok) {
  const problem = await response.json();
  throw new Error(`${problem.code}: ${problem.detail}`);
}

const campaign = await response.json();

جميع عناصر التحكم في التوليد

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

كلمات مفضلة ومطلوبة ومستبعدة

استخدم keywords للكلمات المفضلة طبيعياً، وrequired_keywords للعبارات التي يجب أن تظهر في كل نسخة، وexcluded_keywords للعبارات الممنوعة. تتحقق لهجتي من كل نسخة، وتحاول الإصلاح مرة، ثم تعيد content_rejected بدلاً من نص غير ملتزم.

النص داخل الصورة والتحكم البصري

اجعل include_text بقيمة false لصورة خالية تماماً من النص. لإضافة نص، استخدم true مع overlay_text واختر auto أو ar أو en. يحافظ auto على النص كما هو، بينما تترجم ar أو en النص عند اختلاف اللغة. بعدها تضع لهجتي النص العربي أو الإنجليزي نفسه بشكل حتمي فوق صورة أساسية نظيفة، بدلاً من مطالبة نموذج الصور بتهجئته. استخدم visual_keywords للعناصر المطلوبة وexcluded_visuals للعناصر الممنوعة.

// Strict text-free image
{
  "prompt": "Premium Saudi coffee campaign",
  "type": "product_showcase",
  "style": "photorealistic",
  "aspect_ratio": "1:1",
  "visual_keywords": ["Saudi coffee cup", "coffee beans"],
  "excluded_visuals": ["people", "logos"],
  "include_text": false
}

// Arabic overlay
{
  "prompt": "Premium Saudi coffee campaign",
  "type": "offer_announcement",
  "include_text": true,
  "overlay_text": "قهوتك، بطابعك",
  "overlay_text_language": "ar"
}

// English overlay; auto also preserves English input
{
  "prompt": "Premium Saudi coffee campaign",
  "type": "lifestyle",
  "include_text": true,
  "overlay_text": "Weekend coffee offer",
  "overlay_text_language": "en"
}

قالب واتساب المعاد هو مسودة. يبقى مزود واتساب لديك مسؤولاً عن التحقق وإرساله لاعتماد Meta.

• أرسل Idempotency-Key فريداً مع كل عملية POST منطقية.
• أعد استخدام المفتاح نفسه والجسم نفسه عند انقطاع الشبكة للحصول على النتيجة المخزنة.
• استخدم مفتاحاً جديداً لطلب جديد؛ يعيد تغيير الجسم مع مفتاح مستخدم خطأ 409.
• احترم Retry-After وترويسات RateLimit عند الخطأ 429.
• احفظ request_id وexternal_id في سجلاتك.

{
  "type": "https://www.lahjty.com/problems/insufficient-credits",
  "title": "Insufficient credits",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "This request costs 7 credits; the current balance is 3.",
  "request_id": "req_01…"
}

قائمة الإنتاج

• أبقِ المفاتيح في أسرار الخادم.
• ضع مهلة لا تقل عن 60 ثانية للتوليد و120 ثانية للحملات المتكاملة.
• اعرض المحتوى للمراجعة البشرية قبل إرسال حملة جماعية.
• راقب الرصيد عبر GET /usage وأضف تنبيهاً للرصيد المنخفض.
• ألغِ المفاتيح القديمة فور تدويرها.