Lahjty API documentation

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

Never place a key in a URL or source repository. Use a separate key for each environment or integration.

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();

Complete generation controls

The endpoint selects the asset family. Copy type, image type, rendering style, audience, framework, brand context, image text, and voice persona are separate controls so integrations never need to hide important Lahjty behavior inside one prompt.

Preferred, required, and excluded keywords

Use keywords for natural preferences, required_keywords for phrases that must appear in every variant, and excluded_keywords for phrases that must never appear. Lahjty validates every variant, retries once when needed, and returns content_rejected instead of non-compliant copy.

Image text and visual controls

Set include_text to false for strict text-free mode. For an overlay, set include_text to true, supply overlay_text, and choose auto, ar, or en. auto preserves the supplied phrase; ar or en translates a mismatched phrase first. Lahjty then places the exact Arabic or English text deterministically over a clean generated base image instead of asking the image model to spell it. visual_keywords request scene concepts and excluded_visuals remove unwanted elements.

// 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"
}

The returned WhatsApp template is a draft. Your WhatsApp provider remains responsible for Meta template validation and approval.

• Send a unique Idempotency-Key for each logical POST operation.
• After a network interruption, retry the same body with the same key to replay the stored result.
• Use a new key for a new operation; changing the body under a used key returns 409.
• Honor Retry-After and RateLimit headers after a 429.
• Persist request_id and your external_id in application logs.

{
  "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…"
}

Production checklist

• Keep API keys in server-side secrets.
• Allow at least 60 seconds for generation and 120 seconds for complete campaigns.
• Put generated content through human review before a bulk send.
• Monitor GET /usage and alert before the balance is exhausted.
• Revoke old keys immediately after rotation.