Campaign images | Lahjty API

Generate durable campaign images with layout, style, visual constraints, brand context, and optional model-rendered text.

POST/image-generations

Strict text-free product image

include_text=false asks the image model for no labels, logos, numbers, signage, or pseudo-text.

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

Offer image with Arabic model-rendered text

The image model renders the phrase as part of the visual. Spelling is probabilistic, so review it before publishing. A 2K image costs 8 credits instead of 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"
}'

For your own product and logo, upload each with its explicit reference or logo role, then send reference_storage_ids and a separate logo_storage_id. Generic images and Ad Library generation accept logo_mode: model uses the supplied mark as an image-model reference, overlay places it deterministically, and none omits it. With a logo, model is the default. Model rendering may alter the mark; overlay preserves the original.

Adapt an Ad Library reference

Search by brief, or copy an ad ID from Lahjty and inspect that exact ID. Search and detail require ad-library:read; preparation and uploads require ad-library:write; generation requires images:write. Suggestions reflect metadata relevance, not measured performance.

Search with brief and filters, then choose an ID from the returned items. A copied ID can skip search.
Read /ad-library/{id}. If preparation.status is ready, use contract.fields and reference_requirement directly. Otherwise disclose preparation.analysis_credits and obtain authorization before POST /prepare. An existing prepared contract costs zero; new analysis currently costs one credit.
Upload required, user-authorized product references or a logo through /ad-library/uploads. Use the returned storage IDs from the same account; never substitute another account's ID.
Fill template_fields using the actual field IDs from the contract and the user's facts. Generate only after approval of the image cost: 5 credits at 1K (the default) or 8 credits when resolution is 2K. Preserve the exact body and Idempotency-Key after a timeout; recover by request ID before retrying.

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

Find a fitting reference

Read-only catalog search; no credits charged.

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

Inspect the copied ad ID

Replace the placeholder with the exact copied 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

Prepare only when needed

Only after checking preparation state and authorizing its cost.

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

Upload a user-owned product reference

Use an authorized image URL and retain the returned storage ID.

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

Generate from the selected contract

Replace placeholder field and storage IDs with the inspected contract and upload result. Omit reference_storage_ids only when references are optional. These are request examples, not executed results.

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"
  ]
}'

Controls that matter

type selects campaign visual, product showcase, lifestyle, offer announcement, or brand awareness.
visual_keywords / excluded_visuals preserve wanted concepts and explicitly remove unwanted elements.
brand_profile_id adds a brand profile owned by the calling account without inventing a logo.