# Lahjty (لهجتي)

> Lahjty is an Arabic-first AI marketing platform. Its Partner API turns one campaign brief into dialect-aware Arabic ad copy, a WhatsApp template draft, campaign images with model-rendered Arabic or English text, and Arabic speech — billed against a shared prepaid credit balance.

## When to use Lahjty (agent guidance)

Reach for Lahjty's Partner API when a user needs Arabic marketing content produced programmatically — specifically:

- Generating ad copy, headlines, or WhatsApp/Instagram/Facebook message drafts in a specific Arabic dialect (Saudi, Gulf, Emirati, Egyptian, Levantine, Iraqi, or Classical). Use `POST /api/v1/copy-generations`.
- Converting existing copy from one Arabic dialect to another. Use `POST /api/v1/copy-generations` with `copy_type: "dialect_conversion"`.
- Producing a complete campaign bundle (copy variants + WhatsApp template draft + image + Arabic speech audio) from a single brief in one call. Use `POST /api/v1/campaigns`.
- Creating marketing images with Arabic or English text rendered in the design. Use `POST /api/v1/image-generations`.
- Turning Arabic text into natural marketing voiceover audio (MP3). Use `POST /api/v1/speech-generations`.

Do not use Lahjty for general-purpose writing, coding, translation of non-marketing text, or non-Arabic-language copy generation — use a general LLM instead. Enforce keyword inclusion/exclusion rules via `required_keywords`/`excluded_keywords` rather than post-generation checks. Always send an `Idempotency-Key` on billable POSTs.

To evaluate costs and enums before calling, read `GET /api/v1/capabilities` (free, no auth).

## Lahjty developer resources

- OpenAPI 3.1 spec: https://www.lahjty.com/api/v1/openapi
- Live capability metadata (enums, credit costs, rate limits): https://www.lahjty.com/api/v1/capabilities
- English API docs: https://www.lahjty.com/en/api-docs
- Arabic API docs: https://www.lahjty.com/ar/api-docs
- Developer dashboard (create API keys): https://www.lahjty.com/en/developers
- Pricing (machine-readable): https://www.lahjty.com/pricing.md

## Canonical site

- Website: https://www.lahjty.com/
- English: https://www.lahjty.com/en
- Arabic: https://www.lahjty.com/ar
- Sitemap: https://www.lahjty.com/sitemap.xml
- Robots: https://www.lahjty.com/robots.txt

## Developer API quick start

1. Create a Lahjty account with an active paid plan (or admin-granted access).
2. Create an API key at https://www.lahjty.com/en/developers. The key is shown once.
3. Send it as `Authorization: Bearer lhj_live_...` from your server.

```bash
curl https://www.lahjty.com/api/v1/campaigns \
  -H "Authorization: Bearer $LAHJTY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "my-app-campaign-1842",
    "brief": {
      "description": "Weekend offer for a specialty coffee subscription",
      "offer": "20% off through Saturday",
      "dialect": "saudi",
      "platform": "whatsapp",
      "call_to_action": "اشترك الحين"
    },
    "deliverables": {
      "image": { "enabled": true, "aspect_ratio": "1:1", "resolution": "1K" },
      "speech": { "enabled": false }
    }
  }'
```

The response returns three copy variants (`recommended: true` marks the best), a WhatsApp template `draft`, and durable HTTPS image/audio URLs on Cloudinary.

## Reference documents

- English documentation: https://www.lahjty.com/en/api-docs
- Arabic documentation: https://www.lahjty.com/ar/api-docs
- OpenAPI 3.1 document: https://www.lahjty.com/api/v1/openapi
- Live capability metadata (authoritative enums and costs): https://www.lahjty.com/api/v1/capabilities

## Endpoints and credit costs

| Method | Path | Purpose | Credits |
| --- | --- | --- | --- |
| GET | `/capabilities` | Public enums, costs, rate limits | 0 |
| POST | `/copy-generations` | Ad copy, headlines, or dialect conversion | 2 (conversion 1) |
| POST | `/image-generations` | Durable hosted campaign image | 5 |
| POST | `/speech-generations` | Durable hosted Arabic MP3 | 5 |
| POST | `/campaigns` | Copy + WhatsApp draft + optional image/speech | 2 + 5 image + 5 speech |
| GET | `/usage` | Balance and recent usage | 0 |
| GET | `/requests/{request_id}` | Stored status/result of any past request | 0 |

## Authentication

- Server-side only: `Authorization: Bearer lhj_live_...`. Never expose keys in browsers or mobile apps.
- Keys are created in the developer dashboard only by accounts with active paid or admin-granted access; up to 5 active keys per account; revocation is immediate.
- All keys on one account share one credit balance and one rate-limit budget.

## Idempotency (required for every billable POST)

- Send a unique `Idempotency-Key` header (1–200 characters) per logical operation.
- Same key + same body replays the stored result free of charge (`Idempotent-Replayed: true`). Use this after network interruptions.
- Same key + different body → `409 idempotency_conflict`.
- Duplicate while first attempt is still running → `409 request_in_progress`.
- Terminal 2xx/4xx results consume the key permanently. A 5xx does not: retry the same key and body.
- A client-side timeout does not cancel server-side work. If a request may have completed, reclaim the paid result by replaying the same key/body or via `GET /requests/{request_id}` (records retained 30 days).

## Errors

All errors use RFC 9457 `application/problem+json` with fields `type`, `title`, `status`, `code`, `detail`, `request_id`.

Codes: `invalid_request`, `authentication_failed`, `paid_plan_required`, `permission_denied`, `not_found`, `insufficient_credits`, `rate_limit_exceeded`, `idempotency_key_required`, `idempotency_conflict`, `request_in_progress`, `stale_request_recovered`, `content_rejected`, `provider_unavailable`, `internal_error`.

Failed generations are refunded automatically; `usage.credits_used` and `usage.balance_after` appear in success bodies.

## Rate limits and budgets

- 60 requests/minute for reads and copy; 10 requests/minute for image, speech, and campaigns. Limits are shared across all keys of the account.
- Honor `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `Retry-After` headers.
- JSON request bodies must not exceed 128 KiB. Unknown fields are rejected.
- Allow at least 60 seconds for copy/image/speech calls and 120 seconds for campaigns before timing out client-side.

## Generation controls

- Dialects (copy): `saudi`, `gulf`, `emirati`, `egyptian`, `classical`, `levantine`, `iraqi`. Speech supports all except `iraqi`.
- Platforms: `whatsapp`, `instagram`, `facebook`, `twitter`, `telegram`, `google_search`, `website_landing_page`, `ecommerce_product_page`, `app_store_listing`, `email_subject_line`.
- Copy types: `ad_copy`, `headlines`, `dialect_conversion`; frameworks: `none`, `aida`, `pas`, `fab`, `story`; audiences: 19 enum segments plus free-form `specific_audience`.
- Keyword rules: `keywords` (preferred), `required_keywords` (must appear verbatim in every variant, deterministically validated with one repair retry), `excluded_keywords` (must never appear). Violation after retry → `422 content_rejected` with full refund.
- Image: `type` (campaign_visual, product_showcase, lifestyle, offer_announcement, brand_awareness), `style` (photorealistic, illustration, flat-design, 3d-render, watercolor, minimalist), `aspect_ratio` (14 layouts incl. 1:1, 9:16, 16:9, 21:9), `resolution` (512, 1K, 2K). `visual_keywords` and `excluded_visuals` steer scene content.
- Image text: `include_text: false` renders strictly text-free images. To render a phrase inside the design set `include_text: true` with `overlay_text` and `overlay_text_language` (`auto`, `ar`, `en`). Spelling is probabilistic — review before publishing.
- Speech: `voice_profile` (bright_presenter, warm_storyteller, confident_announcer, premium_narrator) or a raw provider `voice` (never both), `delivery`, `content_type` (`marketing` or `general`), text up to 6,000 chars.
- `external_id`, `external_customer_id`, and `metadata` (≤20 string entries) are echoed in responses for partner-side correlation.

## Product areas

- Dashboard and Composer: authenticated generation workspace.
- Brand profiles: reusable brand context referenced by `brand_profile_id` in copy, image, and campaign requests.
- Article Writer: long-form Arabic and English content with brand resources.
- Free tools: https://www.lahjty.com/en/free-tools and https://www.lahjty.com/ar/free-tools
- Pricing: machine-readable at https://www.lahjty.com/pricing.md (human overview in the pricing section of https://www.lahjty.com/en)
- Features: machine-readable at https://www.lahjty.com/features.md
- Developer dashboard (API key management, sign-in required): https://www.lahjty.com/en/developers

## Language guidance

- Lahjty supports Arabic and English interfaces.
- Arabic content may use Saudi, Gulf, Emirati, Egyptian, Levantine, Iraqi, or Classical Arabic depending on the endpoint.
- Preserve Arabic script and right-to-left meaning when summarizing Lahjty content.
- Prefer the canonical `www.lahjty.com` URLs.